CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

<!-- OPENSPEC:START -->
# OpenSpec Instructions

These instructions are for AI assistants working in this project.

Always open `@/openspec/AGENTS.md` when the request:
- Mentions planning or proposals (words like proposal, spec, change, plan)
- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
- Sounds ambiguous and you need the authoritative spec before coding

Use `@/openspec/AGENTS.md` to learn:
- How to create and apply change proposals
- Spec format and conventions
- Project structure and guidelines

Keep this managed block so 'openspec update' can refresh the instructions.

<!-- OPENSPEC:END -->

## 项目架构

RuoYi-Vue 是一个基于 Spring Boot + Vue 的前后端分离快速开发框架（v3.8.8）。

### 整体结构

```
RuoYi-Vue-master/
├── ruoyi-ui/            # 前端项目（Vue 2 + Element UI）
├── ruoyi-admin/         # Web 服务入口（Spring Boot 主应用）
├── ruoyi-framework/     # 核心框架模块（认证、权限、缓存）
├── ruoyi-system/        # 系统管理模块（用户、角色、菜单等）
├── ruoyi-common/        # 通用工具模块
├── ruoyi-quartz/        # 定时任务模块
├── ruoyi-generator/     # 代码生成模块
├── ibs/                 # 数字支行模块（自定义业务模块）
├── sql/                 # SQL 脚本
├── openspec/            # OpenSpec 规范管理
└── pom.xml              # Maven 父项目配置
```

### 后端模块依赖关系

- **ruoyi-admin**: 主应用，依赖所有其他模块
- **ruoyi-framework**: 核心框架，提供 Spring Security、JWT、Redis 等基础功能
- **ruoyi-system**: 系统管理功能（用户、角色、菜单、部门、岗位、字典、参数、通知公告等）
- **ruoyi-common**: 通用工具类（注解、常量、异常处理、工具类等）
- **ruoyi-quartz**: Quartz 定时任务调度
- **ruoyi-generator**: 代码生成器，支持前后端代码生成
- **ibs**: 自定义业务模块

### 前端目录结构（ruoyi-ui/）

```
ruoyi-ui/
├── src/
│   ├── api/           # API 接口定义
│   ├── assets/        # 静态资源
│   ├── components/    # 通用组件
│   ├── layout/        # 布局组件
│   ├── router/        # 路由配置
│   ├── store/         # Vuex 状态管理
│   ├── utils/         # 工具函数
│   └── views/         # 页面组件
├── public/            # 公共静态资源
├── vue.config.js      # Vue CLI 配置
└── package.json       # 前端依赖管理
```

## 开发命令

### 后端开发

```bash
# 编译整个项目
mvn clean install

# 编译单个模块
mvn clean install -pl ruoyi-admin

# 跳过测试编译
mvn clean install -DskipTests

# 运行主应用（需先编译）
cd ruoyi-admin/target
java -jar ruoyi-admin.jar

# 或使用 Maven 插件运行
cd ruoyi-admin
mvn spring-boot:run
```

### 前端开发

```bash
cd ruoyi-ui

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 生产环境构建
npm run build:prod

# 预发布环境构建
npm run build:stage

# 代码检查
npm run lint
```

### 启动脚本

项目提供了启动脚本：
- Windows: `ry.bat`
- Linux: `./ry.bat` 或 `./ry.sh`

## 技术栈

### 后端

- Spring Boot 2.5.14
- Spring Security 5.7.12（认证授权）
- JWT（Token 认证）
- MyBatis（ORM）
- Redis（缓存）
- Druid（数据库连接池）
- Swagger 3.0（API 文档）
- Quartz（定时任务）
- WebSocket（实时通信）
- EasyExcel（Excel 处理）

### 前端

- Vue 2.6.12
- Element UI 2.15.14
- Vue Router 3.4.9
- Vuex 3.6.0
- Axios 0.28.1（HTTP 客户端）
- ECharts 5.4.0（数据可视化）

## 核心概念

### 认证授权

- 基于 Spring Security + JWT 的无状态认证
- 支持动态权限菜单
- 数据权限控制（基于部门的数据范围）
- Token 存储在 Redis 中，支持过期续期

### 权限控制

- 菜单权限：控制用户可见的功能模块
- 按钮权限：细粒度的操作控制
- 数据权限：控制用户可访问的数据范围

### 代码生成器

使用代码生成器可以一键生成前后端 CRUD 代码：
1. 在数据库中创建表
2. 通过系统菜单的"代码生成"功能导入表
3. 编辑字段信息
4. 生成代码并下载

## 重要配置文件

| 文件路径 | 用途 |
|---------|------|
| [ruoyi-admin/src/main/resources/application.yml](ruoyi-admin/src/main/resources/application.yml) | Spring Boot 主配置 |
| [ruoyi-ui/.env.development](ruoyi-ui/.env.development) | 前端开发环境配置 |
| [ruoyi-ui/vue.config.js](ruoyi-ui/vue.config.js) | Vue CLI 配置 |
| [pom.xml](pom.xml) | Maven 依赖配置 |

## 开发注意事项

### 后端开发

- Controller 层位于各模块的 `controller/` 包
- Service 层分为接口（`service/`）和实现（`service/impl/`）
- Mapper 层使用 MyBatis 注解或 XML 映射
- 实体类使用 JPA 注解（`@Table`, `@Column` 等）
- 使用 `@RequiresPermissions` 注解控制权限

### 前端开发

- API 请求统一在 `src/api/` 目录下定义
- 页面组件放在 `src/views/` 目录下，按模块分组
- 使用 Vuex 管理全局状态（用户信息、权限等）
- 路由配置在 `src/router/` 目录下
- 静态资源放在 `src/assets/` 目录下

### 数据库

- SQL 脚本位于 `sql/` 目录
- 表命名规范：`sys_` 前缀为系统表，业务表可自定义
- 字段包含通用字段：`create_by`, `create_time`, `update_by`, `update_time`, `remark`

## 默认账号

- 用户名: `admin`
- 密码: `admin123`