185 lines
4.4 KiB
Markdown
185 lines
4.4 KiB
Markdown
<!-- OPENSPEC:START -->
|
||
# 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.
|
||
|
||
<!-- 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 数据库操作时，使用项目配置文件中的数据库
|