RuoYi-Vue-master/CLAUDE.md

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/                 # 数据库初始化脚本

常用开发命令

后端开发：

# 清理和构建项目
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

前端开发：

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)

注释规范 - 严格执行

【必须遵守】注释规范：

• ✅ 只允许行首注释 - 所有注释必须独占一行，位于代码行之前
• ❌ 严禁行尾注释 - 绝不允许在代码行尾添加注释
• 📝 注释内容要求 - 注释必须简洁明了，解释代码的业务意图和逻辑

✅ 正确的注释示例：

// 获取用户列表数据
const getUserList = async () => {
  // 构建查询参数
  const params = {
    pageNum: 1,
    pageSize: 10
  }
  
  // 调用API接口
  const response = await listUser(params)
  
  // 更新表格数据
  tableData.value = response.rows
}

/**
 * 查询用户列表
 * @param user 用户查询条件
 * @return 用户列表
 */
public TableDataInfo list(SysUser user) {
    // 开始分页
    startPage();
    
    // 查询用户列表
    List<SysUser> list = userService.selectUserList(user);
    
    // 返回分页结果
    return getDataTable(list);
}

❌ 错误的注释示例：

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):

/**
 * 用户管理控制器
 */
@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):

/**
 * 用户业务层实现
 */
@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):

/**
 * 用户对象
 */
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组件结构：

<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接口定义：

// 导入请求工具
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个，多参数使用对象传递
• 返回值类型保持一致

异常处理：

// 业务异常处理
try {
    // 业务逻辑
    userService.insertUser(user);
} catch (Exception e) {
    // 记录错误日志
    log.error("新增用户失败：{}", e.getMessage());
    // 抛出业务异常
    throw new ServiceException("新增用户失败");
}

// 前端错误处理
try {
  // 调用API接口
  const response = await addUser(this.form)
  
  // 操作成功提示
  this.$modal.msgSuccess("新增成功")
} catch (error) {
  // 错误提示已由统一拦截器处理
  console.error('添加用户失败', error)
}

性能优化规范：

• 避免不必要的数据库查询
• 合理使用缓存机制
• 前端组件懒加载和代码分割
• 图片压缩和CDN加速

重要说明

• 该项目专为企业级后台管理系统设计，包含完整的权限管理和系统监控功能
• 代码生成器是核心优势，能显著提升 CRUD 功能的开发效率
• 前后端分离架构，支持团队并行开发
• 基于成熟的开源技术栈，便于维护和扩展
• 详细的架构分析和使用指南请参考 document/ 目录下的分析文档