<!-- 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 -->

# 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 样式

### 代码规范

#### Vue.js 最佳实践

##### 代码规划
- 代码简洁易于人类阅读

##### 组件结构
- 优先使用组合式 API 而非选项式 API
- 保持组件小巧且功能专注
- 采用恰当的 TypeScript 集成方案
- 实现规范的 props 验证
- 使用标准的 emit 声明
- 保持模板逻辑简洁
- 优先使用template 语法，而不是函数组件
- 优先使用函数或者hook，而不是类

##### 组合式 API
- 正确使用 ref 与 reactive
- state模块化 

```js
const uiState = ref({ dialogVisible:false, tableLoading:false})
const open = ()=>{
   uiState.value.dialogVisible = true
}
```

- 合理实现生命周期钩子
- 通过组合式函数封装可复用逻辑
- 保持 setup 函数整洁
- 规范使用计算属性
- 合理实现侦听器

##### 状态管理
- 使用 Pinia 进行状态管理
- 保持仓库模块化
- 采用合理的状态组织方式
- 规范实现操作逻辑
- 正确使用获取器
- 妥善处理异步状态

##### 性能优化
- 实现组件懒加载
- 配置恰当的缓存策略
- 高效使用计算属性
- 避免不必要的侦听器
- 区分使用 v-show 与 v-if
- 实现科学的 key 管理

##### 路由管理
- 规范使用 Vue Router
- 实现完整的导航守卫
- 合理配置路由元字段
- 正确处理路由参数
- 实现路由懒加载
- 使用标准的导航方法

##### 表单处理
- 正确使用 v-model
- 实现完善的验证机制
- 规范处理表单提交
- 展示合理的加载状态
- 配置完整的错误处理
- 实现表单重置功能

##### TypeScript 集成
- 使用规范的组件类型定义
- 实现完整的 props 类型声明
- 规范 emit 类型声明
- 处理类型推断
- 使用标准的组合函数类型
- 实现完整的仓库类型定义


## 代码简化
- 只保留核心分支，移除重复校验 / 冗余注释”，例：“生成 Java 订单支付接口逻辑，仅包含参数非空校验、支付状态判断 2 个核心分支，无需异常场景的冗余兜底代码
- 用三目运算符简化 if-else 冗余，避免单分支重复判断；变量仅定义必要的，移除未被调用的临时变量

**数据库与基础设施：**
- 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/                        # 文档
```


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

### 前端（Vue.js）

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

# 安装依赖
pnpm install

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

# 生产构建
pnpm run build

# 代码检查
pnpm run lint

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

## 模块架构

### 后端模块结构模式

每个模块都遵循一致的分层架构：
```
module/
├── controller/      # REST 控制器（admin-api/、api/）
├── service/         # 业务逻辑 + 接口
│   ├── {Xxx}Service.java           # 接口
│   └── {Xxx}ServiceImpl.java       # 实现
├── mapper/             # 数据访问层
├── 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`


**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` 测试

## 常见易错点与正确用法

### 1. CommonResult 错误处理
❌ `CommonResult.error("msg")`
✅ `CommonResult.error(GlobalErrorCodeConstants.UNAUTHORIZED)`

### 2. JSON 序列化
❌ `parseJson()`, `toJson()`
✅ `JsonUtils.parseObject(text, new TypeReference<List<T>>() {})` / `JsonUtils.toJsonString(obj)`

### 3. DO基类
❌ `common.pojo.TenantBaseDO`
✅ `tenant.core.db.TenantBaseDO`

### 4. 分页参数
❌ 自定义pageNo/pageSize
✅ `VO extends SortablePageParam` + `selectPage(reqVO, wrapper)`

### 5. 用户认证
❌ `Long userId = 1L`
✅ `SecurityFrameworkUtils.getLoginUserId()`

### 6. Mapper查询
❌ `QueryWrapper` + 字符串字段
✅ `LambdaQueryWrapperX` + 方法引用

### 7. JSON字段
❌ `private List<String> urls`
✅ `private String urls` + `getUrlList()/setUrlList()` 转换

### 8. Bean转换
❌ `org.springframework.beans.BeanUtils`
✅ `framework.common.util.object.BeanUtils`

### 9. 异步处理
❌ 同步调用ICE API
✅ `CompletableFuture.runAsync(() -> {...})`

### 10. Logger使用
❌ `log.info("msg")` 无定义Logger
✅ `@Slf4j` 注解类 或 `private static final Logger log = LoggerFactory.getLogger(...)`

### 11. Cron配置
❌ `@Scheduled(cron = "*/30 * * * * ?")`
✅ `@Scheduled(cron = Constants.CRON_CHECK_STATUS)`

### 12. OSS配额检查
❌ 直接上传文件到OSS而不检查配额
✅ 上传前检查用户/系统配额，限制文件大小和数量，记录使用量

## 多租户

- 配置中默认启用
- 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`
8. **OSS 配额：** 使用阿里云 OSS、文件上传、混剪视频存储等功能时**必须**检查和限制配额，防止超出存储/流量限制

## 故障排除

**常见问题：**

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