<!-- 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 数据库操作时，使用项目配置文件中的数据库