sionrui/CLAUDE.md

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.

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模块化

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）

开发：

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 覆盖

配置：

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