142 lines
4.9 KiB
Markdown
142 lines
4.9 KiB
Markdown
<!-- OPENSPEC:START -->
|
||
# OpenSpec 指令
|
||
|
||
本指令适用于参与此项目的 AI 助手。
|
||
|
||
当请求出现以下情况时，请务必查阅 `@/openspec/AGENTS.md`：
|
||
* 提及规划或提案（如提案、规范、变更、计划等词）
|
||
* 引入新功能、破坏性变更、架构调整或重大的性能/安全相关工作
|
||
* 表述含糊，需要在编码前查阅权威规范
|
||
|
||
通过 `@/openspec/AGENTS.md` 可了解：
|
||
* 如何创建和应用变更提案
|
||
* 规范格式与约定
|
||
* 项目结构与指导方针
|
||
|
||
请保留此受管理的代码块，以便 `openspec update` 可以更新指令。
|
||
|
||
<!-- OPENSPEC:END -->
|
||
|
||
## 使用中文与用户沟通
|
||
|
||
## 项目简介
|
||
**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服务**: 语音克隆、图像生成、音乐生成、向量搜索
|
||
|
||
## 代码规范要点
|
||
|
||
### Vue.js 最佳实践
|
||
- 优先使用组合式API：`<script setup>`
|
||
- 状态管理使用Pinia，保持仓库模块化
|
||
- TypeScript类型定义规范
|
||
- 组件保持小巧专注，逻辑清晰
|
||
- 样式优先使用less 示例:`<style scoped lang="less"><style>`
|
||
- 代码简洁，只包含核心的功能
|
||
|
||
### Java开发规范
|
||
- 分层架构：Controller → Service → Mapper → VO/DO
|
||
- Mapper继承 `BaseMapperX<T>`
|
||
- DO继承 `BaseDO` 或 `TenantBaseDO`
|
||
- API响应统一使用 `CommonResult<T>`
|
||
- 权限注解：`@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<T>
|
||
│ └── 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<String> 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` |