ccdi/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

**纪检初核系统** - 基于 **若依管理系统 v3.9.1** 构建的企业级前后端分离管理系统，用于员工异常行为风险识别。

### 技术栈版本

| 后端技术                        | 版本     | 前端技术       | 版本      |
|-----------------------------|--------|------------|---------|
| Spring Boot                 | 3.5.8  | Vue.js     | 2.6.12  |
| Java                        | 17     | Element UI | 2.15.14 |
| MyBatis Spring Boot Starter | 3.0.5  | Vuex       | 3.6.0   |
| MySQL Connector             | 8.2.0  | Vue Router | 3.4.9   |
| SpringDoc OpenAPI           | 2.8.14 | Axios      | 0.28.1  |
| EasyExcel                   | 3.3.4  | ECharts    | 5.4.0   |
| Quartz                      | 2.5.2  | Sass       | 1.32.13 |

---

## 常用命令

### 后端 (Maven)

```bash
# 编译项目
mvn clean compile

# 运行应用 (开发环境)
mvn spring-boot:run

# 打包部署
mvn clean package

# Windows 启动
ry.bat

# Linux/Mac 启动
./ry.sh start
```

### 前端 (npm)

```bash
cd ruoyi-ui

# 安装依赖 (推荐使用国内镜像)
npm install --registry=https://registry.npmmirror.com

# 开发服务器 (端口 80)
npm run dev

# 生产构建
npm run build:prod

# 预览生产构建
npm run preview
```

### 数据库初始化

```bash
mysql -u root -p < sql/ry_20250522.sql
mysql -u root -p < sql/quartz.sql
```

---

## 模块架构

```
ccdi/
├── ruoyi-admin/          # 主应用入口 (Spring Boot 启动类)
├── ruoyi-framework/      # 核心框架 (Security, Config, Filters)
├── ruoyi-system/         # 系统管理 (Users, Roles, Menus, Depts)
├── ruoyi-common/         # 通用工具 (annotations, utils, constants)
├── ruoyi-quartz/         # 定时任务
├── ruoyi-generator/      # 代码生成器
├── ruoyi-info-collection/ # 【核心业务模块】信息采集
├── ruoyi-ui/             # 前端 Vue 应用
├── sql/                  # 数据库脚本
├── bin/                  # 启动脚本
└── doc/                  # 项目文档
```

### 模块依赖关系

```
ruoyi-admin (启动模块)
    ├── ruoyi-framework (核心安全配置)
    ├── ruoyi-system (系统核心业务)
    ├── ruoyi-common (共享工具)
    ├── ruoyi-quartz (定时任务)
    ├── ruoyi-generator (代码生成)
    └── ruoyi-info-collection (信息采集模块)
```

### ruoyi-info-collection 业务模块 (核心)

自定义业务模块，包含以下核心功能：

| 功能       | Controller                            | 实体类                         |
|----------|---------------------------------------|-----------------------------|
| 员工基础信息   | CcdiBaseStaffController               | CcdiBaseStaff               |
| 中介黑名单    | CcdiIntermediaryController            | CcdiBizIntermediary         |
| 员工家庭关系   | CcdiStaffFmyRelationController        | CcdiStaffFmyRelation        |
| 员工企业关系   | CcdiStaffEnterpriseRelationController | CcdiStaffEnterpriseRelation |
| 信贷客户家庭关系 | CcdiCustFmyRelationController         | CcdiCustFmyRelation         |
| 信贷客户企业关系 | CcdiCustEnterpriseRelationController  | CcdiCustEnterpriseRelation  |
| 员工调动记录   | CcdiStaffTransferController           | CcdiStaffTransfer           |
| 员工招聘记录   | CcdiStaffRecruitmentController        | CcdiStaffRecruitment        |
| 采购交易     | CcdiPurchaseTransactionController     | CcdiPurchaseTransaction     |

**分层结构:**

- Controller: `ruoyi-info-collection/src/main/java/com/ruoyi/info/collection/controller/`
- Service: `ruoyi-info-collection/src/main/java/com/ruoyi/info/collection/service/`
- Mapper: `ruoyi-info-collection/src/main/java/com/ruoyi/info/collection/mapper/`
- Domain: `ruoyi-info-collection/src/main/java/com/ruoyi/info/collection/domain/`
  - dto/: 数据传输对象
  - vo/: 视图对象
  - excel/: Excel导入导出实体
- XML映射: `ruoyi-info-collection/src/main/resources/mapper/info/collection/`

---

## 后端开发规范

### 通用规范

- **新模块命名**: 项目英文名首字母集合 + 主要功能 (如 `ruoyi-info-collection`)
- **代码分离**: 新功能代码与若依框架自带代码分离，Controller 放在新模块中
- **审计字段**: 实体类不继承 BaseEntity，单独添加审计字段，通过注释实现自动插入

### Java 代码风格

```java
// 使用 @Data 注解
@Data
public class CcdiBaseStaff {
  // 审计字段通过注释实现自动插入
  /** 创建者 */
  private String createBy;
  /** 创建时间 */
  private Date createTime;
  /** 更新者 */
  private String updateBy;
  /** 更新时间 */
  private Date updateTime;
}

  // 服务层使用 @Resource 注入
  @Resource
  private ICcdiBaseStaffService baseStaffService;
```

### 分层规范

- **Controller**: 所有接口添加 Swagger 注释，分页使用 MyBatis Plus Page
- **Service**: 简单 CRUD 用 MyBatis Plus 方法，复杂操作在 XML 写 SQL
- **DTO/VO**: 接口传参使用独立 DTO，返回使用独立 VO，不与 entity 混用

### 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);
```

---

## 前端开发规范

### 目录结构

```
ruoyi-ui/src/
├── api/              # API 请求定义 (与后端 Controller 对应)
├── views/            # 页面组件 (按功能模块组织)
│   ├── ccdiBaseStaff/
│   ├── ccdiIntermediary/
│   └── ...
├── components/       # 可复用组件 (复杂组件需拆分)
├── router/           # 路由配置
└── store/            # Vuex 状态管理
```

### API 调用示例

```javascript
import request from '@/utils/request'

export function listStaff(query) {
  return request({
    url: '/ccdi/baseStaff/list',
    method: 'get',
    params: query
  })
}
```

### 菜单联动

添加页面和组件后，需要同步修改数据库中的菜单表 (`sys_menu`)。

---

## 特殊功能

### 异步导入

支持大数据量异步 Excel 导入，通过 taskId 查询导入状态：

```java
@PostMapping("/import")
public AjaxResult asyncImport(@RequestParam("file") MultipartFile file) {
    String taskId = asyncImportService.startImport(file);
    return AjaxResult.success("导入任务已启动", taskId);
}

@GetMapping("/import/status/{taskId}")
public AjaxResult getImportStatus(@PathVariable String taskId) {
    return AjaxResult.success(asyncImportService.getStatus(taskId));
}
```

### EasyExcel 字典下拉框

导入模板支持字典下拉框配置，提升数据录入准确性。

### 权限控制

基于 Spring Security + JWT 的角色菜单权限系统：

- 权限格式: `system:user:edit`, `ccdi:staff:list`
- 数据权限: 支持全部、自定义、部门等范围

---

## 测试与验证

### 测试账号

- **用户名**: `admin`
- **密码**: `admin123`

### 登录获取 Token

```bash
# 登录接口
POST /login/test?username=admin&password=admin123
```

### API 文档

- **Swagger UI**: `/swagger-ui/index.html`
- **API Docs**: `/v3/api-docs`

### 测试规范

- 不在命令行启动后端进行测试
- 生成可执行的测试脚本进行验证
- 测试完成后保存接口输出并生成测试用例报告

---

## 配置说明

| 配置项     | 值                 |
|---------|-------------------|
| 后端端口    | 8080              |
| 前端开发端口  | 80                |
| 默认管理员   | admin/admin123    |
| JWT 有效期 | 30 分钟             |
| 文件上传限制  | 单文件 10MB, 总计 20MB |

### 配置文件位置

| 配置       | 路径                                                   |
|----------|------------------------------------------------------|
| 主配置      | `ruoyi-admin/src/main/resources/application.yml`     |
| 开发环境     | `ruoyi-admin/src/main/resources/application-dev.yml` |
| 数据库连接    | `application-dev.yml`                                |
| Redis 配置 | `application-dev.yml`                                |

---

## 重要文件路径

| 用途            | 路径                                                                             |
|---------------|--------------------------------------------------------------------------------|
| 应用入口          | `ruoyi-admin/src/main/java/com/ruoyi/RuoYiApplication.java`                    |
| 安全配置          | `ruoyi-framework/src/main/java/com/ruoyi/framework/config/SecurityConfig.java` |
| 业务 Controller | `ruoyi-info-collection/src/main/java/com/ruoyi/info/collection/controller/` |
| 业务 Mapper XML | `ruoyi-info-collection/src/main/resources/mapper/info/collection/`          |
| Vue 路由        | `ruoyi-ui/src/router/index.js`                                                 |
| Vuex Store    | `ruoyi-ui/src/store/`                                                          |
| 前端 API        | `ruoyi-ui/src/api/`                                                            |

---

## 数据库规范

- **新建表名**: 需要加上项目英文名首字母集合前缀 `ccdi_` (如 `ccdi_base_staff`)

---

## 文档管理

- **文档语言**: 使用简体中文编写 .md 文档
- **文档目录**: 所有生成的文档放在 `doc/` 目录下，按类型分类
- **需求分析**: 在 `doc/` 目录下新建文件夹，以需求内容命名

### doc 目录结构

```
doc/
├── api-docs/          # API 文档
├── database/          # 数据库相关
├── design/            # 设计文档
├── implementation/    # 实施文档
├── requirements/      # 需求文档
└── test-scripts/      # 测试脚本
```

---

## OpenSpec 工作流

项目使用 OpenSpec 进行规范驱动开发，参考 `openspec/AGENTS.md`。

### 何时创建 Proposal

**需要创建:**

- 新功能或能力
- 破坏性变更 (API, 数据库结构)
- 架构变更
- 改变行为的性能优化

**无需创建:**

- Bug 修复 (恢复预期行为)
- 拼写错误、格式、注释
- 非破坏性依赖更新
- 配置变更

---

## 沟通规范

- 永远使用简体中文进行思考和对话