svn-log-tool/AGENTS.md

AGENTS 指南（svn-log-tool）

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

1. 项目概览

• 产品名：SVN/Git 日报周报月报一键生成
• 语言与构建：Java 8 + Maven（backend/pom.xml）
• 打包产物：由 backend/ 输出可执行 fat jar（jar-with-dependencies）
• 统一入口：com.svnlog.web.WebApplication
• 核心目录：
  • backend/src/main/java/com/svnlog/core/（svn / git / report）
  • backend/src/main/java/com/svnlog/web/（controller / service / dto / model）
  • backend/src/test/java/（后端测试）
  • docs/
• SVN 预设：由 SvnPresetService 管理，当前为后端静态配置

2. 常用命令（Build / Lint / Test / Run）

以下命令默认在仓库根目录执行。

2.1 Build

• 后端仅编译：cd backend && mvn clean compile
• 后端打包（跳过测试）：cd backend && mvn clean package -DskipTests
• 整体打包（推荐）：make build
• 产物（通常）：backend/target/svn-log-tool-1.0.0-jar-with-dependencies.jar

2.2 Lint / 静态检查

• 后端以 cd backend && mvn clean compile 作为基础语法检查。
• 若需更严格检查，可使用 cd backend && mvn -DskipTests verify。

2.3 Test

• 运行后端全部测试：cd backend && mvn test
• 运行单个测试类：cd backend && mvn -Dtest=ClassName test
• 运行单个测试方法：cd backend && mvn -Dtest=ClassName#methodName test
• 已有测试位于 backend/src/test/java/com/svnlog/web/service/

2.4 Run

• 运行服务（Docker，推荐）：
  • make up
  • make status
  • make down
  • 启动后访问：http://localhost:18088
• 运行后端（本机 Java + Maven）：
  • cd backend && mvn spring-boot:run -Dspring-boot.run.mainClass=com.svnlog.web.WebApplication

3. 代码结构与职责边界

核心层（backend/src/main/java/com/svnlog/core/）

• core/svn/SVNLogFetcher：SVN 连接、版本区间处理、日志抓取、用户过滤
• core/git/GitLogFetcher：Git 本地仓库日志抓取
• core/report/MarkdownReportWriter：Markdown 报表生成

Web 层（backend/src/main/java/com/svnlog/web/）

• web/controller/AppController：REST API 统一入口
• web/service/ReportWorkflowService：统一报表生成工作流
• web/service/TaskService：异步任务管理
• web/service/SettingsService：API Key 与输出目录管理
• web/service/RepositoryConfigService：仓库配置管理

变更原则

• SVN 抓取逻辑改在 backend/src/main/java/com/svnlog/core/svn/
• Git 抓取逻辑改在 backend/src/main/java/com/svnlog/core/git/
• 报表生成逻辑改在 backend/src/main/java/com/svnlog/core/report/
• AI/Excel 逻辑改在 backend/src/main/java/com/svnlog/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 必须使用大括号。

5. 安全与敏感信息

• 严禁提交真实密钥、口令、Token、内网敏感地址。
• 优先从环境变量读取 API Key。
• 不把真实值写入源码或日志。

6. 测试与验收建议

• 功能变更后至少执行：
  • cd backend && mvn clean compile
  • cd backend && mvn test（若已有测试）

7. Git 与提交建议（给 Agent）

• 小步提交，标题建议使用动词前缀：fix:、feat:、refactor:、docs:。
• 一次提交只做一类改动。
• 不顺手修改无关文件。

8. 给自动化代理的执行清单

• 先读 backend/pom.xml 与目标类，再动代码。
• 先最小改动实现需求，再补测试与文档。
• 变更命令、入口、参数时必须更新本文档。
• 无测试时至少确保 cd backend && mvn clean compile 成功。
• 输出结论时写明：改了什么、为什么、如何验证。