sionrui/CLAUDE.md

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）

构建和运行：

# 构建项目
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）

开发：

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：

# 启动所有服务（MySQL、Redis、Server、Admin）
cd script/docker
docker-compose up -d

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

手动 Docker 构建：

# 后端
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

部署

生产部署：

# 使用部署脚本
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 覆盖

配置：

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