sion/sionrui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 优化

Browse Source
This commit is contained in:
sion123
2025-12-27 18:17:10 +08:00
parent ad36382f60
commit effbbc694c
282 changed files with 66909 additions and 1131 deletions
Download Patch File Download Diff File Expand all files Collapse all files

599
CLAUDE.md
View File

@@ -16,573 +16,102 @@ Use `@/openspec/AGENTS.md` to learn:
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/媒体重点部署版本，具备数字人生成、语音克隆、视频混剪和内容分析能力。
## 项目简介
**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服务**: 语音克隆、图像生成、音乐生成、向量搜索
**后端：**
- 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：`<script setup>`
- 状态管理使用Pinia，保持仓库模块化
- TypeScript类型定义规范
- 组件保持小巧专注，逻辑清晰
### 代码规范
#### 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 容器化
### Java开发规范
- 分层架构：Controller → Service → Mapper → VO/DO
- Mapper继承 `BaseMapperX<T>`
- DO继承 `BaseDO` 或 `TenantBaseDO`
- API响应统一使用 `CommonResult<T>`
- 权限注解：`@PreAuthorize("hasPermission(...)")`
## 项目结构
```
/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/ # 文档
├── yudao-server/ # 主应用（端口9900）
├── yudao-module-tik/ # 媒体模块（语音克隆、视频）
├── yudao-module-ai/ # AI模块（聊天、知识库）
├── yudao-module-system/ # 系统管理
└── frontend/app/web-gold/ # Vue前端
```
**代码生成：**
- 内置 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 # 响应
├── 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`
1. **yudao-module-tik** - 媒体/AI 功能
- `voice/` - 语音克隆（CosyVoice、Latentsync）
- `file/` - 带 OSS 集成的文件管理
- `chat/` - 对话管理
- `media/` - 媒体处理
- `quota/` - 配额管理
## API约定
- 管理API: `/admin-api/{module}/{resource}`
- 应用API: `/api/{module}/{resource}`
- CRUD端点: create/update/delete/get/page
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. 用户认证
### 1. 权限控制
❌ `Long userId = 1L`
✅ `SecurityFrameworkUtils.getLoginUserId()`
### 6. Mapper查询
### 2. 分页查询
❌ 自定义pageNo/pageSize
✅ VO继承 `SortablePageParam` + `selectPage(reqVO, wrapper)`
### 3. Mapper查询
❌ `QueryWrapper` + 字符串字段
✅ `LambdaQueryWrapperX` + 方法引用
### 7. JSON字段
### 4. JSON字段处理
❌ `private List<String> urls`
✅ `private String urls` + `getUrlList()/setUrlList()` 转换
✅ `private String urls` + `getUrlList()/setUrlList()` 转换方法
### 8. Bean转换
### 5. 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` 实现租户隔离
### 6. 多租户
- DO类必须继承 `TenantBaseDO`
- 框架自动注入 `tenantId`
- 需要时使用 `@TenantIgnore` 覆盖
**配置：**
```yaml
yudao:
tenant:
enable: true
ignore-urls:
- /jmreport/*
ignore-tables:
- table_name
## 开发命令
```bash
# 前端开发
cd frontend/app/web-gold
pnpm install
pnpm run dev # 启动开发服务器
# 后端开发
mvn clean install
mvn spring-boot:run
```
## 安全
**认证与授权：**
- 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
## 重要提醒
1. **OSS配额检查**: 文件上传前必须检查用户/系统配额
2. **多租户**: 默认启用，DO类需继承 `TenantBaseDO`
3. **异常处理**: 使用 `ErrorCodeConstants` 中的错误码
4. **事务管理**: Service写操作使用 `@Transactional`