wkc/ccdi

Files

优化md

2026-02-24 16:10:27 +08:00

10 KiB

Raw Blame History

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)

# 编译项目
mvn clean compile

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

# 打包部署
mvn clean package

# Windows 启动
ry.bat

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

前端 (npm)

cd ruoyi-ui

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

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

# 生产构建
npm run build:prod

# 预览生产构建
npm run preview

数据库初始化

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 代码风格

// 使用 @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 响应格式

// 成功
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 调用示例

import request from '@/utils/request'

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

菜单联动

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

特殊功能

异步导入

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

@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

# 登录接口
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 修复 (恢复预期行为)
拼写错误、格式、注释
非破坏性依赖更新
配置变更

沟通规范

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

10 KiB Raw Blame History Unescape Escape