# 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/` 目录下的分析文档