# 换装跳舞直播间 — 技术设计文档(Model / View / Control / Process) 依据:产品需求 `docs/todo/dressup-dance-room.md`(下称"需求文档",本文各处 引用其章节号);系统架构 `docs/structure/architecture.md`(下称"架构文档")。 本文档把已确认的产品决策落到:数据库表结构(M)、前后端界面清单(V)、 按钮/交互动作(C)、各类用户的操作流程(P),供开发排期和实现参考。 约定:字段名延续现有 `library.json`/`live-state.json` 的英文小驼峰风格; 表结构在第一期仍以 JSON 文件承载,第三期(用户账号)后迁移 SQLite(见 架构文档 1.4 节)——本文按"关系表"描述,两种落地方式都能直接映射。 --- ## M — Model:数据结构设计 ### M.1 `users` | 字段 | 类型 | 说明 | |---|---|---| | `id` | string (uuid) | 主键 | | `email` | string | 邮箱,唯一(7.1 节,第一期登录方式) | | `passwordHash` | string | bcrypt/argon2,邮箱登录用 | | `oauthProviders` | array | 预留 `["google","apple","github"]`,第一期为空数组 | | `nickname` | string | 展示昵称,迁移自现有 cookie `viewer_nickname` | | `legacyUid` | string \| null | 绑定的旧 `viewer_uid`(cookie),用于历史投票/点播记录迁移,见 P.4 | | `ageConfirmed` | boolean | "我已满18岁" 勾选记录(5.1 节) | | `ageConfirmedAt` | number (ts) | | | `creditBalance` | number | 当前积分余额(冗余字段,权威值仍是 `credit_ledger` 流水汇总,见 M.2) | | `createdAt` | number (ts) | | ### M.2 `credit_ledger`(积分流水,7.2 节) | 字段 | 类型 | 说明 | |---|---|---| | `id` | string | 主键 | | `userId` | string | 外键 → `users.id` | | `delta` | number | 正数=充值/退款,负数=消费 | | `reason` | enum | `topup` \| `spend_garment` \| `spend_character` \| `refund_stage1_fail` \| `refund_stage2_fail` \| `refund_moderation_reject` \| `admin_adjust` | | `relatedAssetId` | string \| null | 关联的 `garments.id` 或 `characters.id`(消费/退款时) | | `balanceAfter` | number | 变动后余额,写入时计算好,避免每次汇总流水 | | `paymentRef` | string \| null | 充值时的外部支付流水号(Stripe/支付宝等,7.3 节) | | `createdAt` | number (ts) | | ### M.3 `characters`(人物库) | 字段 | 类型 | 说明 | |---|---|---| | `id` | string | 主键 | | `name` | string | | | `imageUrl` | string | 人物参考图 | | `tags` | array | | | `source` | enum | `admin_seed` \| `user_paid`(6.1 节) | | `ownerUserId` | string \| null | `user_paid` 来源必填 | | `isDefault` | boolean | 是否为直播默认人物;第一期**全库最多一条为 true**(6.1 节已确认,不做多人物轮换) | | `moderationStatus` | enum | `auto_passed` \| `blacklisted` \| `manually_removed`(5 节:自动黑名单过滤,无强制人工预审) | | `totalSegments` | number \| null | 付费购买的 10 秒片段总配额,`admin_seed`/默认人物为 null(不限量,只受 4.6 节去重缓存影响的是复用次数,不是配额) | | `remainingSegments` | number \| null | 剩余可播片段数,每播放一段 -1(7.2 节;架构文档 2.7 节) | | `status` | enum | `active` \| `expired`(配额耗尽后置 `expired`,记录不删除,7.4 节/架构文档 2.7 节) | | `createdAt` | number (ts) | | ### M.4 `garments`(衣服库) | 字段 | 类型 | 说明 | |---|---|---| | `id` | string | 主键 | | `name` | string | | | `category` | string | 分类标签(古风/泳装/校服…) | | `thumbnailUrl` | string | | | `imageUrl` | string | 原图 | | `source` | enum | `admin_seed` \| `user_paid`(6.2 节) | | `ownerUserId` | string \| null | | | `moderationStatus` | enum | `pending` \| `approved` \| `rejected`(模式二走轻量图片审核,审核通过默认沉淀进公共库,3 节模式二第 3 点) | | `isActive` | boolean | 上下架开关 | | `createdAt` | number (ts) | | ### M.5 `dance_refs`(参考跳舞视频/音乐库) | 字段 | 类型 | 说明 | |---|---|---| | `id` | string | 主键 | | `name` | string | | | `videoUrl` | string | | | `styleTags` | array | | | `durationSec` | number | | | `motionDescriptor` | string | **管理员手写的动作描述**(如"拉丁风格摆胯+举臂旋转"),拼进 Stage2 prompt 模板的 `detailed_description`(已确认,需求文档 4.2/6.3 节),上传时必填 | | `copyrightSource` | enum | `test_placeholder` \| `self_made` \| `licensed`(第一期全部 `test_placeholder`,6.3/8 节) | | `isActive` | boolean | | | `createdAt` | number (ts) | | ### M.6 `composed_images`(Stage1 换装图产物) | 字段 | 类型 | 说明 | |---|---|---| | `id` | string | 主键 | | `characterId` | string | 外键 | | `garmentId` | string | 外键 | | `imageUrl` | string | 合成结果 | | `model` | string | 实际调用的 fal.ai 模型标识(4.1/8 节,待选型) | | `appearanceDescriptor` | string | **Stage1 完成后自动调视觉模型描述这张换装图**,生成 2-3 条具体特征(发色/发型、服装颜色款式等),拼进 Stage2 prompt 模板的 `subject_definitions`/`detailed_description`(已确认,需求文档 4.2 节)。生成失败不阻塞——留空则 Stage2 直接拒绝提交并重试打标,而不是拿"如图所示"这种不合规描述硬凑(H3 规范明确不允许) | | `status` | enum | `generating` \| `done` \| `failed` | | `createdAt` | number (ts) | | **唯一索引 `(characterId, garmentId)`**——这是 4.6 节去重缓存的落地位置: 提交前先按这个组合查是否已有 `status: done` 的记录,命中直接复用,不 新建。 ### M.7 `generated_videos`(Stage2 产物,`library.json` 风格 clip 的超集) 在现有 `library.json` clip 字段基础上(见 `docs/done` 第 3 节)新增: | 新增字段 | 类型 | 说明 | |---|---|---| | `characterId` | string | | | `garmentId` | string | | | `composedImageId` | string | 外键 → M.6,点开能看 Stage1 合成图(6.4 节) | | `refDanceVideoId` | string | 外键 → M.5 | | `channel` | enum | `live` \| `dance`(区分是 `live.html` 还是 `dance.html` 的产物,两条独立时刻表共用同一张表时靠这个字段区分,见架构文档 2.1 节) | | `backend` | enum | `h3_console` \| `fal`(4.3 节双算力策略,记录这条具体是哪条算力路径生成的,便于追溯成本) | | `priority` | enum | `normal` \| `paid_boost`(`paid_boost` = 付费新人物内容,排播时走 2.6 节"插队"通道,不参与投票) | | `requestedByUserId` | string \| null | 付费请求必填,免费匿名请求为 null(用 `legacyUid` 兜底) | | `width`/`height` | number | `dance` 频道默认 480×832;`live` 频道走独立的 `H3_GEN_PARAMS`,目前也是 480×832(`docs/done` 2.2 节),两者不共享同一份配置 | ### M.8 直播时刻表状态(非持久化数据库表,`live-state.json` 风格的内存+落盘结构,`dance.html` 独立一份) ```jsonc { "channel": "dance", "schedule": [{ "videoId": "...", "startAt": 0, "endAt": 0, "requestedBy": null, "priority": "normal" }], "priorityInbox": [ /* paid_boost 产物就绪后先进这里,ensureSchedule 优先消费,见架构文档 2.6 节 */ ], "freeQueue": [ /* 免费模式一提交,走投票排序,结构同 v1 promptQueue */ ] } ``` ### M.9 `moderation_log` | 字段 | 类型 | 说明 | |---|---|---| | `id` | string | 主键 | | `assetType` | enum | `garment_upload` \| `character_upload` | | `assetId` | string | | | `verdict` | enum | `auto_pass` \| `auto_reject_blacklist` \| `admin_takedown`(5 节:自动过 + 事后人工兜底) | | `reason` | string \| null | | | `reviewedBy` | string | `system` 或管理员 `userId` | | `createdAt` | number (ts) | | ### M.10 ER 关系图 ```mermaid erDiagram users ||--o{ credit_ledger : "流水" users ||--o{ characters : "user_paid 拥有者" users ||--o{ garments : "user_paid 拥有者" users ||--o{ generated_videos : "requestedBy" characters ||--o{ composed_images : "Stage1 输入" garments ||--o{ composed_images : "Stage1 输入" composed_images ||--o{ generated_videos : "Stage2 输入" dance_refs ||--o{ generated_videos : "Stage2 输入" characters ||--o{ moderation_log : "审核记录" garments ||--o{ moderation_log : "审核记录" ``` ### M.11 Stage2 默认 Prompt 模板(已确认,需求文档 4.2 节) 依据仓库里的 `docs/h3skill.md`(内部 H3 提示词写作方法论)"全能参考 模式六段式"结构写成。**`{{...}}` 是占位符**,由 M.6/M.5 的 `appearanceDescriptor`/`motionDescriptor` 字段在拼装时填入: - `` = Stage1 换装合成图(`composed_images.imageUrl`) - `