6114f9eeb5
- 添加CLAUDE.md项目配置指南 - 添加document目录包含详细的架构分析文档 - 添加doc目录包含环境使用手册 - 添加bin目录包含构建和清理脚本 - 添加.github配置文件
463 lines
12 KiB
Markdown
463 lines
12 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
# 项目概述
|
||
|
||
这是一个基于 RuoYi Vue 3.9.0 的前后端分离企业级管理系统，采用 Spring Boot + Vue 架构。项目包含完整的用户权限管理、系统监控、代码生成等企业级功能。
|
||
|
||
## 核心技术架构
|
||
|
||
**后端架构：**
|
||
- Spring Boot 2.5.15 + Java 1.8
|
||
- Spring Security + JWT 认证
|
||
- MySQL + Druid 连接池 + MyBatis + PageHelper
|
||
- Redis 缓存 + Quartz 定时任务
|
||
|
||
**前端架构：**
|
||
- Vue 2.6.12 + Vue Router + Vuex
|
||
- Element UI 2.15.14 + Axios
|
||
|
||
**模块结构：**
|
||
```
|
||
RuoYi-Vue-master/
|
||
├── ruoyi-admin/ # Spring Boot 启动模块，包含所有 REST API
|
||
├── ruoyi-framework/ # 框架核心（安全配置、Web配置、切面等）
|
||
├── ruoyi-system/ # 系统业务模块（用户、角色、权限等核心业务）
|
||
├── ruoyi-common/ # 通用工具类和常量定义
|
||
├── ruoyi-generator/ # MyBatis 代码生成器模块
|
||
├── ruoyi-quartz/ # 定时任务模块
|
||
├── ruoyi-ui/ # Vue 前端项目
|
||
└── sql/ # 数据库初始化脚本
|
||
```
|
||
|
||
## 常用开发命令
|
||
|
||
**后端开发：**
|
||
```bash
|
||
# 清理和构建项目
|
||
mvn clean install -Dmaven.test.skip=true
|
||
|
||
# 启动后端服务（开发环境）
|
||
cd ruoyi-admin
|
||
mvn spring-boot:run
|
||
|
||
# 使用脚本启动/停止/重启服务（生产环境）
|
||
./ry.sh start # 启动服务
|
||
./ry.sh stop # 停止服务
|
||
./ry.sh restart # 重启服务
|
||
./ry.sh status # 查看状态
|
||
|
||
# 打包生产版本
|
||
mvn clean package -Dmaven.test.skip=true
|
||
```
|
||
|
||
**前端开发：**
|
||
```bash
|
||
cd ruoyi-ui
|
||
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 启动开发服务器 (http://localhost:80)
|
||
npm run dev
|
||
|
||
# 构建生产版本
|
||
npm run build:prod
|
||
|
||
# 构建预生产版本
|
||
npm run build:stage
|
||
```
|
||
|
||
## 核心架构设计
|
||
|
||
### 1. 权限控制体系
|
||
|
||
**RBAC权限模型：**
|
||
- 用户(User) -> 角色(Role) -> 权限(Permission) 三层关联
|
||
- 支持数据权限：全部数据、自定义数据、本部门数据、本部门及以下、仅本人数据
|
||
- 菜单权限：控制页面访问
|
||
- 按钮权限：控制页面内操作按钮显示
|
||
- 使用 `@PreAuthorize("@ss.hasPermi('system:user:list')")` 进行接口权限控制
|
||
- 使用 `@DataScope` 注解进行数据权限控制
|
||
|
||
### 2. 安全认证机制
|
||
|
||
**JWT + Spring Security：**
|
||
- 前后端分离，使用 JWT Token 进行无状态认证
|
||
- Token 存储在 Redis 中，支持主动失效和超时控制
|
||
- 登录验证码防暴力破解
|
||
- 密码使用 BCrypt 加密存储
|
||
- 支持在线用户管理和强制下线
|
||
|
||
### 3. 代码生成器架构
|
||
|
||
**核心优势功能：**
|
||
- 基于数据库表结构自动生成完整 CRUD 代码
|
||
- 支持单表、主子表、树表三种模板
|
||
- 同时生成后端代码（Entity、Mapper、Service、Controller）和前端代码（Vue 页面、API接口）
|
||
- 使用 Velocity 模板引擎，支持自定义模板
|
||
- 可配置字段显示类型、查询方式、是否必填等属性
|
||
|
||
### 4. 数据访问层设计
|
||
|
||
**MyBatis + 分页 + 缓存：**
|
||
- 使用 MyBatis 作为 ORM 框架，SQL 可控
|
||
- PageHelper 插件实现分页功能
|
||
- 动态 SQL 支持复杂查询条件
|
||
- Redis 缓存热点数据（如字典、用户信息）
|
||
- 使用 `@DataScope` 实现数据权限过滤
|
||
|
||
### 5. 前端架构模式
|
||
|
||
**组件化 + 状态管理：**
|
||
- 采用 Vue 2.x 组件化开发
|
||
- Vuex 集中状态管理（用户信息、权限、路由等）
|
||
- 动态路由：根据用户权限动态生成菜单和路由
|
||
- 统一的 API 调用封装和错误处理
|
||
- Element UI 提供企业级组件库
|
||
|
||
## 业务核心模块
|
||
|
||
### 系统管理模块
|
||
- **用户管理**：用户CRUD、角色分配、部门关联、状态控制
|
||
- **角色管理**：角色权限分配、数据权限设置
|
||
- **菜单管理**：动态菜单、权限标识、按钮权限
|
||
- **部门管理**：树形组织架构、数据权限范围控制
|
||
- **字典管理**：系统配置项统一管理，支持前端动态获取
|
||
|
||
### 系统监控模块
|
||
- **操作日志**：使用 `@Log` 注解自动记录操作行为
|
||
- **登录日志**：登录行为监控，IP地理位置解析
|
||
- **在线用户**：实时会话管理，支持强制下线
|
||
- **定时任务**：基于 Quartz 的任务调度管理
|
||
- **系统监控**：CPU、内存、磁盘等系统指标监控
|
||
- **缓存监控**：Redis 缓存状态和性能监控
|
||
|
||
## 配置和环境
|
||
|
||
**关键配置文件：**
|
||
- `ruoyi-admin/src/main/resources/application.yml` - 主配置文件
|
||
- `ruoyi-admin/src/main/resources/application-druid.yml` - 数据源配置
|
||
- `ruoyi-ui/.env.development` - 前端开发环境配置
|
||
- `ruoyi-ui/vue.config.js` - Vue CLI 构建配置
|
||
|
||
**数据库要求：**
|
||
- MySQL 5.7+
|
||
- Redis 6.0+
|
||
- 需执行 `sql/` 目录下的初始化脚本
|
||
|
||
**访问地址：**
|
||
- 前端应用：http://localhost（开发环境）
|
||
- 后端接口：http://localhost:8080
|
||
- 接口文档：http://localhost:8080/swagger-ui.html
|
||
- Druid监控：http://localhost:8080/druid（admin/123456）
|
||
|
||
## 开发规范要点
|
||
|
||
### 🚨 核心编码规范 (MANDATORY)
|
||
|
||
#### 注释规范 - 严格执行
|
||
**【必须遵守】注释规范：**
|
||
- ✅ **只允许行首注释** - 所有注释必须独占一行，位于代码行之前
|
||
- ❌ **严禁行尾注释** - 绝不允许在代码行尾添加注释
|
||
- 📝 **注释内容要求** - 注释必须简洁明了，解释代码的业务意图和逻辑
|
||
|
||
**✅ 正确的注释示例：**
|
||
```javascript
|
||
// 获取用户列表数据
|
||
const getUserList = async () => {
|
||
// 构建查询参数
|
||
const params = {
|
||
pageNum: 1,
|
||
pageSize: 10
|
||
}
|
||
|
||
// 调用API接口
|
||
const response = await listUser(params)
|
||
|
||
// 更新表格数据
|
||
tableData.value = response.rows
|
||
}
|
||
```
|
||
|
||
```java
|
||
/**
|
||
* 查询用户列表
|
||
* @param user 用户查询条件
|
||
* @return 用户列表
|
||
*/
|
||
public TableDataInfo list(SysUser user) {
|
||
// 开始分页
|
||
startPage();
|
||
|
||
// 查询用户列表
|
||
List<SysUser> list = userService.selectUserList(user);
|
||
|
||
// 返回分页结果
|
||
return getDataTable(list);
|
||
}
|
||
```
|
||
|
||
**❌ 错误的注释示例：**
|
||
```javascript
|
||
const getUserList = async () => {
|
||
const params = { pageNum: 1, pageSize: 10 } // 构建查询参数 ❌
|
||
const response = await listUser(params) // 调用API接口 ❌
|
||
tableData.value = response.rows // 更新表格数据 ❌
|
||
}
|
||
```
|
||
|
||
#### 命名规范
|
||
**变量和函数命名：**
|
||
- 使用有意义的英文单词，避免拼音和缩写
|
||
- JavaScript: 小驼峰命名 `getUserInfo`、`tableData`
|
||
- Java: 小驼峰命名 `selectUserList`、`userService`
|
||
- 常量使用大写下划线 `MAX_PAGE_SIZE`、`DEFAULT_PASSWORD`
|
||
|
||
**组件和类命名：**
|
||
- Vue组件: 大驼峰命名 `UserManagement.vue`、`DictTag.vue`
|
||
- Java类: 大驼峰命名 `SysUserController`、`UserServiceImpl`
|
||
|
||
### 后端开发规范
|
||
|
||
**控制器层 (Controller):**
|
||
```java
|
||
/**
|
||
* 用户管理控制器
|
||
*/
|
||
@RestController
|
||
@RequestMapping("/system/user")
|
||
public class SysUserController extends BaseController {
|
||
|
||
@Autowired
|
||
private ISysUserService userService;
|
||
|
||
/**
|
||
* 查询用户列表
|
||
*/
|
||
@PreAuthorize("@ss.hasPermi('system:user:list')")
|
||
@GetMapping("/list")
|
||
public TableDataInfo list(SysUser user) {
|
||
// 开始分页
|
||
startPage();
|
||
|
||
// 查询用户列表
|
||
List<SysUser> list = userService.selectUserList(user);
|
||
|
||
// 返回分页结果
|
||
return getDataTable(list);
|
||
}
|
||
}
|
||
```
|
||
|
||
**服务层 (Service):**
|
||
```java
|
||
/**
|
||
* 用户业务层实现
|
||
*/
|
||
@Service
|
||
public class SysUserServiceImpl implements ISysUserService {
|
||
|
||
@Autowired
|
||
private SysUserMapper userMapper;
|
||
|
||
/**
|
||
* 根据条件查询用户列表
|
||
*/
|
||
@Override
|
||
@DataScope(deptAlias = "d", userAlias = "u")
|
||
public List<SysUser> selectUserList(SysUser user) {
|
||
// 调用数据访问层查询
|
||
return userMapper.selectUserList(user);
|
||
}
|
||
}
|
||
```
|
||
|
||
**实体类 (Entity):**
|
||
```java
|
||
/**
|
||
* 用户对象
|
||
*/
|
||
public class SysUser extends BaseEntity {
|
||
|
||
/**
|
||
* 用户ID
|
||
*/
|
||
private Long userId;
|
||
|
||
/**
|
||
* 用户账号
|
||
*/
|
||
private String userName;
|
||
|
||
/**
|
||
* 用户昵称
|
||
*/
|
||
private String nickName;
|
||
|
||
// getter和setter方法...
|
||
}
|
||
```
|
||
|
||
**核心规范要点：**
|
||
- 继承 `BaseController` 获取通用方法
|
||
- 使用 `AjaxResult` 统一返回格式
|
||
- 业务异常统一抛出 `ServiceException`
|
||
- 实体类继承 `BaseEntity` 获取审计字段
|
||
- Mapper接口使用 `@Mapper` 注解
|
||
- 权限注解 `@PreAuthorize` 进行接口权限控制
|
||
- 数据权限注解 `@DataScope` 进行数据范围控制
|
||
- 操作日志注解 `@Log` 记录操作行为
|
||
|
||
### 前端开发规范
|
||
|
||
**Vue组件结构：**
|
||
```vue
|
||
<template>
|
||
<!-- 页面模板 -->
|
||
<div class="app-container">
|
||
<!-- 查询条件 -->
|
||
<el-form :model="queryParams" ref="queryForm" size="small" :inline="true">
|
||
<!-- 表单项... -->
|
||
</el-form>
|
||
|
||
<!-- 表格数据 -->
|
||
<el-table v-loading="loading" :data="userList">
|
||
<!-- 表格列... -->
|
||
</el-table>
|
||
</div>
|
||
</template>
|
||
|
||
<script>
|
||
// 导入API接口
|
||
import { listUser, getUser, delUser, addUser, updateUser } from "@/api/system/user"
|
||
|
||
export default {
|
||
name: "User",
|
||
data() {
|
||
return {
|
||
// 遮罩层
|
||
loading: true,
|
||
// 用户表格数据
|
||
userList: [],
|
||
// 查询参数
|
||
queryParams: {
|
||
pageNum: 1,
|
||
pageSize: 10,
|
||
userName: null
|
||
}
|
||
}
|
||
},
|
||
created() {
|
||
// 初始化获取数据
|
||
this.getList()
|
||
},
|
||
methods: {
|
||
/**
|
||
* 查询用户列表
|
||
*/
|
||
getList() {
|
||
// 设置加载状态
|
||
this.loading = true
|
||
|
||
// 调用API接口
|
||
listUser(this.queryParams).then(response => {
|
||
// 更新表格数据
|
||
this.userList = response.rows
|
||
this.total = response.total
|
||
this.loading = false
|
||
})
|
||
}
|
||
}
|
||
}
|
||
</script>
|
||
```
|
||
|
||
**API接口定义：**
|
||
```javascript
|
||
// 导入请求工具
|
||
import request from '@/utils/request'
|
||
|
||
/**
|
||
* 查询用户列表
|
||
* @param {Object} query 查询参数
|
||
*/
|
||
export function listUser(query) {
|
||
return request({
|
||
url: '/system/user/list',
|
||
method: 'get',
|
||
params: query
|
||
})
|
||
}
|
||
|
||
/**
|
||
* 查询用户详细
|
||
* @param {Number} userId 用户ID
|
||
*/
|
||
export function getUser(userId) {
|
||
return request({
|
||
url: '/system/user/' + userId,
|
||
method: 'get'
|
||
})
|
||
}
|
||
```
|
||
|
||
**核心规范要点：**
|
||
- 组件命名使用大驼峰 (PascalCase)
|
||
- API接口统一在 `src/api/` 目录定义
|
||
- 使用 `v-hasPermi` 指令控制按钮权限显示
|
||
- 表单验证使用 Element UI 验证机制
|
||
- 路由懒加载: `component: () => import('@/views/system/user/index')`
|
||
- 统一错误处理和Loading状态管理
|
||
- 使用 Vuex 管理全局状态(用户信息、权限等)
|
||
|
||
### 代码质量规范
|
||
|
||
**函数和方法：**
|
||
- 单一职责原则，一个函数只做一件事
|
||
- 函数长度不超过50行，复杂逻辑拆分为多个函数
|
||
- 参数个数不超过5个，多参数使用对象传递
|
||
- 返回值类型保持一致
|
||
|
||
**异常处理：**
|
||
```java
|
||
// 业务异常处理
|
||
try {
|
||
// 业务逻辑
|
||
userService.insertUser(user);
|
||
} catch (Exception e) {
|
||
// 记录错误日志
|
||
log.error("新增用户失败：{}", e.getMessage());
|
||
// 抛出业务异常
|
||
throw new ServiceException("新增用户失败");
|
||
}
|
||
```
|
||
|
||
```javascript
|
||
// 前端错误处理
|
||
try {
|
||
// 调用API接口
|
||
const response = await addUser(this.form)
|
||
|
||
// 操作成功提示
|
||
this.$modal.msgSuccess("新增成功")
|
||
} catch (error) {
|
||
// 错误提示已由统一拦截器处理
|
||
console.error('添加用户失败', error)
|
||
}
|
||
```
|
||
|
||
**性能优化规范：**
|
||
- 避免不必要的数据库查询
|
||
- 合理使用缓存机制
|
||
- 前端组件懒加载和代码分割
|
||
- 图片压缩和CDN加速
|
||
|
||
## 重要说明
|
||
|
||
- 该项目专为企业级后台管理系统设计，包含完整的权限管理和系统监控功能
|
||
- 代码生成器是核心优势，能显著提升 CRUD 功能的开发效率
|
||
- 前后端分离架构，支持团队并行开发
|
||
- 基于成熟的开源技术栈，便于维护和扩展
|
||
- 详细的架构分析和使用指南请参考 `document/` 目录下的分析文档 |