491 lines
14 KiB
Markdown
491 lines
14 KiB
Markdown
# 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/ # 文档
|
||
```
|
||
|
||
|
||
**代码生成：**
|
||
- 内置 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
|