docs: 完善 AGENTS.md 添加构建命令和代码规范

2026-03-06 09:43:09 +08:00
parent 5c7e30275e
commit 4b0ccb194b
1 changed files with 167 additions and 1 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,4 +15,170 @@ Use `@/openspec/AGENTS.md` to learn:

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

-<!-- OPENSPEC:END -->
+<!-- OPENSPEC:END -->
+
+# AGENTS.md - AI Coding Assistant Guide
+
+## 项目概述
+
+基于若依 v3.9.1 的纪检初核系统，Java 21 + Spring Boot 3 + Vue 2
+
+---
+
+## Build / Lint / Test Commands
+
+### 后端 (Maven)
+
+```bash
+# 编译项目
+mvn clean compile
+
+# 运行应用
+mvn spring-boot:run
+
+# 打包部署
+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
+```
+
+### API 测试
+
+```bash
+# 获取 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
+
+```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
+- **Service**: 简单 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_` 前缀 (如 `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 数据库操作时，使用项目配置文件中的数据库