ccdi/AGENTS.md

OpenSpec Instructions

These instructions are for AI assistants working in this project.

Always open @/openspec/AGENTS.md when the request:

• Mentions planning or proposals (words like proposal, spec, change, plan)
• Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
• Sounds ambiguous and you need the authoritative spec before coding

Use @/openspec/AGENTS.md to learn:

• How to create and apply change proposals
• Spec format and conventions
• Project structure and guidelines

Keep this managed block so 'openspec update' can refresh the instructions.

AGENTS.md - AI Coding Assistant Guide

项目概述

基于若依 v3.9.1 的纪检初核系统，Java 21 + Spring Boot 3 + Vue 2

---

Build / Lint / Test Commands

后端 (Maven)

# 编译项目
mvn clean compile

# 运行应用
mvn spring-boot:run

# 打包部署
mvn clean package

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

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

# 跳过测试
mvn clean package -DskipTests

前端 (npm)

cd ruoyi-ui

# 安装依赖
npm install --registry=https://registry.npmmirror.com

# 开发服务器
npm run dev

# 生产构建
npm run build:prod

API 测试

# 获取 Token (测试账号: admin/admin123)
POST http://localhost:8080/login/test?username=admin&password=admin123

# Swagger 文档
http://localhost:8080/swagger-ui/index.html

---

代码规范

Java 代码风格

• 注解: 使用 Lombok @Data 简化实体类
• 依赖注入: 使用 @Resource 而非 @Autowired
• 实体类: 不继承 BaseEntity，单独添加审计字段
• 禁止: 禁止使用全限定类名 (如 java.util.List)，必须 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
• Service: 简单 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_ 前缀 (如 ccdi_base_staff)
• 非业务字段 (create_by, create_time 等) 由后端自动处理，前端表单不显示

前端规范

• 目录结构: views/ 按功能模块组织，api/ 对应后端 Controller
• API 调用: 使用 @/utils/request 封装
• 菜单联动: 添加页面后需同步修改数据库 sys_menu 表

导入功能规范

• 批量操作提高性能
• 返回结果只展示失败数据，不展示成功数据
• 使用 EasyExcel + 异步处理大数据量导入

---

模块架构

ccdi/
├── ruoyi-admin/           # 启动入口
├── ruoyi-framework/       # 安全配置
├── ruoyi-system/          # 系统模块
├── ruoyi-common/          # 通用工具
├── ccdi-info-collection/  # 信息采集 (员工、中介、黑名单)
├── ccdi-project/          # 项目管理
├── ccdi-lsfx/             # 流水分析对接
└── ruoyi-ui/              # 前端

添加新模块

1. 根 pom.xml 添加 <module>
2. pom.xml 添加 ruoyi-common 依赖
3. ruoyi-admin/pom.xml 添加模块依赖
4. 按分层创建 controller/service/mapper/domain 包

---

常用路径

用途	路径
应用入口	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/
Vue 路由	ruoyi-ui/src/router/index.js

---

沟通规范

• 使用简体中文进行思考和对话
• 遇到 MCP 数据库操作时，使用项目配置文件中的数据库