ai/docs/system_b/16_Codex开发任务拆解文档.md

# 16_Codex开发任务拆解文档

## 1. 文档目标

本文档用于把系统 B 拆成适合 Codex 执行的开发任务。每个任务应该尽量独立、可验证、可回滚。

## 2. 开发原则

1. 先跑通主流程，再优化细节。
2. 每个任务必须有验收标准。
3. 不要一次让 Codex 写完整系统。
4. 数据库、接口、页面、任务队列分阶段完成。
5. AI Provider 先做抽象，再接具体模型。

## 3. 阶段 1：项目基础框架

### 任务 01：初始化后端项目

目标：创建 NestJS 后端项目。

要求：

- TypeScript
- 环境变量配置
- 全局异常处理
- 日志基础封装
- Swagger 可选

验收：

- `npm run start` 正常启动。
- `/api/health` 返回 ok。

### 任务 02：配置数据库 ORM

目标：接入 MySQL。

要求：

- TypeORM 或 Prisma 二选一
- 配置迁移
- 创建基础 users/projects 表

验收：

- 可以执行迁移。
- 可以读写测试数据。

### 任务 03：配置 Redis 和 BullMQ

目标：接入 Redis 队列。

要求：

- QueueModule
- 测试队列
- Worker 示例

验收：

- 能创建任务。
- Worker 能消费任务。

### 任务 04：配置 MinIO 文件上传

目标：实现对象存储。

要求：

- 上传文件
- 生成签名 URL
- 删除文件
- 缩略图字段预留

验收：

- 上传图片成功。
- 数据库 asset 记录生成。

## 4. 阶段 2：用户与权限

### 任务 05：实现用户注册登录

要求：

- 手机号验证码模拟版
- JWT 登录
- 获取当前用户

验收：

- 登录成功返回 token。
- 受保护接口能识别用户。

### 任务 06：实现后台管理员登录

要求：

- admin_users
- roles
- 权限中间件

验收：

- 管理员可登录。
- 不同角色权限可区分。

## 5. 阶段 3：模板系统

### 任务 07：实现人生主题 API

接口：

- GET /api/life-themes
- POST /api/admin/life-themes
- PUT /api/admin/life-themes/:id

验收：

- 前台可读取主题。
- 后台可新增编辑。

### 任务 08：实现套餐 API

接口：

- GET /api/packages
- 后台增删改查

验收：

- 套餐限制字段可配置。

### 任务 09：实现风格、世界、场景、镜头模板 API

要求：

- style_templates
- world_templates
- scene_templates
- shot_templates

验收：

- 前台按主题/风格查询世界。
- 后台可维护模板。

## 6. 阶段 4：项目创建流程

### 任务 10：实现项目创建 API

接口：

- POST /api/projects
- GET /api/projects/:id
- GET /api/my/projects

验收：

- 用户可创建项目。
- 只能查看自己的项目。

### 任务 11：实现项目选择流程 API

接口：

- POST /api/projects/:id/package
- POST /api/projects/:id/style
- POST /api/projects/:id/worlds
- POST /api/projects/:id/scenes
- POST /api/projects/:id/custom-info

验收：

- 项目选择数据可保存。
- 套餐限制生效。

### 任务 12：实现授权记录

接口：

- POST /api/projects/:id/authorizations

验收：

- 未授权不能进入照片质检。
- 授权记录包含 IP 和 UA。

## 7. 阶段 5：照片与人物档案

### 任务 13：实现照片上传

要求：

- 按 person_role 上传
- 创建 asset
- 绑定 project

验收：

- 上传成功。
- 角色归属正确。

### 任务 14：实现基础照片质检 Worker

第一版可先实现基础检测：

- 文件格式
- 尺寸
- 文件大小
- 是否可读取

后续接 Python 人脸检测。

验收：

- 合格返回 pass。
- 不合格返回 fail。

### 任务 15：实现人物档案生成

要求：

- 汇总合格照片
- 创建 person_profiles
- 外貌摘要先可用文本模型生成，或手动占位

验收：

- 每个角色有 person_profile。

## 8. 阶段 6：AI Provider 抽象

### 任务 16：实现 Provider 配置表和管理 API

要求：

- provider_configs
- provider_logs
- 后台可新增编辑测试

验收：

- Provider 不写死在代码。

### 任务 17：实现 TextProvider 接口

功能：

- generatePlan
- generatePrompt
- generateCopy

验收：

- 输入项目数据，输出创作方案 JSON。

### 任务 18：实现 ImageProvider 接口

功能：

- generatePreviewImage
- generateFinalImage

验收：

- 可生成图片并保存 asset。

### 任务 19：实现 VoiceProvider 接口

功能：

- 文本转音频

验收：

- 生成音频 asset。

## 9. 阶段 7：生成工作流

### 任务 20：创作方案生成

接口：

- POST /api/projects/:id/generate-plan
- GET /api/projects/:id/plan
- POST /api/projects/:id/confirm-plan

验收：

- 任务队列化。
- 方案保存为 shot_plans。

### 任务 21：预览图生成

接口：

- POST /api/projects/:id/generate-preview
- POST /api/projects/:id/confirm-preview

验收：

- 生成水印预览图。
- 用户可确认。

### 任务 22：正式图生成

接口：

- POST /api/projects/:id/generate-final

验收：

- 按 shot_plans 生成正式图。
- 图片 asset 绑定镜头。

### 任务 23：图片质检任务

要求：

- 先做基础检查
- 后续接高级检测

验收：

- fail 任务可重试。

## 10. 阶段 8：视频合成

### 任务 24：字幕生成

要求：

- 根据旁白/文案生成 SRT

验收：

- SRT 文件保存为 asset。

### 任务 25：FFmpeg 视频合成 Worker

要求：

- 图片转视频
- 简单推拉
- BGM
- 字幕
- 输出 MP4

验收：

- 生成可播放视频。
- 项目 video_asset_id 更新。

### 任务 26：成品下载

接口：

- GET /api/assets/:id/download-url

验收：

- 签名链接有效。
- 非本人不能下载。

## 11. 阶段 9：订单和额度

### 任务 27：订单创建

接口：

- POST /api/projects/:id/orders

验收：

- 创建 pending 订单。

### 任务 28：支付模拟和状态推进

第一版可做后台手动标记支付。

验收：

- paid 后项目进入 payment_paid。
- 未支付不能正式生成。

### 任务 29：额度和成本日志

要求：

- 任务成本记录
- 项目成本汇总

验收：

- 后台能看到项目成本。

## 12. 阶段 10：后台管理

### 任务 30：接入 Geeker-Admin

要求：

- 登录
- 菜单
- 权限
- 基础布局

验收：

- 后台可登录。

### 任务 31：项目管理页

功能：

- 项目列表
- 项目详情
- 任务查看
- 素材查看

### 任务 32：模板管理页

功能：

- 主题
- 套餐
- 风格
- 世界
- 场景
- 镜头

### 任务 33：任务管理页

功能：

- 查看任务
- 重试
- 终止
- 转人工

### 任务 34：案例管理页

功能：

- 从项目生成案例
- 上架/下架
- 设置首页推荐

## 13. 阶段 11：修改与审核

### 任务 35：修改申请

接口：

- POST /api/projects/:id/revisions
- 后台处理修改申请

验收：

- 修改次数扣减。
- 大改提示重新计费。

### 任务 36：人工审核流程

要求：

- manual_review 状态
- 审核通过/驳回

验收：

- 高端项目可进入人工审核。

## 14. 阶段 12：稳定性和运维

### 任务 37：任务幂等

要求：

- input_hash
- 重复请求不重复生成

### 任务 38：错误码和异常处理

要求：

- 统一错误返回
- 日志记录

### 任务 39：清理任务

要求：

- 临时文件清理
- 过期下载链接

### 任务 40：部署脚本

要求：

- Docker Compose 或 PM2
- Nginx 配置示例
- 环境变量模板

## 15. 建议开发顺序

```text
基础框架
→ 用户登录
→ 模板系统
→ 项目创建
→ 文件上传
→ 照片质检
→ AI Provider
→ 创作方案
→ 图片生成
→ 视频合成
→ 后台管理
→ 订单支付
→ 修改审核
→ 稳定性增强
```

## 15.1 V3 真人动态视频追加阶段

V3 不建议一开始就全片真实视频化，应按以下顺序追加：

```text
V2 图集/图片视频主流程
→ 输出模式分层
→ 真人身份锚点
→ 本人相似度质检
→ 动态写真轻动效
→ 真实 VideoProvider 配置
→ 单镜头真实视频小样
→ 视频片段列表/重试/质检
→ 片段合成
→ 口型任务，可选
→ 隐私/未成年人/公开案例强化验收
```

### 阶段 13：输出模式和身份锚点

任务 41：项目输出模式

- 增加 `output_mode`：photo_album/image_video/motion_portrait/real_video/premium_film。
- 用户端创建项目时明确选择。
- 后台项目列表展示输出模式。

任务 42：身份锚点表和接口

- 增加 `identity_anchors`。
- 支持生成锚点、用户确认、后台确认。
- 未确认锚点不允许真实视频生成。

任务 43：FaceConsistencyProvider

- 抽象本人相似度检查。
- 第一版可 mock，后续接真实人脸一致性服务。
- 结果写入 `face_consistency_score`。

### 阶段 14：动态写真和动作模板

任务 44：动作模板管理

- 增加 `motion_templates`。
- 后台可维护动作名称、Prompt 规则、时长、难度和成本等级。

任务 45：动态写真片段

- 支持眨眼、微笑、头发衣服轻微动、背景动效。
- 先用 mock 或轻量 Provider 跑通，不直接上全片真实视频。

### 阶段 15：AI 真人动态视频片段

任务 46：VideoProvider 国内预设

- 预置 MiniMax Hailuo、阿里 Wan、Vidu、Seedance、Kling、Runway。
- 默认禁用。
- 后台可配置 Key、Base URL、模型、单价、成本阈值。

任务 47：视频片段生成

- 增加 `video_clips`。
- 按镜头生成 3-6 秒片段。
- 生成前做成本估算。
- 用户确认后才真实生成。
- 失败不能回落 mock 假成功。

任务 48：视频片段质检

- 检查像不像本人、动作、表情、年龄变化、混脸、多出第三人。
- 支持 passed/needs_retry/manual_review/rejected。

任务 49：视频片段合成

- 使用 FFmpeg concat 合成多个片段。
- 加旁白、字幕、BGM。
- 支持片段替换后重新合成。

### 阶段 16：口型和高端纪念片

任务 50：LipSyncProvider

- 增加 `lipsync_tasks`。
- 绑定视频片段和音频资产。
- 口型失败可回退旁白字幕版本。

任务 51：高端真人纪念片后台流程

- 人工报价。
- 人工审核。
- 多轮修改。
- 片段精修和替换。

任务 52：V3 合规验收

- 未成年人保护。
- 公开案例二次授权。
- 后台访问原图审计。
- 删除项目清理原图、锚点、关键帧、视频片段。

## 16. Codex 使用建议

每次只给 Codex 一个任务，附带：

- 目标
- 相关表
- 相关接口
- 相关文件路径
- 验收标准
- 注意事项

不要一次让 Codex “开发完整系统”。