# OpenSpec 指令 本指令适用于参与此项目的 AI 助手。 当请求出现以下情况时，请务必查阅 `@/openspec/AGENTS.md`： * 提及规划或提案（如提案、规范、变更、计划等词） * 引入新功能、破坏性变更、架构调整或重大的性能/安全相关工作 * 表述含糊，需要在编码前查阅权威规范 通过 `@/openspec/AGENTS.md` 可了解： * 如何创建和应用变更提案 * 规范格式与约定 * 项目结构与指导方针 请保留此受管理的代码块，以便 `openspec update` 可以更新指令。 ## 使用中文与用户沟通 ## 项目简介 **Yudao（芋道）** - Spring Boot快速开发平台，AI/媒体功能增强版 ### 核心技术栈 - **后端**: Java 17 + Spring Boot 3.5.5 + MyBatis Plus + Redis - **前端**: Vue.js 3 + TypeScript + shadcn-vue + TailwindCSS - **数据库**: MySQL 8.0+，支持多种数据库 - **AI服务**: 语音克隆、图像生成、音乐生成、向量搜索 ## 代码规范要点 ### Vue.js 最佳实践 - 优先使用组合式API：` {{ opt.label }} 全部 ``` - **日期选择**: 使用 `Calendar` 或 `RangeCalendar` 组件，配合 `Popover` 使用 - **表单**: 使用 `Form` 组件进行表单验证和提交 - **弹窗**: 使用 `Dialog` 组件替代原生弹窗 ### Java开发规范 - 分层架构：Controller → Service → Mapper → VO/DO - Mapper继承 `BaseMapperX` - DO继承 `BaseDO` 或 `TenantBaseDO` - API响应统一使用 `CommonResult` - 权限注解：`@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控制器 - 通过URL前缀区分 /admin-api 或 /api ├── service/ # 业务逻辑层 - 核心业务处理 │ ├── XxxService.java # 接口定义 │ └── XxxServiceImpl.java # 实现类（@Service） ├── mapper/ # 数据访问层 - 继承BaseMapperX │ └── XxxMapper.java └── vo/ # 值对象 - 数据传输对象 ├── XxxSaveReqVO.java # 创建/更新请求 ├── XxxPageReqVO.java # 分页查询请求（继承SortablePageParam） └── XxxRespVO.java # 响应对象 ``` ### 层级职责 | 层级 | 职责 | 禁止事项 | |------|------|----------| | Controller | 参数校验、调用Service、返回响应 | 禁止写业务逻辑 | | Service | 业务逻辑处理、事务管理 | 禁止直接操作Mapper（通过Service） | | Mapper | 数据库CRUD操作 | 禁止写业务逻辑 | | VO | 数据传输、格式转换 | 禁止包含业务逻辑 | ## 关键配置 - **后端配置**: `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 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' 指向 frontend/app/web-gold/src/utils/token-manager ## 重要提醒 1. **OSS配额检查**: 文件上传前必须检查用户/系统配额 2. **多租户**: 默认启用，DO类需继承 `TenantBaseDO` 3. **异常处理**: 使用 `ErrorCodeConstants` 中的错误码 4. **事务管理**: Service写操作使用 `@Transactional`