363 lines
14 KiB
Markdown
363 lines
14 KiB
Markdown
# AGENTS.md - AI Coding Assistant Guide
|
||
|
||
## 项目概述
|
||
|
||
本仓库是纪检初核系统主仓库，基于若依 `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/` 初始化与增量脚本
|
||
|
||
---
|
||
|
||
## 高优先级规则
|
||
|
||
- 使用简体中文进行思考和对话
|
||
- Git 提交说明必须使用中文
|
||
- 忽略 `.DS_Store` 文件，不将其视为本次任务需要处理或提交的有效变更
|
||
- 仅当用户明确声明调用 `using-superpowers` 时才允许启用；未明确声明时按普通流程直接处理需求
|
||
- Git 提交前必须检查暂存区，仅允许包含本次任务相关文件；若存在无关文件，必须先移出暂存或与用户确认
|
||
- 每一次改动都需要留下实施文档，记录修改内容、影响范围与验证情况
|
||
- 功能设计同时涉及前端和后端改动时，必须分别输出后端与前端两份实施计划；若仅涉及单侧，则只输出对应实施计划
|
||
- 新增或修改设计文档、实施计划、实施记录前，必须先确认保存路径是否正确
|
||
- 前端相关安装、构建、调试、测试命令执行前，必须先通过 `nvm` 切换并确认 Node 版本
|
||
- 测试结束后，自动关闭测试过程中启动的前后端进程
|
||
- 重启后端时，必须优先使用 `bin/restart_java_backend.sh`
|
||
|
||
---
|
||
|
||
## 协作约定
|
||
|
||
### 基础协作
|
||
|
||
- 前端开发直接在当前分支进行，不需要额外创建 git worktree
|
||
- 给出方案时，必须保持最短路径实现，不允许提供兼容性、补丁性或过度设计的方案
|
||
- 不允许自行扩展出用户需求之外的兜底、降级或变体方案，避免业务逻辑偏移
|
||
- 输出方案前必须完成全链路逻辑校验，确保方案逻辑正确、链路闭环
|
||
|
||
### Git 与变更管理
|
||
|
||
- Git 提交前必须检查暂存区，仅保留本次任务相关文件
|
||
- 若暂存区存在无关文件，必须先移出暂存或与用户确认，禁止顺带提交
|
||
- `.DS_Store` 默认忽略，不纳入任务变更范围
|
||
|
||
### 文档产出
|
||
|
||
- 若需求来自设计文档，默认同时沉淀后端与前端两份实施计划
|
||
- 功能设计同时涉及前端和后端改动时，实施计划分别放在 `docs/plans/backend/` 与 `docs/plans/frontend/`
|
||
- 功能修改只涉及前端或只涉及后端时，只输出对应的实施计划
|
||
- 非前后端架构项目不强制拆分两份实施计划
|
||
- 每一次改动都需要留下实施文档，实施记录优先放在 `docs/reports/implementation/`
|
||
- 每次新增或修改设计文档、实施计划、实施记录前，都要先确认保存路径是否正确
|
||
|
||
### 测试与运行
|
||
|
||
- 测试结束后，自动关闭测试过程中启动的前后端进程
|
||
- 重启后端时，必须优先使用 `bin/restart_java_backend.sh`，不要直接手工执行 `java -jar` 替代正式重启流程
|
||
- 前端相关安装、构建、调试、测试命令执行前，必须先通过 `nvm` 切换并确认 Node 版本
|
||
|
||
### 数据库与编码
|
||
|
||
- 遇到 MCP 数据库操作时，使用项目配置文件中的数据库连接信息
|
||
- 执行包含中文内容的 MySQL SQL 脚本或数据库导入时，禁止直接手写 `mysql -e` 或普通重定向执行；必须优先使用 `bin/mysql_utf8_exec.sh <sql-file>`，确保会话字符集为 `utf8mb4`
|
||
- 所有业务表、系统表新增或修改时，必须显式使用 `utf8mb4` 字符集与 `utf8mb4_general_ci` 排序规则
|
||
- 禁止引入 `utf8mb4_0900_ai_ci`、`utf8mb4_unicode_ci` 或其他混用排序规则
|
||
- 银行流水打标相关规则与参数编码需要统一使用全大写；新增或修改 `rule_code`、`indicator_code`、`param_code` 时，禁止混用大小写风格
|
||
|
||
---
|
||
|
||
## Build / Run / Test Commands
|
||
|
||
### 后端 (Maven)
|
||
|
||
```bash
|
||
# 根目录编译全部 Java 模块
|
||
mvn clean compile
|
||
|
||
# 启动主应用（Jar）
|
||
sh bin/restart_java_backend.sh
|
||
|
||
# 打包全部模块
|
||
mvn clean package
|
||
|
||
# 运行单个测试类
|
||
mvn test -Dtest=ClassName
|
||
|
||
# 运行单个测试方法
|
||
mvn test -Dtest=ClassName#methodName
|
||
|
||
# 跳过测试打包
|
||
mvn clean package -DskipTests
|
||
```
|
||
|
||
### 前端 (npm)
|
||
|
||
```bash
|
||
cd ruoyi-ui
|
||
|
||
# 使用 nvm 切换到项目所需 Node 版本
|
||
nvm use
|
||
|
||
# 安装依赖
|
||
npm install --registry=https://registry.npmmirror.com
|
||
|
||
# 本地开发
|
||
npm run dev
|
||
|
||
# 生产构建
|
||
npm run build:prod
|
||
|
||
# 预览构建结果
|
||
npm run preview
|
||
```
|
||
|
||
### 流水分析 Mock 服务 (Python / FastAPI)
|
||
|
||
```bash
|
||
cd lsfx-mock-server
|
||
|
||
# 安装依赖
|
||
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
|
||
```
|
||
|
||
---
|
||
|
||
## 代码规范
|
||
|
||
### Java 代码风格
|
||
|
||
- 实体类优先使用 Lombok `@Data`
|
||
- 依赖注入使用 `@Resource`，不要使用 `@Autowired`
|
||
- 实体类不继承 `BaseEntity`，审计字段单独声明
|
||
- 禁止使用全限定类名，必须通过 `import` 引入
|
||
|
||
```java
|
||
@Data
|
||
public class CcdiBaseStaff {
|
||
/** 创建者 */
|
||
private String createBy;
|
||
/** 创建时间 */
|
||
private Date createTime;
|
||
/** 更新者 */
|
||
private String updateBy;
|
||
/** 更新时间 */
|
||
private Date updateTime;
|
||
}
|
||
|
||
@Resource
|
||
private ICcdiBaseStaffService baseStaffService;
|
||
```
|
||
|
||
### 分层规范
|
||
|
||
- `Controller` 添加 Swagger 注释
|
||
- 分页查询优先使用 MyBatis Plus `Page`
|
||
- 简单 CRUD 优先使用 MyBatis Plus
|
||
- 复杂查询或批量逻辑放到 XML SQL
|
||
- 接口入参使用独立 DTO，返回使用独立 VO
|
||
- 禁止 DTO、VO 与 entity 混用
|
||
- 禁止 `extends ServiceImpl<>`
|
||
|
||
### API 响应格式
|
||
|
||
```java
|
||
// 成功
|
||
AjaxResult.success("操作成功", data);
|
||
|
||
// 错误
|
||
AjaxResult.error("操作失败");
|
||
|
||
// 分页
|
||
Page<CcdiBaseStaff> page = new Page<>(pageNum, pageSize);
|
||
IPage<CcdiBaseStaff> result = baseStaffMapper.selectPage(page, queryWrapper);
|
||
return AjaxResult.success(result);
|
||
```
|
||
|
||
### 数据库规范
|
||
|
||
- 业务表统一使用 `ccdi_` 前缀
|
||
- 非业务字段如 `create_by`、`create_time` 由后端自动维护
|
||
- 前端表单不要暴露通用审计字段
|
||
- 新增菜单、字典、初始化数据时，同步补充 SQL 脚本
|
||
- 执行数据库脚本或导入数据库前，需确认客户端会话字符集为 `utf8mb4`
|
||
- 涉及中文插入、更新、导入时默认使用 `bin/mysql_utf8_exec.sh`
|
||
- 所有系统表和业务表的表级、字符字段级排序规则统一为 `utf8mb4_general_ci`
|
||
- 新增建表 SQL、字段追加 SQL、表结构修复 SQL 必须显式声明字符集与排序规则，避免因默认排序规则漂移导致联表或条件查询报错
|
||
|
||
### 前端规范
|
||
|
||
- 页面放在 `ruoyi-ui/src/views/` 下，按业务域组织
|
||
- API 文件放在 `ruoyi-ui/src/api/` 下，与后端 Controller 对应
|
||
- 请求统一使用 `@/utils/request`
|
||
- 新增页面或功能入口时，同步检查 `sys_menu`、路由、权限标识
|
||
- 优先延续现有 `ccdi*` 业务目录与命名方式，不随意新造平行目录
|
||
|
||
### 导入功能规范
|
||
|
||
- 大批量导入优先考虑批量写入
|
||
- 返回结果仅展示失败数据
|
||
- 大数据量导入优先采用 EasyExcel + 异步处理
|
||
|
||
### 导入页面测试规范
|
||
|
||
- 导入功能测试必须进入真实业务页面执行，先在页面内下载当前导入模板，再基于该模板生成测试文件，禁止手工凭记忆新建表头或脱离页面直接构造上传文件
|
||
- 双 Sheet 模板的导入测试必须覆盖两个 Sheet 的联动关系；除“缺少 Sheet / 空 Sheet”专项场景外，默认两个 Sheet 都要准备测试数据
|
||
- 导入测试文件优先放在 `output/spreadsheet/` 或 `output/playwright/`，不提交到 git
|
||
- 需要按场景拆分测试文件，避免多个互斥校验互相覆盖；至少覆盖空模板、主信息必填、主信息格式与金额、主从关系异常、供应商校验、缺少/空 Sheet、成功导入、成功与失败混合、失败记录查看、导入后清理回滚
|
||
- 主从关系异常测试至少覆盖：已存在主键、供应商有数据但主信息缺失、主信息重复、供应商 Sheet 中采购事项 ID 为空
|
||
- 供应商校验测试至少覆盖：重复供应商、多条中标、供应商名称为空、名称超长、联系人超长、银行账户超长、联系电话非法、统一信用代码非法、是否中标枚举非法
|
||
- 页面上传后必须核对页面提示、导入状态、失败记录弹窗和列表总数变化；异步导入场景还要核对任务状态从 `PROCESSING` 到最终状态的变化
|
||
- 对“成功导入 + 异常数据混合”的样本，必须额外核对成功数据是否真正入库、异常数据是否被拦截，以及是否存在被静默忽略的行
|
||
- 导入测试结束后，必须删除本轮成功写入的测试数据，清理页面本地导入任务缓存，并关闭测试过程中启动的前后端进程
|
||
|
||
---
|
||
|
||
## 当前仓库结构
|
||
|
||
```text
|
||
ccdi/
|
||
├── 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 模块
|
||
|
||
根 `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/`
|
||
- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/`
|
||
- `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/`
|
||
- `ruoyi-ui/src/views/`
|
||
- `ruoyi-ui/src/api/ccdi/`
|
||
|
||
### 添加新后端模块时
|
||
|
||
1. 在根 `pom.xml` 增加 `<module>`
|
||
2. 在新模块 `pom.xml` 中声明公共依赖，如 `ruoyi-common`
|
||
3. 在 `ruoyi-admin/pom.xml` 中引入该业务模块
|
||
4. 按 `controller/service/mapper/domain` 分层创建代码
|
||
5. 补充对应 SQL、菜单、权限和前端 API/页面
|
||
|
||
---
|
||
|
||
## 常用路径
|
||
|
||
| 用途 | 路径 |
|
||
|------|------|
|
||
| 应用入口 | `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/` |
|
||
| 流水分析对接 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/`：代码评审报告
|
||
|
||
### 历史资料目录
|
||
|
||
- `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/`
|
||
- 如果移动了文档，需同步修正文档内引用路径
|
||
- 若需求来自设计文档，默认同时沉淀后端与前端两份实施计划
|
||
- 功能设计同时涉及前端和后端改动时，必须分别输出后端与前端两份实施计划；若仅涉及前端或仅涉及后端，则只输出对应实施计划；非前后端架构项目不强制拆分双文档
|
||
- 每一次改动都需要留下实施文档，记录本次修改内容、影响范围与验证情况，实施记录优先放在 `docs/reports/implementation/`
|
||
- 每次新增或修改设计文档、实施计划、实施记录前，都要先确认保存路径是否正确
|
||
|
||
---
|
||
|
||
## 开发与测试提醒
|
||
|
||
- `target/`、`node_modules/`、运行日志等目录默认视为构建产物，阅读时注意与源码区分
|
||
- `lsfx-mock-server` 是独立子项目，除非任务涉及流水分析联调，否则不要把其实现规则混入主 Java 工程
|
||
- `docker/backend`、`docker/frontend`、`docker/mock` 分别对应三类运行时镜像
|
||
- `sql/migration/` 用于增量迁移脚本，新增修复脚本优先按日期或功能命名
|
||
- 启动前后端或 Mock 服务做验证后，结束测试时要主动停止进程，避免残留占用端口
|
||
- 前端相关安装、构建、调试、测试命令执行前，必须先通过 `nvm` 切换并确认 Node 版本
|