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,649 @@
+# 06_API接口设计文档
+
+## 1. 文档目标
+
+本文档定义系统 B 的 API 接口结构、请求参数、返回格式、错误码和权限要求。
+
+## 2. 通用规范
+
+### 2.1 Base URL
+
+```text
+/api
+```
+
+后台接口：
+
+```text
+/api/admin
+```
+
+### 2.2 通用返回格式
+
+```json
+{
+  "code": 0,
+  "message": "ok",
+  "data": {}
+}
+```
+
+错误示例：
+
+```json
+{
+  "code": 40001,
+  "message": "照片质量不合格",
+  "data": {
+    "reason": "face_blur"
+  }
+}
+```
+
+### 2.3 通用错误码
+
+| code | 含义 |
+|---|---|
+| 0 | 成功 |
+| 40000 | 参数错误 |
+| 40100 | 未登录 |
+| 40300 | 无权限 |
+| 40400 | 资源不存在 |
+| 40900 | 状态冲突 |
+| 42900 | 请求过于频繁 |
+| 50000 | 系统错误 |
+| 60000 | AI 生成失败 |
+| 60001 | Provider 不可用 |
+| 70000 | 支付失败 |
+| 80000 | 审核不通过 |
+
+## 3. 认证接口
+
+### 3.1 发送验证码
+
+```text
+POST /api/auth/send-code
+```
+
+请求：
+
+```json
+{ "phone": "13800000000" }
+```
+
+返回：
+
+```json
+{ "success": true }
+```
+
+### 3.2 手机号登录
+
+```text
+POST /api/auth/login-phone
+```
+
+请求：
+
+```json
+{
+  "phone": "13800000000",
+  "code": "123456"
+}
+```
+
+返回：
+
+```json
+{
+  "token": "jwt-token",
+  "user": { "id": 1, "nickname": "用户" }
+}
+```
+
+### 3.3 微信登录
+
+```text
+POST /api/auth/login-wechat
+```
+
+请求：
+
+```json
+{ "code": "wechat_code" }
+```
+
+## 4. 首页与案例接口
+
+### 4.1 首页配置
+
+```text
+GET /api/home
+```
+
+返回：
+
+```json
+{
+  "banners": [],
+  "featured_cases": [],
+  "themes": [],
+  "packages": []
+}
+```
+
+### 4.2 案例列表
+
+```text
+GET /api/cases?theme_id=1&style_id=2&page=1&page_size=20
+```
+
+### 4.3 案例详情
+
+```text
+GET /api/cases/:id
+```
+
+## 5. 模板查询接口
+
+### 5.1 人生主题列表
+
+```text
+GET /api/life-themes
+```
+
+### 5.2 套餐列表
+
+```text
+GET /api/packages?theme_id=1
+```
+
+### 5.3 风格列表
+
+```text
+GET /api/styles?theme_id=1
+```
+
+### 5.4 世界观列表
+
+```text
+GET /api/worlds?theme_id=1&style_id=2
+```
+
+### 5.5 场景列表
+
+```text
+GET /api/worlds/:world_id/scenes
+```
+
+## 6. 项目接口
+
+### 6.1 创建项目
+
+```text
+POST /api/projects
+```
+
+请求：
+
+```json
+{
+  "title": "我们的时空纪念片",
+  "life_theme_id": 1,
+  "output_type": "video"
+}
+```
+
+返回：
+
+```json
+{
+  "project_id": 1001,
+  "status": "draft"
+}
+```
+
+### 6.2 获取项目详情
+
+```text
+GET /api/projects/:id
+```
+
+### 6.3 保存套餐
+
+```text
+POST /api/projects/:id/package
+```
+
+请求：
+
+```json
+{ "package_id": 2 }
+```
+
+### 6.4 保存风格
+
+```text
+POST /api/projects/:id/style
+```
+
+请求：
+
+```json
+{ "style_id": 3 }
+```
+
+### 6.5 保存世界观
+
+```text
+POST /api/projects/:id/worlds
+```
+
+请求：
+
+```json
+{
+  "selected_worlds": [
+    { "world_id": 1, "sort_order": 1 },
+    { "world_id": 5, "sort_order": 2 }
+  ]
+}
+```
+
+### 6.6 保存场景
+
+```text
+POST /api/projects/:id/scenes
+```
+
+请求：
+
+```json
+{
+  "selected_scenes": [
+    { "world_id": 1, "scene_id": 11, "sort_order": 1 },
+    { "world_id": 5, "scene_id": 51, "sort_order": 2 }
+  ]
+}
+```
+
+### 6.7 保存定制信息
+
+```text
+POST /api/projects/:id/custom-info
+```
+
+请求：
+
+```json
+{
+  "names": { "person_a": "男方", "person_b": "女方" },
+  "relationship_type": "couple",
+  "anniversary_date": "2026-05-20",
+  "copy_mood": "romantic",
+  "show_names": true,
+  "show_date": true,
+  "vow_text": "愿此生与你共赴山海",
+  "special_requirements": "整体梦幻，不要太搞笑",
+  "allow_public_case": false
+}
+```
+
+### 6.8 项目进度
+
+```text
+GET /api/projects/:id/progress
+```
+
+返回：
+
+```json
+{
+  "status": "final_generating",
+  "percent": 65,
+  "current_step": "正式图片生成中",
+  "tasks": [
+    { "task_type": "final_image", "success": 12, "total": 20 }
+  ]
+}
+```
+
+### 6.9 我的项目列表
+
+```text
+GET /api/my/projects?page=1&page_size=20
+```
+
+## 7. 文件与照片接口
+
+### 7.1 上传照片
+
+```text
+POST /api/projects/:id/photos
+Content-Type: multipart/form-data
+```
+
+字段：
+
+```text
+person_role: person_a/person_b/child/self
+file: image
+```
+
+返回：
+
+```json
+{
+  "asset_id": 2001,
+  "url": "signed-url",
+  "status": "uploaded"
+}
+```
+
+### 7.2 删除照片
+
+```text
+DELETE /api/assets/:asset_id
+```
+
+### 7.3 触发照片质检
+
+```text
+POST /api/projects/:id/photo-check
+```
+
+### 7.4 获取照片质检结果
+
+```text
+GET /api/projects/:id/photo-check-result
+```
+
+## 8. 授权接口
+
+### 8.1 提交授权确认
+
+```text
+POST /api/projects/:id/authorizations
+```
+
+请求：
+
+```json
+{
+  "types": ["photo_usage", "privacy_policy", "terms"],
+  "minor_guardian_confirmed": false
+}
+```
+
+### 8.2 公开案例授权
+
+```text
+POST /api/projects/:id/public-case-authorization
+```
+
+## 9. AI 生成流程接口
+
+### 9.1 生成创作方案
+
+```text
+POST /api/projects/:id/generate-plan
+```
+
+返回：
+
+```json
+{
+  "task_id": 3001,
+  "status": "pending"
+}
+```
+
+### 9.2 获取创作方案
+
+```text
+GET /api/projects/:id/plan
+```
+
+### 9.3 确认创作方案
+
+```text
+POST /api/projects/:id/confirm-plan
+```
+
+### 9.4 生成预览
+
+```text
+POST /api/projects/:id/generate-preview
+```
+
+### 9.5 确认预览
+
+```text
+POST /api/projects/:id/confirm-preview
+```
+
+### 9.6 正式生成
+
+```text
+POST /api/projects/:id/generate-final
+```
+
+### 9.7 获取项目素材
+
+```text
+GET /api/projects/:id/assets?asset_type=final_image
+```
+
+## 10. 订单支付接口
+
+### 10.1 创建订单
+
+```text
+POST /api/projects/:id/orders
+```
+
+请求：
+
+```json
+{ "package_id": 2, "pay_method": "wechat" }
+```
+
+### 10.2 获取支付状态
+
+```text
+GET /api/orders/:id
+```
+
+### 10.3 支付回调
+
+```text
+POST /api/payments/wechat/callback
+```
+
+## 11. 修改申请接口
+
+### 11.1 提交修改申请
+
+```text
+POST /api/projects/:id/revisions
+```
+
+请求：
+
+```json
+{
+  "revision_type": "small",
+  "request_text": "请把片尾日期改成 2026-05-20"
+}
+```
+
+### 11.2 修改申请列表
+
+```text
+GET /api/projects/:id/revisions
+```
+
+## 12. 下载接口
+
+### 12.1 获取下载链接
+
+```text
+GET /api/assets/:asset_id/download-url
+```
+
+返回：
+
+```json
+{
+  "url": "signed-download-url",
+  "expires_in": 3600
+}
+```
+
+## 13. 后台接口示例
+
+### 13.1 后台项目列表
+
+```text
+GET /api/admin/projects?status=manual_review&page=1&page_size=20
+```
+
+### 13.2 后台项目详情
+
+```text
+GET /api/admin/projects/:id
+```
+
+### 13.3 后台任务重试
+
+```text
+POST /api/admin/tasks/:id/retry
+```
+
+### 13.4 后台任务终止
+
+```text
+POST /api/admin/tasks/:id/cancel
+```
+
+### 13.5 后台转人工
+
+```text
+POST /api/admin/projects/:id/manual-review
+```
+
+### 13.6 后台模板新增/编辑
+
+```text
+POST /api/admin/world-templates
+PUT /api/admin/world-templates/:id
+POST /api/admin/scene-templates
+PUT /api/admin/scene-templates/:id
+```
+
+### 13.7 后台 Provider 测试
+
+```text
+POST /api/admin/providers/:id/test
+```
+
+## 14. WebSocket 进度推送
+
+连接：
+
+```text
+/ws/projects/:project_id
+```
+
+事件：
+
+```json
+{
+  "event": "project_progress",
+  "data": {
+    "project_id": 1001,
+    "status": "video_rendering",
+    "percent": 82,
+    "message": "视频合成中"
+  }
+}
+```
+
+## 15. 权限规则
+
+- 用户只能访问自己的项目、素材、订单。
+- 后台管理员按角色权限访问后台接口。
+- Provider 密钥不可通过接口返回明文。
+- 公开案例必须检查授权记录。
+
+## 16. V3 真人动态视频接口增量
+
+### 16.1 输出模式
+
+```text
+PATCH /api/projects/:id/output-mode
+```
+
+请求：
+
+```json
+{
+  "output_mode": "real_video"
+}
+```
+
+### 16.2 身份锚点
+
+```text
+POST /api/projects/:id/identity-anchors/generate
+GET  /api/projects/:id/identity-anchors
+POST /api/identity-anchors/:anchor_id/confirm
+POST /api/identity-anchors/:anchor_id/reject
+```
+
+### 16.3 人脸一致性质检
+
+```text
+POST /api/person-profiles/:person_id/face-consistency/check
+GET  /api/person-profiles/:person_id/face-consistency/latest
+```
+
+### 16.4 动作模板
+
+```text
+GET /api/motion-templates
+GET /api/admin/motion-templates
+POST /api/admin/motion-templates
+PUT /api/admin/motion-templates/:id
+```
+
+### 16.5 真人动态视频片段
+
+```text
+GET  /api/projects/:id/video-clips
+GET  /api/projects/:id/video-clips/cost-estimate
+POST /api/projects/:id/video-clips/generate
+POST /api/video-clips/:clip_id/retry
+POST /api/video-clips/:clip_id/quality-check
+POST /api/video-clips/:clip_id/replace
+```
+
+真实生成请求必须包含：
+
+```json
+{
+  "provider_code": "minimax_hailuo_23_fast",
+  "confirm_real_video": true,
+  "max_cost_per_clip": 1.0
+}
+```
+
+未确认或 Provider 未启用时，应返回明确错误，不允许回落 mock。
+
+### 16.6 口型任务
+
+```text
+POST /api/video-clips/:clip_id/lipsync
+GET  /api/projects/:id/lipsync-tasks
+POST /api/lipsync-tasks/:task_id/retry
+```