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. 建议开发顺序

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

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

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

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 “开发完整系统”。