363 lines
10 KiB
Markdown
363 lines
10 KiB
Markdown
# 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-ccdi/ # 【核心业务模块】纪检初核业务
|
||
├── ruoyi-ui/ # 前端 Vue 应用
|
||
├── sql/ # 数据库脚本
|
||
├── bin/ # 启动脚本
|
||
└── doc/ # 项目文档
|
||
```
|
||
|
||
### 模块依赖关系
|
||
|
||
```
|
||
ruoyi-admin (启动模块)
|
||
├── ruoyi-framework (核心安全配置)
|
||
├── ruoyi-system (系统核心业务)
|
||
├── ruoyi-common (共享工具)
|
||
├── ruoyi-quartz (定时任务)
|
||
├── ruoyi-generator (代码生成)
|
||
└── ruoyi-ccdi (纪检业务模块)
|
||
```
|
||
|
||
### ruoyi-ccdi 业务模块 (核心)
|
||
|
||
自定义业务模块，包含以下核心功能：
|
||
|
||
| 功能 | Controller | 实体类 |
|
||
|----------|---------------------------------------|-----------------------------|
|
||
| 员工基础信息 | CcdiBaseStaffController | CcdiBaseStaff |
|
||
| 中介黑名单 | CcdiIntermediaryController | CcdiBizIntermediary |
|
||
| 员工家庭关系 | CcdiStaffFmyRelationController | CcdiStaffFmyRelation |
|
||
| 员工企业关系 | CcdiStaffEnterpriseRelationController | CcdiStaffEnterpriseRelation |
|
||
| 信贷客户家庭关系 | CcdiCustFmyRelationController | CcdiCustFmyRelation |
|
||
| 信贷客户企业关系 | CcdiCustEnterpriseRelationController | CcdiCustEnterpriseRelation |
|
||
| 员工调动记录 | CcdiStaffTransferController | CcdiStaffTransfer |
|
||
| 员工招聘记录 | CcdiStaffRecruitmentController | CcdiStaffRecruitment |
|
||
| 采购交易 | CcdiPurchaseTransactionController | CcdiPurchaseTransaction |
|
||
|
||
**分层结构:**
|
||
|
||
- Controller: `ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/controller/`
|
||
- Service: `ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/service/`
|
||
- Mapper: `ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/mapper/`
|
||
- Domain: `ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/domain/`
|
||
- dto/: 数据传输对象
|
||
- vo/: 视图对象
|
||
- excel/: Excel导入导出实体
|
||
- XML映射: `ruoyi-ccdi/src/main/resources/mapper/ccdi/`
|
||
|
||
---
|
||
|
||
## 后端开发规范
|
||
|
||
### 通用规范
|
||
|
||
- **新模块命名**: 项目英文名首字母集合 + 主要功能 (如 `ruoyi-ccdi`)
|
||
- **代码分离**: 新功能代码与若依框架自带代码分离，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-ccdi/src/main/java/com/ruoyi/ccdi/controller/` |
|
||
| 业务 Mapper XML | `ruoyi-ccdi/src/main/resources/mapper/ccdi/` |
|
||
| Vue 路由 | `ruoyi-ui/src/router/index.js` |
|
||
| Vuex Store | `ruoyi-ui/src/store/` |
|
||
| 前端 API | `ruoyi-ui/src/api/` |
|
||
|
||
---
|
||
|
||
## 数据库规范
|
||
|
||
- **新建表名**: 需要加上项目英文名首字母集合前缀 (如 `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 修复 (恢复预期行为)
|
||
- 拼写错误、格式、注释
|
||
- 非破坏性依赖更新
|
||
- 配置变更
|
||
|
||
---
|
||
|
||
## 沟通规范
|
||
|
||
- 永远使用简体中文进行思考和对话
|