# YaoAI Video 开发与 AI 协作规范

本文档给项目同事和 AI 编程工具使用。目标是让参与者先理解仓库结构、运行方式和修改边界，再开始写代码。

## 1. 仓库结构约定

```text
.
|-- doc/html                 # 客户端页面，PC 创作工作台，React + Vite
|-- doc/miniapp              # 微信小程序 / H5，uni-app
|-- doc/h5                   # 旧 H5 / Vue 页面
|-- yaoai-admin-web          # 管理后台，Vue + Element Plus
|-- yaoai-comic-studio       # 后端服务，Spring Boot 多模块
|-- docker-compose.yml       # 根目录本地发布态 / 部署编排
|-- start-dev.ps1            # 开发态依赖服务启动说明脚本
|-- start-prod-local.ps1     # 本地发布态完整服务启动脚本
`-- docs                    # 项目文档、设计规格、AI 协作规范
```

常用定位：

- 客户端页面修改：优先看 `doc/html/src/app/pages`、`doc/html/src/hooks`、`doc/html/src/lib/api`
- 后端接口修改：优先看 `yaoai-comic-studio/yaoai-api`
- 核心业务编排：优先看 `yaoai-comic-studio/yaoai-pipeline`
- 数据实体 / Mapper：优先看 `yaoai-comic-studio/yaoai-domain`
- 数据库迁移：放在 `yaoai-comic-studio/yaoai-bootstrap/src/main/resources/db/migration`
- 管理后台：看 `yaoai-admin-web/src`
- 小程序：看 `doc/miniapp/src`

## 2. AI 工具执行原则

AI 工具接手任务时，必须先做这些事：

1. 明确目标目录。比如“客户端页面”默认是 `doc/html`，不要误改 `doc/h5` 或 `doc/miniapp`。
2. 先搜索再修改。优先用 `rg` 查找页面、接口、hook、实体、迁移脚本。
3. 遵循现有模式。前端优先复用已有 hook/API/client；后端优先复用已有 Controller/Service/Mapper 结构。
4. 不要回滚用户已有修改。看到无关 dirty files 时忽略，不要 `git reset --hard`。
5. 有数据库字段变更时，必须同步：
   - Entity
   - DTO
   - API request/response
   - Flyway migration
   - 前端 TypeScript interface
6. 前后端联动功能必须验证：
   - `doc/html` 跑 `npm run build`
   - 后端相关模块跑 Maven compile/package
7. UI 功能完成后，说明页面入口、接口路径、验证命令和剩余注意事项。

## 3. 本地开发启动

### 3.1 开发态依赖服务

开发态依赖服务使用 `yaoai-comic-studio/docker-compose.yml`，主要启动 MySQL、Redis、RabbitMQ、Prometheus、Grafana。

```powershell
docker compose -f .\yaoai-comic-studio\docker-compose.yml up -d
```

默认端口：

```text
MySQL      localhost:13306
Redis      localhost:16379
RabbitMQ   localhost:15672
Prometheus localhost:19090
Grafana    localhost:13000
```

不要随便执行：

```powershell
docker compose down -v
```

这会删除数据卷。

### 3.2 后端编译打包

在 `yaoai-comic-studio` 目录执行：

```powershell
mvn package -pl yaoai-bootstrap -am -DskipTests
```

说明：

- `-pl yaoai-bootstrap`：只打包启动模块
- `-am`：自动编译它依赖的模块，例如 common、domain、api、pipeline
- `-DskipTests`：跳过单元测试

### 3.3 后端启动

在 `yaoai-comic-studio` 目录执行：

```powershell
java -jar .\yaoai-bootstrap\target\yaoai-bootstrap-0.1.0-SNAPSHOT.jar
```

启动前确保 MySQL 已运行。Flyway 会自动执行 `db/migration` 下未执行过的迁移脚本，例如 `V1__init.sql`、后续 `Vxx__*.sql`。

常用地址：

```text
后端     http://localhost:8081
Swagger  http://localhost:8081/swagger-ui/index.html
```

### 3.4 客户端 doc/html 启动

```powershell
cd .\doc\html
npm install
npm run dev
```

默认地址：

```text
http://localhost:5173
```

构建验证：

```powershell
cd .\doc\html
npm run build
```

### 3.5 管理后台启动

```powershell
cd .\yaoai-admin-web
npm install
npm run dev
```

默认地址：

```text
http://localhost:5174
```

构建验证：

```powershell
cd .\yaoai-admin-web
npm run build
```

### 3.6 小程序 / H5 启动

```powershell
cd .\doc\miniapp
npm install
npm run dev:h5
```

微信小程序构建：

```powershell
npm run dev:mp-weixin
```

然后用微信开发者工具打开：

```text
doc/miniapp/dist/dev/mp-weixin
```

类型检查：

```powershell
npm run typecheck
```

## 4. 本地发布态 / Docker 完整部署

根目录 `docker-compose.yml` 是本地发布态或部署编排，会构建前端、管理端、后端，并启动 MySQL、Redis。

首次启动前：

```powershell
Copy-Item .\.env.example .\.env
```

然后检查 `.env`，尤其是：

```text
MYSQL_ROOT_PASSWORD
MYSQL_PASSWORD
VOLCENGINE_ARK_API_KEY
VOLCENGINE_TOS_ACCESS_KEY
VOLCENGINE_TOS_SECRET_KEY
VOLCENGINE_TOS_BUCKET
```

启动：

```powershell
docker compose up -d --build
```

默认端口按 `.env` 或 compose fallback 生效：

```text
客户端     http://localhost:3000
管理后台   http://localhost:3001
后端       http://localhost:8080
MySQL      localhost:13306
Redis      localhost:16379
```

注意：如果服务器 `.env` 里已经配置过端口映射，部署时以服务器 `.env` 为准。前端和管理端容器内部都是 Nginx 监听 `80`，宿主机端口应映射到容器 `80`。

## 5. 常用验证命令

只改 `doc/html`：

```powershell
cd .\doc\html
npm run build
```

只改管理后台：

```powershell
cd .\yaoai-admin-web
npm run build
```

只改小程序：

```powershell
cd .\doc\miniapp
npm run typecheck
npm run build:h5
```

只改后端 API / domain / pipeline：

```powershell
cd .\yaoai-comic-studio
mvn -pl yaoai-api,yaoai-domain,yaoai-storage,yaoai-pipeline -am -DskipTests compile
```

改了 `yaoai-ai-providers`、`yaoai-bootstrap` 或数据库迁移：

```powershell
cd .\yaoai-comic-studio
mvn -pl yaoai-api,yaoai-domain,yaoai-storage,yaoai-pipeline,yaoai-ai-providers,yaoai-bootstrap -am -DskipTests compile
```

最终完整打包：

```powershell
cd .\yaoai-comic-studio
mvn package -pl yaoai-bootstrap -am -DskipTests
```

## 6. 前端开发规范

### 6.1 doc/html 客户端

`doc/html` 是当前主要客户端页面，技术栈是 React、Vite、TypeScript、TanStack Query、Zustand。

修改规则：

- 页面组件优先放在 `doc/html/src/app/pages`
- API 封装放在 `doc/html/src/lib/api`
- React Query hook 放在 `doc/html/src/hooks`
- 路由看 `doc/html/src/app/routes.tsx`
- 登录状态看 `doc/html/src/stores/authStore.ts`
- 页面风格尽量沿用现有类名和组件结构
- 不要把客户端改动误放进 `doc/h5`

常见功能链路：

```text
页面组件 -> hook -> lib/api -> 后端 Controller -> Service/Pipeline -> Mapper/Entity
```

如果新增接口，通常要同步：

```text
doc/html/src/lib/api/*.ts
doc/html/src/hooks/*.ts
doc/html/src/app/pages/*.tsx
```

### 6.2 doc/miniapp 小程序

`doc/miniapp` 是 uni-app 项目，可构建 H5 和微信小程序。

修改规则：

- 页面在 `doc/miniapp/src/pages`
- 接口在 `doc/miniapp/src/api`
- 公共组件在 `doc/miniapp/src/components`
- 状态在 `doc/miniapp/src/stores`
- 微信小程序端不要使用浏览器专属 API

### 6.3 yaoai-admin-web 管理端

管理端是 Vue + Element Plus。

修改规则：

- 页面在 `yaoai-admin-web/src/views`
- 路由在 `yaoai-admin-web/src/router`
- API/client 以现有封装为准
- 构建前跑 `npm run build`

## 7. 后端开发规范

后端是 Maven 多模块项目，核心目录是 `yaoai-comic-studio`。

模块职责：

```text
yaoai-bootstrap      # Spring Boot 启动入口、配置、Flyway migrations
yaoai-api            # Controller、API DTO、请求入口
yaoai-domain         # Entity、Mapper、数据库模型
yaoai-pipeline       # 业务编排、AI 生成流程、视频任务流程
yaoai-ai-providers   # 火山 Ark/Seedream/Seedance 等 provider 封装
yaoai-storage        # TOS / 本地存储抽象
yaoai-billing        # 计费/额度
yaoai-admin          # 管理端后端接口
```

新增业务字段时，通常要改：

```text
yaoai-domain/src/main/java/.../entity
yaoai-api/src/main/java/.../dto
yaoai-api/src/main/java/.../controller
yaoai-pipeline/src/main/java/.../service
yaoai-bootstrap/src/main/resources/db/migration/Vxx__*.sql
doc/html/src/lib/api/*.ts
```

接口返回给前端时，优先使用 DTO，不要直接暴露不需要的 Entity 字段。

文件上传规则：

- 前端使用 `FormData`
- 后端 Controller 使用 `@RequestPart("file") MultipartFile file`
- 上传接口加 `consumes = MediaType.MULTIPART_FORM_DATA_VALUE`
- 后端校验 `file.isEmpty()` 和 `contentType.startsWith("image/")`
- TOS key 用 `TosService.buildKey(...)`
- 返回前端时同时给 key 和可预览 URL

## 8. 数据库迁移规范

项目使用 Flyway。所有结构变更必须新增迁移脚本，不要直接改历史 SQL。

命名：

```text
V{next_number}__short_description.sql
```

示例：

```text
V21__storyboard_frame_reference_images.sql
```

迁移脚本位置：

```text
yaoai-comic-studio/yaoai-bootstrap/src/main/resources/db/migration
```

注意：

- 新增字段要考虑已有数据，尽量 `DEFAULT NULL`
- 线上部署前确认迁移脚本已随 bootstrap 打包
- 如果本地库已经启动过，Flyway 只会执行未执行过的新版本

## 9. Git 与协作规则

AI 工具或同事修改代码时：

- 不要提交无关文件
- 不要清理别人未提交的改动
- 变更前后用 `git status --short` 看范围
- 完成后用 `git diff --stat` 汇总影响范围
- 只在用户明确要求时 commit / push
- 推 GitHub 常用命令：

```powershell
git push github HEAD
```

如果远程名不是 `github`，先看：

```powershell
git remote -v
```

## 10. AI 任务完成后的标准回复

交付时建议说明：

```text
完成了什么
改了哪些关键文件
如何验证
是否有数据库迁移 / 部署注意事项
是否有未处理的风险
```

示例：

```text
已完成 doc/html 分镜页首尾帧参考图功能。
验证：npm run build；mvn ... compile。
注意：部署时需要执行 V21 Flyway 迁移。
```

