svn-log-tool/docs/README_Web.md

SVN 日志 Web 工作台

功能概览

Web 工作台将现有 CLI 能力封装为可视化页面与 REST API，支持以下流程：

1. SVN 参数录入与连接测试
2. 异步抓取日志并导出 Markdown
3. 使用 DeepSeek 或 OpenAI 兼容接口分析 Markdown 并生成 Excel
4. 查看任务历史（状态、进度、错误、产物），支持筛选、分页与取消运行中任务
5. 下载输出文件、配置 API Key 与输出目录
6. 工作台展示系统健康状态（输出目录可写性、API Key 配置、任务统计）

批量抓取策略：多个项目按顺序执行（前一个项目完成后才开始下一个）。

启动方式

在仓库根目录执行：

# Docker 一键启动（推荐）
make up

备用方式（本机 Java + Maven）：

mvn spring-boot:run -Dspring-boot.run.mainClass=com.svnlog.web.WebApplication

启动后访问：

http://localhost:18088

页面说明

• 工作台：最近任务统计与最近产物
• SVN 日志抓取：SVN 地址、账号密码、版本区间、过滤用户（支持预置项目下拉与自定义地址）
• AI 工作量分析：选择 Markdown 文件、工作周期、输出文件名
• 任务历史：异步任务状态与产物列表，支持筛选、分页、取消任务
• 系统设置：AI 提供商、DeepSeek API Key、OpenAI 兼容 Base URL/API Key/阶段模型、输出目录、默认 SVN 预置项目

输出目录

• 默认输出目录：outputs/
• Markdown 输出：outputs/md/*.md
• Excel 输出：outputs/excel/*.xlsx
• 任务持久化：outputs/task-history.json（重启后可恢复历史）

AI 提供商设置

• DeepSeek：沿用现有两阶段分析链路，读取 DeepSeek API Key
• OpenAI兼容：使用 baseURL + apiKey + stage1Model + stage2Model 调用兼容 /chat/completions 接口
• OpenAI 兼容默认值：
  • baseURL=http://127.0.0.1:5001/v1
  • stage1Model=deepseek-v4-flash
  • stage2Model=deepseek-v4-pro

DeepSeek API Key 读取优先级

1. AI 分析请求中的临时 apiKey
2. 设置页保存的运行时 apiKey
3. 环境变量 DEEPSEEK_API_KEY

建议在生产环境优先使用环境变量，避免敏感信息暴露。

SVN 预设来源与调用方式

• SVN 地址统一维护在 application.properties 的 svn.presets[*] 中。
• 前端不再传 SVN URL，业务接口统一传 presetId，后端按 presetId 解析地址。
• GET /api/svn/presets 仅返回 id 与 name（不返回 url）。

主要 API

• POST /api/svn/test-connection
• POST /api/svn/fetch
• GET /api/svn/presets
• POST /api/ai/analyze
• GET /api/tasks
• GET /api/tasks/query?status=&type=&keyword=&page=1&size=10
• GET /api/tasks/{taskId}
• GET /api/tasks/{taskId}/stream（SSE 实时输出）
• POST /api/tasks/{taskId}/cancel
• GET /api/health
• GET /api/health/details
• GET /api/files
• GET /api/files/download?path=...
• GET /api/settings
• PUT /api/settings

验证建议

至少执行：

mvn clean compile

如需验证完整流程：

1. 启动 Web 服务
2. 在「SVN 日志抓取」创建任务并生成 .md
3. 在「AI 工作量分析」选择 .md 并生成 .xlsx
4. 在「任务历史」中下载产物并核验内容

AI 输入校验

为避免误操作和资源滥用，AI 分析接口增加输入约束：

• 一次最多分析 20 个文件
• 仅允许 .md 文件
• 单文件大小不超过 2MB