# AGENTS 指南（svn-log-tool）
本文件提供给自动化编码代理（Agent）使用。
目标：在不破坏现有行为的前提下，安全、可复现地修改本仓库。

## 1. 项目概览
- 语言与构建：Java 8 + Maven（`pom.xml`）。
- 打包产物：可执行 fat jar（`jar-with-dependencies`）。
- 统一入口：`com.svnlog.web.WebApplication`（前后端一体，静态页面 + REST API）。
- 核心目录：
  - `src/main/java/com/svnlog/`
  - `docs/`
  - SVN 预设地址：`src/main/resources/application.properties`（`svn.presets[*]`）

## 2. 常用命令（Build / Lint / Test / Run）
以下命令默认在仓库根目录执行。

### 2.1 Build
- 仅编译（推荐快速检查）：`mvn clean compile`
- 打包（跳过测试）：`mvn clean package -DskipTests`
- 打包（执行测试）：`mvn clean package`
- 产物（通常）：`target/svn-log-tool-1.0.0-jar-with-dependencies.jar`

### 2.2 Lint / 静态检查
- 当前仓库未配置 Checkstyle / SpotBugs / PMD。
- 将 `mvn clean compile` 作为基础语法与依赖检查。
- 若需更严格检查，可使用 `mvn -DskipTests verify`。

### 2.3 Test
- 运行全部测试：`mvn test`
- 运行单个测试类（重点）：`mvn -Dtest=ClassName test`
- 单测类示例：`mvn -Dtest=SVNLogFetcherTest test`
- 运行单个测试方法（重点）：`mvn -Dtest=ClassName#methodName test`
- 单测方法示例：`mvn -Dtest=SVNLogFetcherTest#shouldFilterByUser test`
- 调试失败测试（输出更完整）：`mvn -Dtest=ClassName test -e`
- 说明：当前 `src/test/java` 为空；新增测试时采用 Surefire 默认约定。

### 2.4 Run
- 运行 Web 工作台（Docker，推荐）：
  - `make up`
  - `make status`
  - `make down`
  - 启动后访问：`http://localhost:18088`
- 运行 Web 工作台（本机 Java + Maven，备用）：
  - `mvn spring-boot:run -Dspring-boot.run.mainClass=com.svnlog.web.WebApplication`

## 3. 代码结构与职责边界
- `SVNLogFetcher.java`：SVN 连接、版本区间处理、日志抓取、用户过滤。
- `LogEntry.java`：日志数据模型（POJO）。
- `web/controller/*`：REST API（SVN、AI、任务、文件、设置）。
- `web/service/*`：异步任务与业务编排（SVN 抓取、AI 分析、输出目录管理）。
- `src/main/resources/static/*`：Web 前端页面与交互脚本。
- 变更原则：
  - 抓取逻辑改在 `SVNLogFetcher`。
  - AI/Excel 逻辑改在 `web/service/AiWorkflowService`。
  - 不把多种职责混入同一方法。

## 4. 代码风格规范（必读）

### 4.1 Java 与兼容性
- 严格保持 Java 8 兼容（`source/target=1.8`）。
- 避免引入仅 Java 9+ 可用 API。

### 4.2 Imports
- 不新增通配符导入（`*`），使用明确导入。
- 按三组排序并空行分隔：
  1) `java.*` / `javax.*`
  2) 第三方库
  3) 本项目包（`com.svnlog.*`）
- 删除未使用 import。

### 4.3 格式与排版
- 缩进使用 4 个空格，不用 Tab。
- 单行长度建议 <= 120。
- `if/for/while` 必须使用大括号（即使单行语句）。
- 方法间保留一个空行；逻辑块间适度空行。

### 4.4 类型与数据结构
- 优先使用接口类型声明：`List` / `Map`，实现类写在右侧。
- 泛型必须写完整，避免原生类型。
- 可变共享状态最小化；能用 `final` 的局部变量尽量用 `final`。
- 使用 `SimpleDateFormat` 等对象时，注意线程安全作用域。

### 4.5 命名规范
- 类名：`UpperCamelCase`（示例：`SVNLogFetcher`）。
- 方法/变量：`lowerCamelCase`（示例：`fetchLogs`）。
- 常量：`UPPER_SNAKE_CASE`（示例：`DEEPSEEK_API_URL`）。
- 名称应表达业务意图，避免无语义缩写（如 `tmp`、`data1`）。

### 4.6 异常与错误处理
- 不吞异常；至少记录错误上下文。
- CLI 提示要清晰，并给出可执行下一步。
- 能在边界处校验输入时，尽早校验并快速失败。
- 不要仅 `printStackTrace`；优先输出结构化错误信息。
- 外部调用（SVN/API/文件）必须处理失败分支与空响应。

### 4.7 I/O 与资源管理
- 文件与网络资源统一使用 try-with-resources。
- 路径与编码显式声明，默认 UTF-8。
- 大文本拼接优先 `StringBuilder`。

### 4.8 注释与文档
- 注释解释“为什么”，避免重复“做了什么”。
- 对外可见方法或复杂逻辑可补充简短 Javadoc。
- 修改行为时同步更新 `docs/` 下文档。

## 5. 安全与敏感信息
- 严禁提交真实密钥、口令、Token、内网敏感地址。
- Web 端 AI 分析涉及 API Key；新增改动时应：
  - 优先从环境变量读取（如 `DEEPSEEK_API_KEY`）。
  - 回退到交互输入。
  - 不把真实值写入源码或日志。
- 日志中避免打印完整凭据与隐私信息。

## 6. 测试与验收建议
- 功能变更后至少执行：
  - `mvn clean compile`
  - `mvn test`（若已有测试）
- 新增测试建议目录：`src/test/java/com/svnlog/`
- 测试命名建议：
  - 类名：`<被测类名>Test`
  - 方法名：`should<行为>When<条件>`

## 7. Git 与提交建议（给 Agent）
- 小步提交，标题建议使用动词前缀：`fix:`、`feat:`、`refactor:`、`docs:`。
- 一次提交只做一类改动（功能/重构/文档分离）。
- 不顺手修改无关文件。
- 提交前确认构建产物（`target/`）不入库。

## 8. Cursor / Copilot 规则检查结果
- 未发现 `.cursorrules`。
- 未发现 `.cursor/rules/` 目录。
- 未发现 `.github/copilot-instructions.md`。
- 若后续新增这些规则文件，应同步更新本 AGENTS，并以更具体规则优先。

## 9. 给自动化代理的执行清单
- 先读 `pom.xml` 与目标类，再动代码。
- 先最小改动实现需求，再补测试与文档。
- 变更命令、入口、参数时必须更新本文档。
- 无测试时至少确保 `mvn clean compile` 成功。
- 输出结论时写明：改了什么、为什么、如何验证。

## 10. 最小验证流程（建议）
- 仅修改文档：至少检查 Markdown 渲染与命令可复制执行。
- 修改 Java 代码：执行 `mvn clean compile`。
- 涉及测试逻辑：执行 `mvn test` 或目标单测命令。
- 涉及打包/入口：执行 `mvn clean package -DskipTests` 并验证产物。
- 涉及 DeepSeek 调用：避免在 CI/自动化中使用真实密钥做在线调用。
- 最终在变更说明中记录验证命令与结果。