diff --git a/AGENTS.md b/AGENTS.md index f86f35c4..a10b2498 100644 --- 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 添加 `` -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` 增加 `` +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 服务做验证后，结束测试时要主动停止进程，避免残留占用端口