# 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 构建行为与优化

- **Docker 镜像加速**：默认使用 `docker.1ms.run/library` 代理。如果需要切换回 Docker Hub 或使用国内其他镜像（如阿里云镜像，例如 `registry.cn-hangzhou.aliyuncs.com/library`，注意不能带 `https://`），可以通过命令行传递 `DOCKER_REGISTRY_MIRROR` 变量：
  ```bash
  DOCKER_REGISTRY_MIRROR=registry.cn-hangzhou.aliyuncs.com/library make up
  ```
- **快速开发迭代（可选 Fast Build）**：默认情况下，构建仍会执行 `mvn clean package` 以确保打包的正确性（防旧 class 或资源残留）。如果在本地频繁修改 Java 代码，可以使用 `fast-up` 实现秒级编译与构建重启。**注意：如果修改了前端静态资源，或删除/重命名了 Java 类与资源文件，应使用默认构建（`make up`），不要用 Fast Build。**
  ```bash
  make fast-up
  ```
  该模式下，Docker 会使用 BuildKit 挂载缓存 `/app/target` 目录，并不再执行 `clean` 目标，使 Maven 能进行增量编译。
- **依赖缓存**：Docker 构建使用 BuildKit 缓存了 Maven 本地仓库（`.m2`）与 npm 缓存（`.npm`）。在依赖文件未变更时，不会重复下载依赖包。
- 如果本机 Docker 未启用 BuildKit，可显式设置 `DOCKER_BUILDKIT=1` 和 `COMPOSE_DOCKER_CLI_BUILD=1` 后再执行构建。

## 页面说明

- 工作台：最近任务统计与最近产物
- 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. 预设凭据
3. 全局设置保存的运行时 `svnUsername/svnPassword`
4. 环境变量 `SVN_USERNAME` / `SVN_PASSWORD`

`GET /api/settings` 不会回显 `openaiApiKey` 或 `svnPassword` 明文，前端通过 `openaiApiKeyConfigured` 和 `svnCredentialsConfigured` 展示配置状态。

## 安全与兼容配置

- SVN 密码加密密钥不再写死在源码中：
  - 默认生成到 `outputs/.svn-log-tool.key`
  - 可用 `SVN_LOG_TOOL_CRYPTO_KEY` 或 `-Dsvnlog.crypto.key=...` 指定 Base64 AES 密钥
  - 可用 `SVN_LOG_TOOL_CRYPTO_KEY_FILE` 或 `-Dsvnlog.crypto.keyFile=...` 指定密钥文件
  - 旧版本固定密钥加密的历史配置需要先用显式密钥启动并重新保存配置完成迁移
- HTTPS/SVN 默认只启用 TLS 1.2，并保留系统默认的证书校验。
- 如必须连接旧内网 SVN，可显式启用兼容开关：
  - `SVN_LOG_TOOL_ALLOW_LEGACY_TLS=true` 或 `-Dsvnlog.svn.allowLegacyTls=true`
  - `SVN_LOG_TOOL_ALLOW_INSECURE_SSL=true` 或 `-Dsvnlog.svn.allowInsecureSsl=true`
- 异步任务线程数可配置：
  - `SVN_LOG_TOOL_TASK_THREADS=16` 或 `-Dsvnlog.task.threads=16`
  - 未配置时默认取 `max(8, CPU核数*2)`。

## 前端构建配置

- `VITE_API_BASE_URL`：覆盖前端 API Base URL，默认使用同源 `/api`。
- `VITE_DASHBOARD_POLL_INTERVAL_MS`：工作台轮询间隔，默认 `8000`，最小 `3000`。

## SVN 预设来源与调用方式

- SVN 地址统一通过仓库管理页维护，并持久化到 `outputs/repository-configs.json` 文件中。
- 前端不再传 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