149 lines
6.3 KiB
Markdown
149 lines
6.3 KiB
Markdown
# 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/自动化中使用真实密钥做在线调用。
|
||
- 最终在变更说明中记录验证命令与结果。
|