sionrui/CLAUDE.md

<!-- OPENSPEC:START -->
# OpenSpec 指令

本指令适用于参与此项目的 AI 助手。

当请求出现以下情况时，请务必查阅 `@/openspec/AGENTS.md`：
*   提及规划或提案（如提案、规范、变更、计划等词）
*   引入新功能、破坏性变更、架构调整或重大的性能/安全相关工作
*   表述含糊，需要在编码前查阅权威规范

通过 `@/openspec/AGENTS.md` 可了解：
*   如何创建和应用变更提案
*   规范格式与约定
*   项目结构与指导方针

请保留此受管理的代码块，以便 `openspec update` 可以更新指令。

<!-- OPENSPEC:END -->

## 使用中文与用户沟通

## 项目简介
**Yudao（芋道）** - Spring Boot快速开发平台，AI/媒体功能增强版

### 核心技术栈
- **后端**: Java 17 + Spring Boot 3.5.5 + MyBatis Plus + Redis
- **前端**: Vue.js 3 + TypeScript + Ant Design Vue + TailwindCSS
- **数据库**: MySQL 8.0+，支持多种数据库
- **AI服务**: 语音克隆、图像生成、音乐生成、向量搜索

## 代码规范要点

### Vue.js 最佳实践
- 优先使用组合式API：`<script setup>`
- 状态管理使用Pinia，保持仓库模块化
- TypeScript类型定义规范
- 组件保持小巧专注，逻辑清晰
- 样式优先使用less 示例:`<style scoped lang="less"><style>`
- 代码简洁，只包含核心的功能

### Java开发规范
- 分层架构：Controller → Service → Mapper → VO/DO
- Mapper继承 `BaseMapperX<T>`
- DO继承 `BaseDO` 或 `TenantBaseDO`
- API响应统一使用 `CommonResult<T>`
- 权限注解：`@PreAuthorize("hasPermission(...)")`
- 代码简洁，只包含核心的功能

## 项目结构
```
/d/projects/sionrui/
├── yudao-server/           # 主应用（端口9900）
├── yudao-module-tik/       # 媒体模块（语音克隆、视频）
├── yudao-module-ai/        # AI模块（聊天、知识库）
├── yudao-module-system/    # 系统管理
└── frontend/app/web-gold/  # Vue前端
```

## 模块标准结构
```
module/
├── controller/      # REST控制器
├── service/         # 业务逻辑（接口+实现）
├── mapper/          # 数据访问层
└── vo/              # 值对象（SaveReq/PageReq/Resp）
```

## 关键配置
- **后端配置**: `yudao-server/src/main/resources/application-local.yaml`
- **数据库**: `jdbc:mysql://8.155.172.147:3306/sion_rui_dev`
- **Redis**: `8.155.172.147:6379`
- **前端代理**: `/admin-api` 和 `/api` 代理到 `http://localhost:9900`

## API约定
- 管理API: `/admin-api/{module}/{resource}`
- 应用API: `/api/{module}/{resource}`
- CRUD端点: create/update/delete/get/page

## 常见易错点

### 1. 权限控制
❌ `Long userId = 1L`
✅ `SecurityFrameworkUtils.getLoginUserId()`

### 2. 分页查询
❌ 自定义pageNo/pageSize
✅ VO继承 `SortablePageParam` + `selectPage(reqVO, wrapper)`

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

### 4. JSON字段处理
❌ `private List<String> urls`
✅ `private String urls` + `getUrlList()/setUrlList()` 转换方法

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

### 6. 多租户
- DO类必须继承 `TenantBaseDO`
- 框架自动注入 `tenantId`

## 开发命令
```bash
# 前端开发（绝对路径）
cd /d/projects/sionrui/frontend/app/web-gold
pnpm install
pnpm run dev  # 启动开发服务器

# 后端开发
mvn clean install
mvn spring-boot:run
```

## 路径别名说明
- `@gold` - 前端项目根目录的别名，指向 `frontend/app/web-gold/src`
- 例如：`import tokenManager from '@gold/utils/token-manager'` 等价于 `import tokenManager from 'frontend/app/web-gold/src/utils/token-manager'`

## 重要提醒
1. **OSS配额检查**: 文件上传前必须检查用户/系统配额
2. **多租户**: 默认启用，DO类需继承 `TenantBaseDO`
3. **异常处理**: 使用 `ErrorCodeConstants` 中的错误码
4. **事务管理**: Service写操作使用 `@Transactional`