svn-log-tool/docs/README_Web.md

SVN 日志 Web 工作台

功能概览

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

1. SVN 参数录入与连接测试
2. 异步抓取日志并导出 Markdown
3. 使用 DeepSeek 分析 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 文件、工作周期、输出文件名
• 任务历史：异步任务状态与产物列表，支持筛选、分页、取消任务
• 系统设置：DeepSeek API Key、输出目录、默认 SVN 预置项目

输出目录

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

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