@@ -1,327 +1,362 @@
# CLAUDE.md
## 分析
- 在进行需求分析类型的任务时，自动开启深度思考模式，输入 “think more”、“think a lot”、“think harder” 或 “think longer” 触发更深层的思考
- 在进行需求分析与分解任务时，按照不同的模块分为不同的文件，创建模块名的文件夹并将对应文件保存在文件夹中，然后对模块的功能文件进行继续分解
- 在使用/openspec:proposal时， ，
- 在执行/openspec:apply后，
- 在分析生成需求文档时，
## Communication
- 永远使用简体中文进行思考和对话
## Documentation
- 编写 .md 文档时，也要用中文
- 所有生成的文档都放在项目根目录下的doc文件中。
## 数据库规范
- 新建表时，需要加上项目英文名首字母集合
## Coding
### Java Code Style
- 新建模块命名方式为项目英文名首字母集合+主要功能
- 新的功能代码与若依框架自带的代码分离， ，
- 使用 `@Data` 注解保证代码的简洁
- 尽量使用 MyBatis Plus 进行 CRUD 操作（版本 3.5.10，
- 服务层中的使用@Resource注释 ，替代@Autowired
- 实体类不继承BaseEntity，
- 完成后端代码controller层代码生成测试后，
- 接口传参需要使用单独的DTO，
- 需要单独的VO类，
- 审计字段通过添加注释的方式实现自动插入
- 简单的crud操作通过mybatis plus的方法实现，
- 控制层所有接口需要正确的添加注释， ，
- 控制层分页接口使用mybatis plus page，
### 前端代码
- 在添加页面和组件后，注意与数据库中菜单表进行联动修改
- 前端组件代码需要组件化，复杂的组件需要进行拆分为单独的文件
## 运行
- 使用mcp:ccdi_intermediary_blacklist进行数据库相关操作
- 不要在命令行中启动后端进行测试
- 测试方式为生成可执行的测试脚本
- 测试脚本在运行完成后需要保存所有接口输出并生成测试用例报告
- /login/test接口可以传入username和password获取token，
用于测试的账号：
- swagger-ui的地址为/swagger-ui/index.html
- 在向doc文件夹添加文件时需要分门别类添加，
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
## 项目概述
This is a **discipline preliminary check system ** built on the **RuoYi (若依) v3.9.1 ** rapid development framework. It is an enterprise-grade management system using a front-end/back-end separated architecture.
**纪检初核系统 ** - 基于 **若依管理系统 v3.9.1 ** 构建的企业级前后端分离管理系统，用于员工异常行为风险识别。
### Technology Stack
### 技术栈版本
**Backend: **
- Spring Boot 3.5.8
- Security + JWT (authentication)
- MyBatis 3.0.5 (ORM)
- MySQL 8.2.0
- Redis (caching)
- Quartz 2.5.2 (scheduled tasks)
- SpringDoc 2.8.14 (API documentation)
- Java 17
| 后端技术 | 版本 | 前端技术 | 版本 |
|-----------------------------|--------|------------|---------|
| 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 |
**Frontend: **
- Vue 2.6.12
- Element UI 2.15.14
- Vuex 3.6.0 (state management)
- Vue Router 3.4.9
- Axios 0.28.1
---
## Common Commands
## 常用命令
### Backend (Maven)
### 后端 (Maven)
``` bash
# Compile the project
# 编译项目
mvn clean compile
# Run the application (development )
# 运行应用 (开发环境 )
mvn spring-boot:run
# Package for deployment
# 打包部署
mvn clean package
# Run using startup scripts
./ ry.bat # Windows
./ry.sh start # Linux/Mac
# Windows 启动
ry.bat
# Linux/Mac 启动
./ry.sh start
```
### Frontend (npm)
### 前端 (npm)
``` bash
cd ruoyi-ui
# Install dependencies
npm install
# 安装依赖 (推荐使用国内镜像)
npm install --registry= https://registry.npmmirror.com
# Development server (runs on port 80 by default )
# 开发服务器 (端口 80 )
npm run dev
# Production build
# 生产构建
npm run build:prod
# Staging build
npm run build:stage
# Preview production build
# 预览生产构建
npm run preview
```
### Database Initialization
### 数据库初始化
``` bash
# Main database schema
# Quartz scheduler tables
mysql -u root -p < sql/quartz.sql
```
## Project Architecture
---
### Module Structure
## 模块架构
```
scipline-prelim-check /
├── ruoyi-admin/ # Main application entry point
├── ruoyi-framework/ # Core framework (Security, c onfig, f ilters)
├── ruoyi-system/ # System management (Users, Roles, Menus, Depts)
├── ruoyi-common/ # Common utilities (annotations, utils, constants)
├── ruoyi-quartz/ # Scheduled task management
├── ruoyi-generator/ # Code generator (CRUD scaffolding)
├── ruoyi-ui/ # Frontend Vue application
├── sql / # Database scripts
├── bin / # Startup scripts
└ ── openspec/ # OpenSpec specification workflow
cc di/
├── ruoyi-admin/ # 主应用入口 (Spring Boot 启动类)
├── ruoyi-framework/ # 核心框架 (Security, C onfig, F ilters)
├── ruoyi-system/ # 系统管理 (Users, Roles, Menus, Depts)
├── ruoyi-common/ # 通用工具 (annotations, utils, constants)
├── ruoyi-quartz/ # 定时任务
├── ruoyi-generator/ # 代码生成器
├── ruoyi-ccdi/ # 【核心业务模块】纪检初核业务
├── ruoyi-ui / # 前端 Vue 应用
├── sql / # 数据库脚本
├ ── bin/ # 启动脚本
└── doc/ # 项目文档
```
### Backend Architecture: MVC + Modular Design
The backend follows a standard MVC pattern with modular separation:
### 模块依赖关系
```
Controller Layer (ruoyi-admin/web/controller/ )
├── common/ # Common controllers (captcha, file upload )
├── monitor/ # Monitoring controllers (cache, server, logs )
├── system/ # System management (users, roles, menus )
└── tool/ # Tools (code generator, swagger )
Service Layer (ruoyi-system/service/ )
├── ISysUserService.java
├── ISysRoleService.java
└── ...
Mapper Layer (ruoyi-system/mapper/)
├── SysUserMapper.java
├── SysRoleMapper.java
└── ...
Domain Layer (ruoyi-system/domain/)
├── SysUser.java # Entity
├── vo/ # Value objects
└── ...
ruoyi-admin (启动模块 )
├── ruoyi-framework (核心安全配置 )
├── ruoyi-system (系统核心业务 )
├── ruoyi-common (共享工具 )
├── ruoyi-quartz (定时任务 )
├── ruoyi-generator (代码生成)
└── ruoyi-ccdi (纪检业务模块 )
```
### Frontend Architecture: Vue SPA
### 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` )
- **代码分离**: 新功能代码与若依框架自带代码分离，
- **审计字段**: 实体类不继承 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， ，
### 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 ) ;
```
---
## 前端开发规范
### 目录结构
```
├── api/ # API request definitions
├── asset s/ # Static resources (images, styles )
├── components/ # Reusable components
├── layout/ # Main layout (Sidebar, Navbar, TagsView)
├── router/ # Vue Router configuration
├── store/ # Vuex state management
├── utils/ # Utility functions
├ ── views / # Page components organized by feature
│ ├── dashboard/
│ ├── monitor/
│ ├── system/
│ └── tool/
└── permission.js # Permission directives
├── api/ # API 请求定义 (与后端 Controller 对应)
├── view s/ # 页面组件 (按功能模块组织 )
│ ├── ccdiBaseStaff/
│ ├── ccdiIntermediary/
│ └── ...
├── components/ # 可复用组件 (复杂组件需拆分)
├── router/ # 路由配置
└ ── store / # Vuex 状态管理
```
### Module Dependencies
```
↓ depends on
ruoyi-framework (core security & config)
ruoyi-system (system core business)
ruoyi-common (shared utilities)
ruoyi-quartz (scheduled tasks)
ruoyi-generator (code generation)
```
## Key Development Patterns
### Code Generation Workflow
RuoYi provides a powerful code generator for rapid CRUD development:
1. **Create database table ** - Design your table schema
2. **Import table ** - Use System Tools → Code Generation → Import
3. **Configure ** - Edit table info, generate info (module, function name, etc.)
4. **Generate code ** - Download the generated zip
5. **Copy files ** - Extract to appropriate directories:
- Backend: `ruoyi-admin/web/controller/` , service, mapper files
- Frontend: `ruoyi-ui/src/views/` , `ruoyi-ui/src/api/`
### Permission System
The permission system uses **Role-Menu-Button ** hierarchy:
- **Menus**: Define navigation items and route permissions
- **Roles**: Assign menu permissions to roles
- **Users**: Assign roles to users
- **Data Permissions**: Control data scope (all, custom, department, etc.)
Permission keys in code use format: `system:user:edit` , `system:user:remove` , etc.
### API Response Format
All API responses use `AjaxResult` wrapper:
``` java
// Success
AjaxResult . success ( " 操作成功 " , data ) ;
// Error
AjaxResult . error ( " 操作失败 " ) ;
// Custom
AjaxResult . put ( " key " , value ) ;
```
### Frontend API Calls
API calls are defined in `ruoyi-ui/src/api/` :
### API 调用示例
``` javascript
import request from '@/utils/request'
export function listUser ( query ) {
export function listStaff ( query ) {
return request ( {
url : '/system/user /list' ,
url : '/ccdi/baseStaff /list' ,
method : 'get' ,
params : query
} )
}
```
export function addUser ( data ) {
return request ( {
url : '/system/user' ,
method : 'post' ,
data : data
} )
### 菜单联动
添加页面和组件后，需要同步修改数据库中的菜单表 (`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 ) ) ;
}
```
## OpenSpec Workflow
### EasyExcel 字典下拉框
This project uses **OpenSpec ** for specification-driven development. Always reference `openspec/AGENTS.md` when:
导入模板支持字典下拉框配置，提升数据录入准确性。
- Planning or proposing new features
- Making breaking changes
- Modifying architecture
- Handling ambiguous requirements
### 权限控制
### Key OpenSpec Commands
基于 Spring Security + JWT 的角色菜单权限系统：
- 权限格式: `system:user:edit` , `ccdi:staff:list`
- 数据权限: 支持全部、自定义、部门等范围
---
## 测试与验证
### 测试账号
- **用户名**: `admin`
- **密码**: `admin123`
### 登录获取 Token
``` bash
# List active changes
openspec list
# List all specifications
openspec list --specs
# View details
openspec show [ change-id or spec-id]
# Validate changes
openspec validate [ change-id] --strict --no-interactive
# Archive completed changes
openspec archive <change-id>
# 登录接口
POST /login/test?username= admin& password = admin123
```
### When to Create Proposals
### API 文档
**Create proposal for: **
- New features or capabilities
- Breaking changes (API, schema)
- Architecture changes
- Performance optimizations that change behavior
- **Swagger UI**: `/swagger-ui/index.html`
- **API Docs**: `/v3/api-docs`
**Skip proposal for: **
- Bug fixes (restoring intended behavior)
- Typos, formatting, comments
- Non-breaking dependency updates
- Configuration changes
### 测试规范
## Configuration Notes
- 不在命令行启动后端进行测试
- 生成可执行的测试脚本进行验证
- 测试完成后保存接口输出并生成测试用例报告
- **Default Admin**: `admin/admin123`
- **Backend Port**: 8080
- **Frontend Dev Port**: 80
- **API Base Path**: Configured in `ruoyi-ui/vue.config.js` proxy
- **Database Config**: `ruoyi-admin/src/main/resources/application.yml`
---
## Important File Locations
## 配置说明
| Purpose | Location |
|---------|----------|
| Main application entry | [ruoyi-admin/src/main/java/com/ruoyi/RuoYiApplication.java ](ruoyi-admin/src/main/java/com/ruoyi/RuoYiApplication.java ) |
| Security configuration | [ruoyi-framework/src/main/java/com/ruoyi/framework/config/SecurityConfig.java ](ruoyi-framework/src/main/java/com/ruoyi/framework/config/SecurityConfig.java ) |
| Database config | [ruoyi-admin/src/main/resources/application.yml ](ruoyi-admin/src/main/resources/application.yml ) |
| MyBatis mappers | [ruoyi-system/src/main/resources/mapper/system/ ](ruoyi-system/src/main/resources/mapper/system/ ) |
| Vue router | [ruoyi-ui/src/router/index.js ](ruoyi-ui/src/router/index.js ) |
| Vuex store | [ruoyi-ui/src/store/ ](ruoyi-ui/src/store/ ) |
| 配置项 | 值 |
|---------|------------------- |
| 后端端口 | 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 目录结构
```
├── api-docs/ # API 文档
├── database/ # 数据库相关
├── design/ # 设计文档
├── implementation/ # 实施文档
├── requirements/ # 需求文档
└── test-scripts/ # 测试脚本
```
---
## OpenSpec 工作流
项目使用 OpenSpec 进行规范驱动开发，参考 `openspec/AGENTS.md` 。
### 何时创建 Proposal
**需要创建: **
- 新功能或能力
- 破坏性变更 (API, 数据库结构)
- 架构变更
- 改变行为的性能优化
**无需创建: **
- Bug 修复 (恢复预期行为)
- 拼写错误、格式、注释
- 非破坏性依赖更新
- 配置变更
---
## 沟通规范
- 永远使用简体中文进行思考和对话
