Initial AI manga platform

2026-06-15 17:45:28 +08:00
commit 7a8191650f
267 changed files with 105987 additions and 0 deletions
@@ -0,0 +1,635 @@
+# 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 “开发完整系统”。