ccdi/AGENTS.md

# 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 提交说明使用中文
- Git 提交前必须检查暂存区，仅允许包含本次任务相关文件
- 若暂存区存在无关文件，必须先移出暂存或与用户确认，禁止顺带提交
- 根据设计文档产出实施计划时，默认输出两份文档：
  - 后端实施计划放 `docs/plans/backend/`
  - 前端实施计划放 `docs/plans/frontend/`
- 前端开发直接在当前分支进行，不需要额外创建 git worktree
- 测试结束后，自动关闭测试过程中启动的前后端进程
- 遇到 MCP 数据库操作时，使用项目配置文件中的数据库连接信息
- 执行包含中文内容的 MySQL SQL 脚本或数据库导入时，禁止直接手写 `mysql -e` 或普通重定向执行；必须优先使用 `bin/mysql_utf8_exec.sh <sql-file>`，确保会话字符集为 `utf8mb4`，避免导入或写入乱码
- 银行流水打标相关规则与参数编码需要统一使用全大写；新增或修改 `rule_code`、`indicator_code`、`param_code` 时，禁止混用大小写风格

---

## Build / Run / Test Commands

### 后端 (Maven)

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

# 启动主应用（Jar）
cd ruoyi-admin/target && java -jar ruoyi-admin.jar

# 打包全部模块
mvn clean package

# 运行单个测试类
mvn test -Dtest=ClassName

# 运行单个测试方法
mvn test -Dtest=ClassName#methodName

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

### 前端 (npm)

```bash
cd ruoyi-ui

# 安装依赖
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`

### 前端规范

- 页面放在 `ruoyi-ui/src/views/` 下，按业务域组织
- API 文件放在 `ruoyi-ui/src/api/` 下，与后端 Controller 对应
- 请求统一使用 `@/utils/request`
- 新增页面或功能入口时，同步检查 `sys_menu`、路由、权限标识
- 优先延续现有 `ccdi*` 业务目录与命名方式，不随意新造平行目录

### 导入功能规范

- 大批量导入优先考虑批量写入
- 返回结果仅展示失败数据
- 大数据量导入优先采用 EasyExcel + 异步处理

---

## 当前仓库结构

```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/`
  - 含 `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/页面

---

## 常用路径

| 用途 | 路径 |
|------|------|
| 应用入口 | `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/`
- 如果移动了文档，需同步修正文档内引用路径
- 若需求来自设计文档，默认同时沉淀后端与前端两份实施计划

---

## 开发与测试提醒

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