更新 AGENTS 文档说明

2026-03-17 15:15:57 +08:00
parent bcee31495c
commit 6e6419c116
1 changed files with 180 additions and 62 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,22 +2,44 @@

 ## 项目概述

-基于若依 v3.9.1 的纪检初核系统，Java 21 + Spring Boot 3 + Vue 2
+本仓库是纪检初核系统主仓库，基于若依 `v3.9.1`，当前技术栈以 `Java 21 + Spring Boot 3 + Vue 2` 为主，并包含独立的流水分析 Mock 服务、Docker 部署文件、SQL 脚本、实施文档与测试文档。
+
+仓库同时承载以下内容：
+
+- Java 多模块后端工程
+- `ruoyi-ui` 前端工程
+- `lsfx-mock-server` Python FastAPI Mock 服务
+- `docs/` 正式文档目录
+- `assets/` 历史设计、测试、接口和实施材料
+- `sql/` 初始化与增量脚本

 ---

-## Build / Lint / Test Commands
+## 协作约定
+
+- 使用简体中文进行思考和对话
+- Git 提交说明使用中文
+- 根据设计文档产出实施计划时，默认输出两份文档：
+  - 后端实施计划放 `docs/plans/backend/`
+  - 前端实施计划放 `docs/plans/frontend/`
+- 前端开发直接在当前分支进行，不需要额外创建 git worktree
+- 测试结束后，自动关闭测试过程中启动的前后端进程
+- 遇到 MCP 数据库操作时，使用项目配置文件中的数据库连接信息
+
+---
+
+## Build / Run / Test Commands

 ### 后端 (Maven)

 ```bash
-# 编译项目
+# 根目录编译全部 Java 模块
 mvn clean compile

-# 运行应用
-mvn spring-boot:run
+# 启动主应用
+mvn -pl ruoyi-admin spring-boot:run

-# 打包部署
+# 打包全部模块
 mvn clean package

 # 运行单个测试类
@@ -26,7 +48,7 @@ mvn test -Dtest=ClassName
 # 运行单个测试方法
 mvn test -Dtest=ClassName#methodName

-# 跳过测试
+# 跳过测试打包
 mvn clean package -DskipTests
 ```

@@ -38,21 +60,45 @@ cd ruoyi-ui
 # 安装依赖
 npm install --registry=https://registry.npmmirror.com

-# 开发服务器
+# 本地开发
 npm run dev

 # 生产构建
 npm run build:prod
+
+# 预览构建结果
+npm run preview
 ```

-### API 测试
+### 流水分析 Mock 服务 (Python / FastAPI)

 ```bash
-# 获取 Token (测试账号: admin/admin123)
-POST http://localhost:8080/login/test?username=admin&password=admin123
+cd lsfx-mock-server

-# Swagger 文档
-http://localhost:8080/swagger-ui/index.html
+# 安装依赖
+pip install -r requirements.txt
+
+# 启动服务
+python main.py
+
+# 热重载启动
+uvicorn main:app --reload --host 0.0.0.0 --port 8000
+
+# 运行测试
+pytest tests/ -v
+```
+
+### API 调试
+
+```bash
+# 测试登录（默认测试账号）
+POST http://localhost:62318/login/test?username=admin&password=admin123
+
+# 主系统 Swagger
+http://localhost:62318/swagger-ui.html
+
+# 流水分析 Mock Swagger
+http://localhost:8000/docs
 ```

 ---
@@ -61,10 +107,10 @@ http://localhost:8080/swagger-ui/index.html

 ### Java 代码风格

- **注解**: 使用 Lombok `@Data` 简化实体类
- **依赖注入**: 使用 `@Resource` 而非 `@Autowired`
- **实体类**: 不继承 BaseEntity，单独添加审计字段
- **禁止**: 禁止使用全限定类名 (如 `java.util.List`)，必须 import
+- 实体类优先使用 Lombok `@Data`
+- 依赖注入使用 `@Resource`，不要使用 `@Autowired`
+- 实体类不继承 `BaseEntity`，审计字段单独声明
+- 禁止使用全限定类名，必须通过 `import` 引入

 ```java
@Data
@@ -85,10 +131,13 @@ private ICcdiBaseStaffService baseStaffService;

 ### 分层规范

- **Controller**: 添加 Swagger 注释，分页使用 MyBatis Plus Page
- **Service**: 简单 CRUD 用 MyBatis Plus，复杂操作在 XML 写 SQL
- **DTO/VO**: 接口传参用独立 DTO，返回用独立 VO，禁止与 entity 混用
- **禁止**: 禁止 `extends ServiceImpl<>`
+- `Controller` 添加 Swagger 注释
+- 分页查询优先使用 MyBatis Plus `Page`
+- 简单 CRUD 优先使用 MyBatis Plus
+- 复杂查询或批量逻辑放到 XML SQL
+- 接口入参使用独立 DTO，返回使用独立 VO
+- 禁止 DTO、VO 与 entity 混用
+- 禁止 `extends ServiceImpl<>`

 ### API 响应格式

@@ -107,43 +156,87 @@ return AjaxResult.success(result);

 ### 数据库规范

- 表名: `ccdi_` 前缀 (如 `ccdi_base_staff`)
- 非业务字段 (create_by, create_time 等) 由后端自动处理，前端表单不显示
+- 业务表统一使用 `ccdi_` 前缀
+- 非业务字段如 `create_by`、`create_time` 由后端自动维护
+- 前端表单不要暴露通用审计字段
+- 新增菜单、字典、初始化数据时，同步补充 SQL 脚本

 ### 前端规范

- **目录结构**: `views/` 按功能模块组织，`api/` 对应后端 Controller
- **API 调用**: 使用 `@/utils/request` 封装
- **菜单联动**: 添加页面后需同步修改数据库 `sys_menu` 表
+- 页面放在 `ruoyi-ui/src/views/` 下，按业务域组织
+- API 文件放在 `ruoyi-ui/src/api/` 下，与后端 Controller 对应
+- 请求统一使用 `@/utils/request`
+- 新增页面或功能入口时，同步检查 `sys_menu`、路由、权限标识
+- 优先延续现有 `ccdi*` 业务目录与命名方式，不随意新造平行目录

 ### 导入功能规范

- 批量操作提高性能
- 返回结果只展示失败数据，不展示成功数据
- 使用 EasyExcel + 异步处理大数据量导入
+- 大批量导入优先考虑批量写入
+- 返回结果仅展示失败数据
+- 大数据量导入优先采用 EasyExcel + 异步处理

 ---

-## 模块架构
+## 当前仓库结构

-```
+```text
 ccdi/
-├── ruoyi-admin/           # 启动入口
-├── ruoyi-framework/       # 安全配置
-├── ruoyi-system/          # 系统模块
-├── ruoyi-common/          # 通用工具
-├── ccdi-info-collection/  # 信息采集 (员工、中介、黑名单)
-├── ccdi-project/          # 项目管理
-├── ccdi-lsfx/             # 流水分析对接
-└── ruoyi-ui/              # 前端
+├── ruoyi-admin/            # Spring Boot 启动入口与 Web 层装配
+├── ruoyi-framework/        # 安全、权限、配置等基础框架
+├── ruoyi-system/           # 系统管理模块
+├── ruoyi-common/           # 通用组件、工具类、基础能力
+├── ruoyi-quartz/           # 定时任务模块
+├── ruoyi-generator/        # 代码生成模块
+├── ccdi-info-collection/   # 信息采集模块（员工、中介、黑名单等）
+├── ccdi-project/           # 项目管理与项目业务模块
+├── ccdi-lsfx/              # 流水分析对接模块
+├── ruoyi-ui/               # Vue 2 前端
+├── lsfx-mock-server/       # 流水分析平台 Mock 服务（FastAPI）
+├── docs/                   # 正式设计、计划、测试、报告
+├── assets/                 # 历史设计稿、接口材料、测试资料、实施材料
+├── sql/                    # 建表、菜单、字典、修复、迁移脚本
+├── docker/                 # 后端、前端、Mock 服务容器文件
+├── deploy/                 # 部署相关文件
+├── bin/                    # 仓库级辅助脚本目录
+├── scripts/                # 预留脚本目录（当前基本为空）
+├── logs/                   # 运行日志输出目录
+└── .worktrees/             # 本地工作树目录
 ```

-### 添加新模块
+### Maven 模块

-1. 根 pom.xml 添加 `<module>`
-2. pom.xml 添加 `ruoyi-common` 依赖
-3. `ruoyi-admin/pom.xml` 添加模块依赖
-4. 按分层创建 controller/service/mapper/domain 包
+根 `pom.xml` 当前包含以下 Java 模块：
+
+1. `ruoyi-admin`
+2. `ruoyi-framework`
+3. `ruoyi-system`
+4. `ruoyi-quartz`
+5. `ruoyi-generator`
+6. `ruoyi-common`
+7. `ccdi-info-collection`
+8. `ccdi-project`
+9. `ccdi-lsfx`
+
+### 主要业务代码分布
+
+- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/`
+  - 含 `controller`、`domain`、`mapper`、`service`、`annotation`、`validation` 等目录
+- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/`
+  - 含 `config`、`controller`、`domain`、`mapper`、`service`
+- `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/`
+  - 含 `client`、`config`、`constants`、`controller`、`domain/request`、`domain/response`
+- `ruoyi-ui/src/views/`
+  - 当前包含 `ccdi`、`ccdiBaseStaff`、`ccdiProject`、`ccdiPurchaseTransaction`、`ccdiIntermediary`、亲属关系、员工调动、招聘等业务页面
+- `ruoyi-ui/src/api/ccdi/`
+  - 放置纪检初核业务 API 封装
+
+### 添加新后端模块时
+
+1. 在根 `pom.xml` 增加 `<module>`
+2. 在新模块 `pom.xml` 中声明公共依赖，如 `ruoyi-common`
+3. 在 `ruoyi-admin/pom.xml` 中引入该业务模块
+4. 按 `controller/service/mapper/domain` 分层创建代码
+5. 补充对应 SQL、菜单、权限和前端 API/页面

 ---

@@ -154,30 +247,55 @@ ccdi/
 | 应用入口 | `ruoyi-admin/src/main/java/com/ruoyi/RuoYiApplication.java` |
 | 信息采集 Controller | `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/controller/` |
 | 项目管理 Controller | `ccdi-project/src/main/java/com/ruoyi/ccdi/project/controller/` |
-| 前端 API | `ruoyi-ui/src/api/` |
+| 流水分析对接 Controller | `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/controller/` |
+| 前端业务 API | `ruoyi-ui/src/api/ccdi/` |
+| 前端页面 | `ruoyi-ui/src/views/` |
 | Vue 路由 | `ruoyi-ui/src/router/index.js` |
+| Vuex | `ruoyi-ui/src/store/` |
+| Mock 服务入口 | `lsfx-mock-server/main.py` |
+| Mock 路由 | `lsfx-mock-server/routers/api.py` |
+| Docker 文件 | `docker/` |
+| SQL 脚本 | `sql/` |

 ---

-## 文档规范
+## 文档与资产规范

- `docs/design/`: 设计文档与设计附属文件
- `docs/plans/backend/`: 后端实施计划
- `docs/plans/frontend/`: 前端实施计划
- `docs/plans/fullstack/`: 综合实施计划、集成计划与通用实施文档
- `docs/plans/misc/`: 计划类杂项文档
- `docs/tests/plans/`: 测试计划
- `docs/tests/records/`: 测试记录
- `docs/tests/scripts/`: 测试脚本与脚本说明
- `docs/reports/implementation/`: 实施报告
- `docs/reports/optimization/`: 优化记录
- `docs/reports/code-review/`: 代码评审报告
- 新增文档时优先放入上述目录，避免继续直接堆放到 `docs/plans/` 根目录
- 文档之间如果引用 `docs` 路径，新增或移动后需同步修正引用
+### 正式文档目录
+
+- `docs/design/`：设计文档与设计附属文件
+- `docs/plans/backend/`：后端实施计划
+- `docs/plans/frontend/`：前端实施计划
+- `docs/plans/fullstack/`：综合实施计划、联调计划、通用实施文档
+- `docs/plans/misc/`：其他计划类文档
+- `docs/tests/plans/`：测试计划
+- `docs/tests/records/`：测试记录
+- `docs/tests/scripts/`：测试脚本与脚本说明
+- `docs/reports/implementation/`：实施报告
+- `docs/reports/optimization/`：优化记录
+- `docs/reports/code-review/`：代码评审报告
+
+### 历史资料目录
+
+- `assets/design/`：历史设计材料
+- `assets/interface-doc/`、`assets/api-docs/`：接口资料
+- `assets/database/`、`assets/database-docs/`：数据库相关资料
+- `assets/test-reports/`、`assets/test-scripts/`、`assets/测试文档/`：测试资料
+- `assets/plans/`、`assets/implementation/`、`assets/实施文档/`：历史实施材料
+
+### 文档维护要求
+
+- 新增文档优先落到 `docs/` 下的规范目录，不要继续堆放到 `docs/plans/` 根目录
+- 只有历史资料或外部原始材料才放入 `assets/`
+- 如果移动了文档，需同步修正文档内引用路径
+- 若需求来自设计文档，默认同时沉淀后端与前端两份实施计划

 ---

-## 沟通规范
+## 开发与测试提醒

- 使用简体中文进行思考和对话
- 遇到 MCP 数据库操作时，使用项目配置文件中的数据库
+- `target/`、`node_modules/`、运行日志等目录默认视为构建产物，阅读时注意与源码区分
+- `lsfx-mock-server` 是独立子项目，除非任务涉及流水分析联调，否则不要把其实现规则混入主 Java 工程
+- `docker/backend`、`docker/frontend`、`docker/mock` 分别对应三类运行时镜像
+- `sql/migration/` 用于增量迁移脚本，新增修复脚本优先按日期或功能命名
+- 启动前后端或 Mock 服务做验证后，结束测试时要主动停止进程，避免残留占用端口