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