liumangmang
1b182c2930
- New Vue 3 + Vite frontend at /v2/ (OLED dark theme, Fira Sans/Code) - Date selector: support day/week/month range (backend unchanged) - SSE auto-reconnect (up to 3 retries) - Visibility polling pause (dashboard pauses when tab hidden) - Friendly Chinese HTTP error messages - Cancel task with confirmation in Dashboard - Split AiWorkflowService (1700->845 lines): - AiApiService: AI API calls + streaming - ExcelExportService: POI Excel generation - Dockerfile: 3-stage build (Node frontend -> Maven -> JRE) - WebApplication.java: System.out -> Logger - .gitignore: v2 build output, backup dirs Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
133 lines
4.9 KiB
Markdown
133 lines
4.9 KiB
Markdown
# SVN 日志 Web 工作台
|
||
|
||
## 功能概览
|
||
|
||
Web 工作台将现有 CLI 能力封装为可视化页面与 REST API，支持以下流程：
|
||
|
||
1. SVN 参数录入与连接测试
|
||
2. 异步抓取日志并导出 Markdown
|
||
3. 使用 DeepSeek 或 OpenAI 兼容接口分析 Markdown 并生成 Excel
|
||
4. 查看任务历史（状态、进度、错误、产物），支持筛选、分页与取消运行中任务
|
||
5. 下载输出文件、配置 API Key、SVN 账号与输出目录
|
||
6. 工作台展示系统健康状态（输出目录可写性、API Key 配置、任务统计）
|
||
|
||
批量抓取策略：多个项目按顺序执行（前一个项目完成后才开始下一个）。
|
||
|
||
## 启动方式
|
||
|
||
在仓库根目录执行：
|
||
|
||
```bash
|
||
# Docker 一键启动（推荐；每次会重新构建镜像并打包最新代码）
|
||
make up
|
||
```
|
||
|
||
备用方式（本机 Java + Maven）：
|
||
|
||
```bash
|
||
mvn spring-boot:run -Dspring-boot.run.mainClass=com.svnlog.web.WebApplication
|
||
```
|
||
|
||
启动后访问：
|
||
|
||
```text
|
||
http://localhost:18088
|
||
```
|
||
|
||
## Docker 构建行为
|
||
|
||
- `make up` 保持“重新构建并启动”的语义，每次都会执行一次 Maven 打包，确保容器内是最新代码。
|
||
- Docker 构建使用 BuildKit 缓存 Maven 本地仓库；首次构建会下载依赖，后续在 `pom.xml` 未变更时会优先命中缓存，不会在每次构建时重复下载全部依赖。
|
||
- 如果修改了 `pom.xml`、执行了 `docker builder prune`、或切换到新的 Docker 环境，依赖缓存会失效并重新下载。
|
||
- 如果本机 Docker 未启用 BuildKit，可显式设置 `DOCKER_BUILDKIT=1` 和 `COMPOSE_DOCKER_CLI_BUILD=1` 后再执行 `make up`。
|
||
|
||
## 页面说明
|
||
|
||
- 工作台：最近任务统计与最近产物
|
||
- SVN 日志抓取：版本区间、过滤用户与连接测试；SVN 账号密码统一在系统设置中托管
|
||
- AI 工作量分析：选择 Markdown 文件、工作周期、输出文件名
|
||
- 任务历史：异步任务状态与产物列表，支持筛选、分页、取消任务
|
||
- 系统设置：AI 提供商、DeepSeek API Key、OpenAI 兼容 Base URL/API Key/阶段模型、SVN 用户名/密码、输出目录、默认 SVN 预置项目
|
||
|
||
## 输出目录
|
||
|
||
- 默认输出目录：`outputs/`
|
||
- Markdown 输出：`outputs/md/*.md`
|
||
- Excel 输出：`outputs/excel/*.xlsx`
|
||
- 任务持久化：`outputs/task-history.json`（重启后可恢复历史）
|
||
- 设置页保存 `outputDir` 时会自动创建不存在的目录；如果目标路径已被普通文件占用，或当前运行用户对该目录无写权限，`PUT /api/settings` 会明确返回失败。
|
||
- 如果本机已有 `outputs/` 但属主或权限异常，可手动修复为当前用户可写后再保存设置，例如调整目录属主或写权限。
|
||
|
||
## 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 凭据读取优先级
|
||
|
||
1. 单次请求显式传入的 `username/password`（兼容旧接口）
|
||
2. 设置页保存的运行时 `svnUsername/svnPassword`
|
||
3. 环境变量 `SVN_USERNAME` / `SVN_PASSWORD`
|
||
|
||
`GET /api/settings` 不会回显 `openaiApiKey` 或 `svnPassword` 明文，前端通过 `openaiApiKeyConfigured` 和 `svnCredentialsConfigured` 展示配置状态。
|
||
|
||
## 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`
|
||
- `POST /api/svn/version-range`：按 `rangeType=date|week|month` 查询版本范围；旧的 `year/month` 月份请求仍兼容
|
||
- `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`
|
||
|
||
## 验证建议
|
||
|
||
至少执行：
|
||
|
||
```bash
|
||
mvn clean compile
|
||
```
|
||
|
||
如需验证完整流程：
|
||
|
||
1. 启动 Web 服务
|
||
2. 在「SVN 日志抓取」创建任务并生成 `.md`
|
||
3. 在「AI 工作量分析」选择 `.md` 并生成 `.xlsx`
|
||
4. 在「任务历史」中下载产物并核验内容
|
||
|
||
## AI 输入校验
|
||
|
||
为避免误操作和资源滥用，AI 分析接口增加输入约束：
|
||
|
||
- 一次最多分析 20 个文件
|
||
- 仅允许 `.md` 文件
|
||
- 单文件大小不超过 2MB
|