wkc/ccdi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
60a7906eb3742787e61504df0c128dcf46ac06b6
ccdi/AGENTS.md

13 KiB
Raw Blame History

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)

# 根目录编译全部 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)

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)

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 调试

# 测试登录（默认测试账号）
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 引入
@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 响应格式

// 成功
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 + 异步处理

当前仓库结构

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 版本
Reference in New Issue View Git Blame Copy Permalink