liumangmang
106 lines
4.2 KiB
Markdown
106 lines
4.2 KiB
Markdown
# 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` 成功。
|
||
- 输出结论时写明：改了什么、为什么、如何验证。
|