# CLAUDE.md

本文档为 Claude Code (claude.ai/code) 在此仓库中处理代码提供指导。

## 项目概览

**Yudao（芋道）** - 基于 Spring Boot 的快速开发平台，采用多模块架构。这是 Yudao 平台的 AI/媒体重点部署版本，具备数字人生成、语音克隆、视频混剪和内容分析能力。

### 核心技术栈

**后端：**
- Java 17 + Spring Boot 3.5.5
- Maven 构建管理
- MyBatis Plus 3.5.14 + Dynamic Datasource ORM
- Redis + Redisson 缓存
- Spring Security 6.5.2 认证
- Flowable 7.0.1 工作流
- Springdoc/OpenAPI 文档

**前端：**
- Vue.js 3.5.22 + Composition API
- Vite 7.1.7 构建工具
- Ant Design Vue 4.2.6 UI组件
- TypeScript 类型安全
- Pinia 3.0.3 状态管理
- TailwindCSS 4.1.14 样式

**数据库与基础设施：**
- MySQL 8.0+（主要）
- 支持 PostgreSQL、Oracle、SQL Server、DM、KingbaseES、OpenGauss、TiDB
- Redis 缓存
- Docker 容器化

## 项目结构

```
/d/projects/sionrui/
├── yudao-dependencies/          # Maven 依赖版本管理
├── yudao-framework/             # 框架组件和 Spring Boot 启动器
├── yudao-server/                # 主应用服务器（端口 9900）
├── yudao-module-system/         # 系统管理（用户、角色、权限）
├── yudao-module-infra/          # 基础设施（文件、配置、任务）
├── yudao-module-member/         # 会员中心
├── yudao-module-pay/            # 支付系统
├── yudao-module-ai/             # AI/ML 功能（聊天、图像、知识、音乐）
├── yudao-module-tik/            # Tik/媒体模块（语音克隆、头像、视频）
├── frontend/app/web-gold/       # Vue.js 前端
├── sql/                         # 数据库模式
├── script/                      # 构建和部署脚本
└── docs/                        # 文档
```

## 常用开发命令

### 后端（Maven）

**构建和运行：**
```bash
# 构建项目
mvn clean package -DskipTests

# 运行特定模块的测试
mvn test -pl yudao-module-tik

# 启动服务器
cd yudao-server && mvn spring-boot:run -Dspring-boot.run.profiles=local

# 使用特定配置构建
mvn clean package -Pdev -DskipTests
```

**代码生成：**
- 内置 CRUD 操作代码生成器
- 生成 Java、Vue、SQL 脚本和 API 文档
- 支持单表、树表、主子表模式

### 前端（Vue.js）

**开发：**
```bash
cd frontend/app/web-gold

# 安装依赖
npm install

# 启动开发服务器（代理到后端 9900 端口）
npm run dev

# 生产构建
npm run build

# 代码检查
npm run lint

# 代码格式化
npm run format
```

**可用脚本：**
- `dev` - 带热重载的开发服务器
- `build` - 生产构建
- `preview` - 预览生产构建
- `lint:oxlint` - 运行 OxLint 并自动修复
- `lint:eslint` - 运行 ESLint 并自动修复
- `lint` - 运行所有检查器
- `format` - 使用 Prettier 格式化代码

### Docker

**使用 Docker Compose：**
```bash
# 启动所有服务（MySQL、Redis、Server、Admin）
cd script/docker
docker-compose up -d

# 启动特定服务
docker-compose up -d mysql redis
```

**手动 Docker 构建：**
```bash
# 后端
cd yudao-server
docker build -t yudao-server .

# 前端
cd frontend/app/web-gold
docker build -t web-gold .
```

## 模块架构

### 后端模块结构模式

每个模块都遵循一致的分层架构：
```
module/
├── controller/      # REST 控制器（admin-api/、app/）
├── service/         # 业务逻辑 + 接口
│   ├── {Xxx}Service.java           # 接口
│   └── {Xxx}ServiceImpl.java       # 实现
├── dal/             # 数据访问层
│   ├── mysql/       # MyBatis Mappers 和 DO 类
│   └── redis/       # Redis 操作
├── client/          # 外部 API 客户端
├── config/          # 配置类
├── util/            # 工具类
└── vo/              # 值对象
    ├── {Xxx}SaveReqVO.java         # 创建请求
    ├── {Xxx}PageReqVO.java         # 分页请求
    ├── {Xxx}UpdateReqVO.java       # 更新请求
    └── {Xxx}RespVO.java            # 响应
```

**核心模块：**

1. **yudao-module-tik** - 媒体/AI 功能
   - `voice/` - 语音克隆（CosyVoice、Latentsync）
   - `file/` - 带 OSS 集成的文件管理
   - `chat/` - 对话管理
   - `media/` - 媒体处理
   - `quota/` - 配额管理

2. **yudao-module-ai** - AI/ML 能力
   - 聊天补全 API
   - 图像生成（Midjourney）
   - 音乐生成（Suno）
   - 带向量搜索的知识库

3. **yudao-module-system** - 核心系统功能
   - 用户/角色/权限管理
   - 多租户支持
   - 审计日志

### 前端结构

```
frontend/app/web-gold/src/
├── api/              # API 服务层
│   ├── axios/        # Axios 拦截器
│   ├── voice.js      # 语音相关 API
│   └── mix.js        # 视频混剪 API
├── components/       # 可复用 Vue 组件
├── router/
│   └── index.js      # Vue Router 配置
├── stores/
│   └── voiceCopy.js  # Pinia 状态管理
├── views/
│   ├── dh/           # 数字人功能
│   │   ├── Avatar.vue
│   │   ├── Video.vue
│   │   └── VoiceCopy.vue
│   ├── material/     # 素材库
│   └── content-style/# 内容分析
└── utils/
    └── video-cover.ts # 工具函数
```

**核心路由：**
- `/digital-human/*` - 语音克隆、头像、视频生成
- `/content-style/*` - 内容分析和基准测试
- `/trends/*` - 趋势分析
- `/material/*` - 素材库管理

## 配置

### 后端配置文件

**主配置：** `yudao-server/src/main/resources/application.yaml`
- Spring Boot 配置
- 数据库连接
- Redis 设置
- 安全设置
- 多租户配置
- AI 服务 API 密钥

**本地开发：** `yudao-server/src/main/resources/application-local.yaml`
- 本地开发覆盖
- 数据库：`jdbc:mysql://8.155.172.147:3306/sion_rui_dev`
- Redis：`8.155.172.147:6379`
- 端口：9900

**配置环境：**
- `local` - 开发（端口 9900）
- `dev` - 开发服务器
- `prod` - 生产

### 前端配置

**Vite 配置：** `frontend/app/web-gold/vite.config.js`
- 开发服务器代理到后端
- 构建配置
- 插件设置

**API 代理：**
- 开发服务器将 `/admin-api` 和 `/api` 代理到 `http://localhost:9900`

## 数据库模式

**位置：** `sql/mysql/`
- 主模式：`ruoyi-vue-pro.sql` (949KB)
- Quartz：`quartz.sql` 用于定时任务
- 模块特定迁移在各模块文件夹中

**模式更新：**
- 将 SQL 迁移添加到 `sql/mysql/`
- 遵循命名约定：`V{version}__{description}.sql`

## API 文档

- **Swagger UI：** `http://localhost:9900/swagger-ui.html`
- **API 文档：** `http://localhost:9900/v3/api-docs`

**API 路径约定：**
- 管理 API：`/admin-api/{module}/{resource}`
- 应用 API：`/api/{module}/{resource}`
- CRUD 端点：
  - 创建：`POST /module/resource/create`
  - 更新：`PUT /module/resource/update`
  - 删除：`DELETE /module/resource/delete`
  - 查询：`GET /module/resource/get?id=xxx`
  - 分页：`GET /module/resource/page`

## 代码风格与规范

### 后端（Java）

**架构层：**
1. **Controller** - 请求处理、验证、调用 Service
2. **Service** - 业务逻辑、事务管理
3. **Mapper** - 使用 MyBatis Plus 进行数据访问
4. **VO** - API 请求/响应对象
5. **DO** - 映射到数据库表的数据对象

**关键规范：**
- Mapper 接口继承 `BaseMapperX<T>`
- DO 类继承 `BaseDO` 或 `TenantBaseDO` 以支持多租户
- 使用 `@PreAuthorize` 进行权限控制
- 统一使用 `CommonResult<T>` 作为 API 响应
- Service 方法使用 `@Transactional` 进行写操作
- 异常代码在 `ErrorCodeConstants` 中，格式为：`MODULE_RESOURCE_ACTION_ERROR`

**命名规范：**
- Controller：`{Xxx}Controller` 或 `App{Xxx}Controller`
- Service：`{Xxx}Service` 和 `{Xxx}ServiceImpl`
- Mapper：`{Xxx}Mapper`
- VO：`{Xxx}SaveReqVO`、`{Xxx}PageReqVO`、`{Xxx}RespVO`
- DO：`{Xxx}DO`

### 前端（Vue.js）

**关键模式：**
- Composition API + `<script setup>`
- Pinia 进行状态管理和持久化
- Axios 拦截器处理认证和租户
- TypeScript 提供类型安全

**代码检查：**
- ESLint + OxLint 保证代码质量
- Prettier 进行代码格式化
- 提交前运行 `npm run lint`

## 测试

**后端：**
- JUnit 5 + Mockito 进行单元测试
- Spring Boot Test 进行集成测试
- 测试位置：`src/test/java`
- 运行测试：`mvn test`

**前端：**
- Vitest 进行单元测试
- Cypress 进行端到端测试
- 运行测试：`npm run test`

## 部署

**生产部署：**
```bash
# 使用部署脚本
cd script/shell
./deploy.sh

# 手动部署
# 1. 构建 JAR
mvn clean package -DskipTests -Pprod

# 2. 部署到服务器
# deploy.sh 脚本处理：
# - 备份前一版本
# - 停止当前服务
# - 传输新 JAR
# - 启动服务
# - 健康检查
```

**JVM 选项：**
- 默认：`-Xms512m -Xmx512m -XX:+HeapDumpOnOutOfMemoryError`
- 可在 `deploy.sh` 中配置

**健康检查：**
- 端点：`/actuator/health`
- 端口：48080（生产）或 9900（本地）

## 开发工作流

### 创建新模块

1. 按照标准目录结构创建模块
2. 将 SQL 迁移添加到 `sql/mysql/`
3. 运行代码生成器进行 CRUD 操作
4. 实现 Controller、Service、Mapper 层
5. 编写单元测试
6. 更新 API 文档

### 添加新 API 端点

1. 在模块的 `vo/` 包中创建 VO 类
2. 使用适当注解实现 Controller：
   - `@Tag`、`@Operation` 用于 Swagger 文档
   - `@PreAuthorize` 用于权限
   - `@Valid` 用于验证
3. 实现包含业务逻辑的 Service 层
4. 如需要，创建/更新 Mapper
5. 通过 Swagger UI 测试端点

### 前端开发

1. 在 `src/api/` 中创建/更新 API 服务
2. 在 `src/stores/` 中添加 Pinia 存储（如需要）
3. 在 `src/views/` 中创建 Vue 组件
4. 更新 `src/router/index.js` 中的路由
5. 使用 `npm run dev` 测试

## 多租户

- 配置中默认启用
- DO 类继承 `TenantBaseDO` 实现租户隔离
- 框架自动注入 `tenantId`
- 需要时使用 `@TenantIgnore` 覆盖

**配置：**
```yaml
yudao:
  tenant:
    enable: true
    ignore-urls:
      - /jmreport/*
    ignore-tables:
      - table_name
```

## 安全

**认证与授权：**
- Spring Security 认证框架
- 基于令牌的身份认证
- 基于角色的访问控制（RBAC）
- 权限格式：`module:resource:action`

**API 安全：**
- 支持 API 加密（AES/RSA）
- 配置中的请求/响应加密密钥
- 可配置的 XSS 保护

**数据保护：**
- 字段级加密支持
- 通过 MyBatis Plus 防止 SQL 注入
- 使用 `@Valid` 进行参数验证

## 缓存

**Redis 配置：**
- 缓存类型：`REDIS`
- 默认 TTL：1 小时
- 连接：`8.155.172.147:6379`

**缓存模式：**
- 键格式：`模块:资源:id`
- 使用 `@Cacheable`、`@CacheEvict` 管理缓存
- 热数据缓存提升性能

## 集成点

**AI 服务：**
- CosyVoice：语音克隆
- Latentsync：语音合成
- Midjourney：图像生成
- Suno：音乐生成
- 多个 LLM 提供商（OpenAI、Claude、Gemini 等）

**文件存储：**
- S3 兼容（MinIO、AWS S3 等）
- 本地存储
- FTP
- 数据库存储

**消息队列：**
- Redis（Pub/Sub、Stream）
- Kafka
- RabbitMQ
- RocketMQ

## 监控与可观测性

**Actuator 端点：**
- `/actuator/health` - 健康检查
- `/actuator/metrics` - 指标
- `/actuator/env` - 环境属性

**监控工具：**
- Spring Boot Admin 应用程序监控
- SkyWalking 分布式追踪
- Druid SQL 监控

## Cursor 规则集成

此仓库在 `.cursor/rules/backend.mdc` 中配置了 **Cursor 规则** 用于 Spring Boot 开发最佳实践。主要规则包括：

- 分层架构强制执行（Controller → Service → Mapper）
- 模块结构约定
- VO/DO 命名标准
- 事务管理模式
- 多租户支持
- API 路径约定
- 安全和权限模式

## 重要注意事项

1. **数据库：** 需要 MySQL 8.0+，外部连接配置在 `application-local.yaml`
2. **Redis：** 缓存和会话管理所需
3. **Java 版本：** 需要 JDK 17+
4. **Node 版本：** 前端需要 Node.js 20.19.0+ 或 22.12.0+
5. **端口：** 后端默认 9900，前端默认 5173
6. **API 密钥：** `application.yaml` 中配置了多个 AI 服务 API 密钥 - 不要提交到公共仓库
7. **多租户：** 默认启用 - 所有 DO 类应继承 `TenantBaseDO`

## 故障排除

**常见问题：**

1. **端口已被占用：**
   - 在 `application-local.yaml` 中更改端口：`server.port=9999`
   - 或终止进程：`lsof -ti:9900 | xargs kill -9`

2. **数据库连接失败：**
   - 验证 MySQL 运行：`mysql -h 8.155.172.147 -u root -p`
   - 检查 `application-local.yaml` 中的连接设置

3. **Redis 连接失败：**
   - 验证 Redis：`redis-cli -h 8.155.172.147 -p 6379`
   - 检查密码/认证设置

4. **前端构建错误：**
   - 清理 node_modules：`rm -rf node_modules package-lock.json`
   - 重新安装：`npm install`
   - 检查 Node 版本：`node --version`

5. **Maven 构建错误：**
   - 清理构建：`mvn clean install`
   - 跳过测试：`mvn clean package -DskipTests`

## 资源

- **官方文档：** https://doc.iocoder.cn/
- **快速开始：** https://doc.iocoder.cn/quick-start/
- **视频教程：** https://doc.iocoder.cn/video/
- **API 文档：** http://localhost:9900/swagger-ui.html（运行时）
- **Spring Boot 参考：** https://docs.spring.io/spring-boot/docs/current/reference/html/
- **Vue.js 指南：** https://vuejs.org/guide/
- **Yudao GitHub：** https://github.com/YunaiV/ruoyi-vue-pro