# CLAUDE.md

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

## 项目概述

这是一个基于 RuoYi-Vue-Plus 5.5.1 的分布式多租户管理系统,采用前后端分离架构:
- **后端**: Spring Boot 3.5.7 + JDK 17/21 + MyBatis-Plus
- **前端**: Vue 3 + TypeScript + Element Plus + Vite

## 开发环境要求

### 后端
- JDK 17 或 JDK 21
- Maven 3.6+
- MySQL 5.7+ / Oracle / PostgreSQL / SQL Server

### 前端
- Node.js >= 18.18.0
- npm >= 8.9.0

## 常用命令

### 后端开发

```bash
# 编译项目(跳过测试)
mvn clean install -DskipTests

# 运行项目(默认 dev 环境)
mvn spring-boot:run

# 运行项目(指定环境)
mvn spring-boot:run -Plocal
mvn spring-boot:run -Pprod

# 运行单元测试
mvn test

# 打包生产环境
mvn clean package -Pprod

# 主应用入口
# ruoyi-admin/src/main/java/org/dromara/DromaraApplication.java
```

### 前端开发

```bash
# 进入前端目录
cd plus-ui

# 安装依赖
npm install --registry=https://registry.npmmirror.com

# 启动开发服务器 (http://localhost:80)
npm run dev

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

# 构建开发环境
npm run build:dev

# 代码检查和修复
npm run lint:eslint:fix

# 代码格式化
npm prettier
```

### Docker 部署

```bash
# 使用 docker-compose 启动所有服务(MySQL + Redis + Nginx 等)
cd script/docker
docker-compose up -d

# 停止所有服务
docker-compose down
```

## 项目架构

### 后端模块结构

```
ruoyi-vue-plus/
├── ruoyi-admin/              # 主应用模块,Web服务入口
├── ruoyi-common/             # 通用模块(插件化架构)
│   ├── ruoyi-common-core/       # 核心模块
│   ├── ruoyi-common-mybatis/    # MyBatis-Plus 集成
│   ├── ruoyi-common-security/   # Sa-Token 安全认证
│   ├── ruoyi-common-oss/        # 对象存储(S3/Minio)
│   ├── ruoyi-common-doc/        # SpringDoc API文档
│   ├── ruoyi-common-redis/      # Redis 缓存
│   ├── ruoyi-common-job/        # SnailJob 定时任务
│   ├── ruoyi-common-json/       # Jackson 序列化
│   ├── ruoyi-common-log/        # 操作日志
│   ├── ruoyi-common-web/        # Web 配置
│   ├── ruoyi-common-translation/# 数据翻译
│   ├── ruoyi-common-encrypt/    # 数据加解密
│   ├── ruoyi-common-sensitive/  # 数据脱敏
│   ├── ruoyi-common-idempotent/ # 幂等处理
│   ├── ruoyi-common-ratelimiter/# 限流
│   ├── ruoyi-common-social/     # 第三方登录
│   ├── ruoyi-common-sms/        # 短信服务
│   ├── ruoyi-common-mail/       # 邮件服务
│   └── ruoyi-common-websocket/  # WebSocket/SSE
├── ruoyi-modules/            # 业务模块
│   ├── ruoyi-system/            # 系统管理模块
│   ├── ruoyi-generator/         # 代码生成器
│   ├── ruoyi-demo/              # 演示案例
│   ├── ruoyi-workflow/          # 工作流模块(Warm-Flow)
│   └── ruoyi-job/               # 任务调度
└── ruoyi-extend/             # 扩展模块
    ├── ruoyi-monitor-admin/     # SpringBoot Admin 监控
    └── ruoyi-snailjob-server/   # SnailJob 调度中心
```

### 前端目录结构

```
plus-ui/
├── src/
│   ├── api/                  # API 接口定义
│   │   ├── demo/                # 演示模块
│   │   ├── monitor/             # 监控模块
│   │   ├── system/              # 系统管理
│   │   ├── tool/                # 工具模块
│   │   └── workflow/            # 工作流
│   ├── assets/               # 静态资源
│   ├── components/           # 公共组件
│   ├── directive/            # 自定义指令
│   ├── hooks/                # 组合式函数
│   ├── layout/               # 布局组件
│   ├── lang/                 # 国际化
│   ├── plugins/              # 插件封装
│   ├── router/               # 路由配置
│   ├── store/                # Pinia 状态管理
│   ├── types/                # TypeScript 类型定义
│   ├── utils/                # 工具函数
│   └── views/                # 页面视图
├── vite/                     # Vite 插件配置
└── vite.config.ts            # Vite 配置文件
```

## 核心技术架构

### 后端核心组件

1. **权限认证**: Sa-Token + JWT (非 Spring Security)
   - 支持登录校验、角色校验、权限校验、二级认证等
   - 支持复杂权限表达式 (AND/OR)

2. **ORM 框架**: MyBatis-Plus
   - 雪花ID主键 (ASSIGN_ID)
   - 多租户插件 (默认启用)
   - 数据权限插件
   - 分页插件

3. **缓存方案**: Redisson (非 Lettuce)
   - 支持分布式锁 (Lock4j)
   - 支持 Spring Cache 注解

4. **多数据源**: Dynamic-Datasource
   - 支持异构数据库动态切换

5. **任务调度**: SnailJob (非 Quartz)
   - 分布式任务调度
   - 支持分片、重试、DAG 任务流

6. **工作流引擎**: Warm-Flow
   - 国产工作流引擎
   - 支持复杂审批流程

7. **文件存储**: MinIO / AWS S3
   - 支持七牛、阿里云、腾讯云等

8. **API 文档**: SpringDoc (非 Springfox)
   - 基于 javadoc 注释自动生成
   - 零注解入侵

### 前端核心特性

1. **UI 框架**: Element Plus
2. **状态管理**: Pinia (非 Vuex)
3. **路由**: Vue Router 4
4. **HTTP 客户端**: Axios
5. **表格组件**: vxe-table
6. **接口加密**: RSA + AES 动态加密

## 配置说明

### 后端配置

- **主配置文件**: `ruoyi-admin/src/main/resources/application.yml`
- **环境配置**:
  - `application-dev.yml` (开发)
  - `application-prod.yml` (生产)
  - `application-local.yml` (本地)

- **多环境切换**: 通过 Maven Profile 切换
  ```xml
  <profiles.active>dev|prod|local</profiles.active>
  ```

### 前端配置

- **环境变量**: `.env.development` / `.env.production`
- **代理配置**: `vite.config.ts` 中配置后端代理
  - 默认代理到 `http://localhost:8080`

### 重要配置项

1. **多租户**: `tenant.enable=true` (默认开启)
2. **接口加密**: `api-decrypt.enabled=true`
3. **数据加密**: `mybatis-encryptor.enable=false` (默认关闭)
4. **WebSocket**: 默认关闭,推荐使用 SSE
5. **验证码**: `captcha.enable=true`

## 数据库说明

- **主键策略**: 雪花ID (ASSIGN_ID),不使用数据库自增
- **逻辑删除**: 默认启用 (`mybatis-plus.enableLogicDelete=true`)
- **多租户表**: 自动添加 `tenant_id` 字段 (排除表在配置中指定)

## 代码生成器

位于系统管理 -> 代码生成模块:
- 支持多数据源代码生成
- 自动生成 Controller、Service、Mapper、Vue 页面
- 符合项目规范的代码风格

## 监控与运维

1. **应用监控**: Spring Boot Admin
   - 访问地址: `http://localhost:9090/admin`
   - 用户名/密码: 配置文件中设置

2. **任务调度中心**: SnailJob
   - 访问地址: `http://localhost:8800/snail-job`

3. **API 文档**: SpringDoc
   - 开发环境访问: `http://localhost:8080/doc.html`

4. **日志**: Logback
   - 日志路径: `./logs/sys-console.log`

## 测试

- **单元测试**: 使用 JUnit 5 + Spring Boot Test
- **运行测试**: `mvn test`
- **测试分组**: 通过 `@Tag` 注解标记,根据环境执行

## 注意事项

1. 项目采用插件化架构,各 `ruoyi-common-*` 模块相互独立,易于扩展
2. 严格遵守 Alibaba Java 编码规范
3. 使用 Lombok 简化代码,需要IDE安装 Lombok 插件
4. 使用 MapStruct-Plus 进行对象转换
5. 前端使用 TypeScript,需要注意类型定义
6. 接口加密功能前后端需同时开启/关闭
7. 数据库连接池使用 HikariCP (非 Druid)
8. Web 容器使用 Undertow (非 Tomcat)

## 部署端口

- 后端应用: 8080
- 前端应用: 80
- SnailJob 客户端: 28080
- Spring Boot Admin: 9090
- SnailJob Server: 8800