开发规范流程md

docs/ai-development-guide.md

+# 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 迁移。
+```
+