# 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 page = new Page<>(pageNum, pageSize); IPage 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 修复 (恢复预期行为) - 拼写错误、格式、注释 - 非破坏性依赖更新 - 配置变更 --- ## 沟通规范 - 永远使用简体中文进行思考和对话