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