宜博 / h3livestream

dressup-dance-room.md 20.1 KB

换装跳舞直播间 — 需求文档（TODO / 未实现）

对应现状基线见 docs/done/live-channel-v1.md；架构层面的落地方案见 docs/structure/architecture.md。本文档记录已与产品方确认的决策 （第 2～7 节），以及仍需要技术验证/调研、非产品决策问题的部分（第 8 节）。

1. 背景与目标

新增一个跟现有文字点播直播间并列的产品：换装跳舞直播间。点播动作从 "打字描述想看什么"变成"选衣服 / 传衣服 / 传人"，本质是把"自由文本生成" 收窄成"资产库组合生成"：

人物照片（资产库） + 衣服照片（资产库或观众上传） → 生成"新衣服小姐姐"参考图 → 参考图 + 参考跳舞视频 → 生成新跳舞视频 → 排入直播间播放队列

2. 产品形态：两个独立的直播间页面（已确认）

  • live.html（现状，不变）：文字点播直播间，观众打字描述想看什么， 详见 docs/done/live-channel-v1.md。
  • dance.html（新增）：换装跳舞直播间，没有文字输入框，点播动作 全部是"选衣柜 / 传衣服 / 传人"。与 live.html 样式保持一致（同一套 视觉语言、同一套播放器/队列 UI 组件），但左侧点播面板换成换装操作， 右侧保留非文字的互动展示（在线人数、点赞、排队列表——这些跟 live.html 一样保留，只是没有聊天输入）。
  • 两个页面各自维护独立的播出时刻表（各自的 schedule/promptQueue）， 不是同一个直播间的两个 tab——它们是两条并行的产品线，共用后端的 素材库/生成流水线/账号体系等基础设施。
  • dance.html 默认竖屏、移动端优先——具体规格见第 4.4 节。 （勘误：live.html 一侧此后也已独立改成竖屏默认，见 4.4 节末尾说明， 两个频道各自的 H3_GEN_PARAMS 配置互不影响，只是当时判断的"横屏不变" 前提已经过时。）

3. 观众体验流程（已确认：使用已有资产库免费，新增资产付费）

模式一：从衣柜选衣服（免费）

  1. 观众打开"衣柜"面板，浏览后台预置/其他观众上传后已沉淀的服装素材 （缩略图 + 名称/分类）。
  2. 点选一件 → 人物固定用系统默认人物（免费用户不能指定/上传人物，只能 换衣服）。第一期默认人物固定只有一个（不做多个轮换/观众选人物， 前端不需要人物选择器；后台仍以列表形式管理人物库，为以后想扩展成 多个预留空间，见 6.1 节）。
  3. 提交 → 进入生成流水线（第 4 节）→ 完成后排入播放队列。同一件衣服被 多个观众点中时，走去重缓存直接复用已有产物，见 4.6 节。
  4. 完全免费，不消耗积分——这是主力免费入口，降低参与门槛。

模式二：上传自己的衣服照片（付费，"新增衣服"）

  1. 观众上传一张衣服/穿搭图片，走轻量内容审核。
  2. 消耗积分（因为这是往衣服库里"新增"一件素材，成本高于直接选用现成 素材）。
  3. 审核通过后默认沉淀进公共衣柜库，之后所有观众（含免费用户）都能在 模式一里选到这件衣服——相当于"付费的人帮全站扩充了衣柜"。
  4. 人物仍然是系统默认人物（模式二不涉及换人物）。

模式三：上传喜欢的小姐姐照片（付费，"新增人物"）

  1. 观众上传一张人物照片。
  2. 经自动化审核（第 5 节）后即可生成——不是强制人工先审。
  3. 充值/消耗的积分数量，直接决定这个新人物能播放几个 10 秒片段—— 花得越多，这个新角色在直播间露出的时长越长。
  4. 衣服可以在提交时一并选/传，也可以不选（系统随机挑一件衣柜库服装 搭配）。
  5. 参考跳舞视频固定走系统随机（第 3.4 点）。
  6. 新人物默认不沉淀进公共人物池，只服务上传者本人这次付费请求—— 不会出现"张三充值上传的照片被李四的免费请求随机抽中生成"的情况。
  7. 到期处理：购买的那几个 10 秒片段播完后，自动下线，但人物、换装 参考图、已生成的视频都保留记录——用户之后再充值，可以直接续播 （复用已有素材，不用重新走一遍 Stage1/Stage2 生成）。

三种模式的共同后置流程

  • 提交后立刻在"生成中"列表出现一条（带上传者昵称），复用现有排队 UI。
  • 生成成功 → 排入待播队列。免费内容（模式一/二）按 v1 现有投票机制 排序；模式三付费新人物内容不参与投票，直接插队/优先播放（已 确认——付费买的是"确定性上镜"，不能让它跟免费内容拼投票数），这一点 是对 v1 ensureSchedule 选片算法的实质性改动，见 docs/structure/architecture.md 1.3/2.6 节。
  • 生成失败/审核不过 → 现有"❌"状态展示；若是付费请求失败，需要退还 已扣的积分，这是底线（见第 7.2 节）。

4. 生成流水线设计（两段式 + 双算力策略）

4.1 Stage 1：人物 + 衣服 → 换装参考图

输入一张人物参考图 + 一张衣服参考图，输出"该人物穿该衣服"的合成图， 人脸/体型一致，只换装扮。走 fal.ai（具体模型见第 8 节，需要小范围实测 后确定），复用 server.js 已有的 /fal/* 反代通道——H3 Console 本身 不产出图片，Stage1 无论如何都得走别的模型。

4.2 Stage 2：换装参考图 + 参考跳舞视频 → 生成跳舞视频

换装图（reference_image_urls）+ 参考跳舞视频（reference_video_urls， 提供舞蹈动作/运镜/配乐节奏，系统随机/轮换挑选，观众不选风格）→ 生成 10 秒左右的跳舞视频片段。产物字段是 v1 library.json clip 的超集，加 characterId/garmentId/composedImageId/refDanceVideoId 溯源字段。

4.3 双算力策略（已确认）

同一个 Stage2（甚至 Stage1）流程，跑在两条不同的算力路径上，按"是否是 付费实时请求"切换：

场景 算力 理由
冷启动/后台种子内容（admin 预先批量生成，铺满衣柜库/默认人物库的初始内容，不面向单个观众的实时请求） 内部 H3 Console（自建 GPU 集群） 免费、无按次成本，但单条约 200s（见 H3-CONSOLE.md），批量提前跑不受实时性压力，适合"不着急"的场景
观众付费实时请求（模式二付费传衣服、模式三付费传人物） fal.ai 云端（minimax/h3* 系列端点，/fal/* 反代已有雏形，见 app.js） 快得多（约 4s 级别 vs 内部集群约 200s，见 H3-CONSOLE.md 实测对比），付费用户对等待时间敏感，成本由用户支付的积分覆盖

即：免费内容靠自己的卡慢慢攒库存，付费内容花钱买 fal.ai 的实时速度。 Stage1（换装图合成）在两条路径下大概率都是 fal.ai（H3 Console 不产图）， 只有 Stage2（视频生成）真正分叉成两条算力。

4.4 视频规格：默认竖屏，移动端优先（已确认，仅 dance.html）

  • dance.html 生成的视频默认竖屏（live.html 现有横屏内容不受影响， 两个直播间各自独立的规格，见第 2 节）。
  • 默认分辨率 480×832——现有 server.js 里 H3_GEN_PARAMS 的横屏 默认是 832×480（总像素量 ≈ 40 万），480×832 只是宽高对调，总像素量 完全不变，理论上不会因为改成竖屏而拖慢生成耗时（H3 集群单条本来就 约 200s，见 H3-CONSOLE.md，竖屏化不能再让这个数字变得更差）。
  • 更高分辨率（576×1024/720×1280 等）画质更好，但会明显增加生成耗时， 不作为默认，可以作为后续付费选项预留（呼应第 7.2 节"新增资产才 消耗积分"的思路——高清可以是另一档付费能力，不是本期范围，先不做）。
  • 前端播放器/排版要跟着调整：dance.html 复用 live.html 的 CSS 风格 （2.1 节），但播放器容器要按 9:16 竖屏比例设计，不能直接套用 live.html 现有横屏播放器的宽高比，否则会出现大黑边——这是 dance.html 相对 live.html 除了"没有文字输入框"之外的第二个视觉 差异点。
  • 勘误：server.js 的 H3_GEN_PARAMS（live.html 使用的那份） 之后被单独改成了 480×832（commit 1dc7084），也就是说 live.html 新生成的内容现在其实也是竖屏了，存量片段仍是原比例混播（播放器靠 object-fit: contain 兼容）。这是 live.html 那条独立产品线自己的 改动，跟 dance.html 的配置互不影响，但上面"仅 dance.html"的表述 已不完全准确，记录于此，详见 docs/todo/dressup-dance-room-mvcp.md 文末"勘误"一节。

4.5 失败/超时处理

  • Stage1 失败：直接终止，不进入 Stage2，不占用 GPU/API 额度；付费请求 的话退还积分。
  • Stage2 失败/超时：复用 v1 generateForPrompt 现成的重试/超时/持久化 套路（h3JobId/fal 任务 id 落盘，进程重启能续投）。

4.6 相同人物+衣服组合去重缓存（已确认，限模式一免费路径）

  • 模式一固定用同一个默认人物（2 节），衣服总量有限，多个观众大概率会 选中同一件——相同"人物+衣服"组合直接复用已有的换装图（Stage1）和 生成视频（Stage2），不重新生成，直接把已有产物排入播放队列。
  • 目的：省 GPU/API 成本，也让免费入口的点播延迟大幅降低（命中缓存约等 于 v1 现有"素材库命中"那种秒级体验，见 docs/done 2.2 节）。
  • 缓存 key 是 (characterId, garmentId) 组合；命中判断在提交时做， 跟 v1 findLibraryMatch 的"先查库再生成"套路是同一个思路，只是匹配 维度从"文本相似度"换成"资产 id 组合"，实现上更简单可靠。
  • 模式二/三（付费路径）不做去重——每次付费传衣服/传人物本身就是 在新增独特资产，不存在"组合已存在"的情况。

5. 内容审核（已确认：自动黑名单 + 事后人工兜底，非强制先审后播）

  • 模式二（传衣服）：基础审核，复用/扩展 v1 关键词审核思路，但要能 过图片——需要图片内容审核能力（供应商待定，见第 8 节）。
  • 模式三（传人）：走自动化人脸识别黑名单过滤（比如过滤涉政人物 形象），不在黑名单里的人物照片自动通过、直接进入生成，不做强制 人工预审。风险兜底靠两层：
    1. 后台运营发现问题内容可以随时手工下架（第 6.5 节播放管理）。
    2. 新人物内容本身生命周期短——播完购买的那几个 10 秒片段就自动下线 （第 3.3 节第 7 点），把"有问题内容能公开曝光多久"这个风险窗口 天然限制住了，不需要靠"生成前卡审核"来兜底。
  • 无论哪种模式，最终生成内容仍会过 H3 Console / fal.ai 自身的生成时 安全策略兜底（docs/done 2.7 已有此保底），是最后一道防线，不是 唯一防线。
  • 人脸识别黑名单模型具体选型待定，见第 8 节。

5.1 年龄确认与免责声明（已确认）

  • dance.html 涉及付费、真人照片上传、可能包含泳装等服饰分类，且对外 公开——进入前要求勾选"我已满18岁"确认框 + 展示免责声明。基础年龄 确认，不做第三方实名认证（成本更高，暂不需要，见第 8 节留作后续 评估项）。
  • 免费模式一是否也要挂这道确认，还是只在涉及付费/传人操作时弹出： 建议统一放在 dance.html 首次进入时做一次性确认（跟现有 live.html 首次进聊天框弹昵称框的交互套路一致，见 docs/done 2.5 节），而不是 每个操作都弹一次。

6. 后台资产管理需求

在现有 admin.html（v1 素材表格）基础上，新增几类资产的管理页面/模块， 保持同一套"表格 + 行内编辑 + 新增表单"交互风格。

6.1 人物图片管理

  • CRUD：上传人物参考图、命名、打标签、设为"直播默认人物"。
  • 来源区分：admin_seed（后台预置/冷启动批量生成） vs user_paid（模式三付费上传）。user_paid 来源不进入"系统随机挑选 免费用户默认人物"的池子（3.3 节第 6 点），但需要能在后台看到、关联到 付费用户、追踪其"剩余可播 10 秒片段数"。
  • 「设为直播默认人物」开关：模式一/二里"系统指定"的人物来源于此。 第一期只允许同时有一个人物被设为默认（2 节已确认，不做多人物 轮换），开关设计上仍按"列表 + 单选"做，方便以后放开多选/轮换不用 改数据模型。

6.2 衣服物品管理

  • CRUD：上传衣服图、命名、分类/标签、缩略图、上下架开关。
  • 来源区分：admin_seed vs user_paid（模式二上传，审核通过后默认 沉淀进公共库，3.2 节第 3 点）。

6.3 参考跳舞视频/音乐管理

  • CRUD：上传参考跳舞视频（含配乐），命名、风格标签、时长、上下架开关。
  • 版权来源字段：当前先用测试素材占位（正式版权素材待确认，见第 8 节），后台需要能记录/后续批量替换。

6.4 生成后的视频管理

  • 扩展现有 admin.html 素材表格：新增 characterId/garmentId/ composedImageId（可点开看 Stage1 合成图）/refDanceVideoId 列， 追溯"谁的脸 + 谁的衣服 + 哪条参考跳舞视频"生成的。
  • 人工下架/加精；批量删除入口。

6.5 播放管理

  • 插播/置顶下一条、手动跳过当前、暂停自动填充、拉黑某个用户/资产（对接 第 5 节的人工兜底手段）。

7. 用户体系与积分（已确认）

7.1 用户注册

  • 起步方式：邮箱登录（账号+邮箱验证）。
  • 后续迭代：加 Google / Apple / GitHub 三方登录。
  • 现有 viewer_uid/viewer_nickname cookie 身份平滑绑定到账号，历史 投票/点播记录不丢（沿用 docs/structure/architecture.md 2.4 节的 过渡方案）。

7.2 积分模型

  • 充值 → 通用积分池，而不是"充值金额直接换算成固定数量的 10 秒 片段"——积分是通用货币，未来别的付费场景（比如优先排队）也能复用 同一套机制，跟原始需求里"未来消耗积分限制生成频率/质量"的说法一致。
  • 计费边界（已确认）：
    • 使用已有资产库（衣柜里选衣服、系统默认人物）—— 免费，不扣积分。
    • 新增资产（模式二付费传衣服、模式三付费传人物）—— 消耗积分。
    • 新增人物额外规则：消耗的积分数量决定该角色可播放的 10 秒片段数 （3.3 节第 3、7 点）；片段播完后角色下线但记录保留，用户可再充值 续播而不需要重新生成。
  • 具体每次操作扣多少积分、充值档位等数值，还没定（不阻塞开发，先把 余额+流水+配置化扣费额这套机制打好，数值上线前再定，见第 8 节）。
  • 失败退还：Stage1/Stage2 任一环节失败，已扣积分必须退还，不能出现 "扣了积分但没生成成功也不退"的黑洞。

7.3 充值支付渠道（机制已定，具体渠道待定）

  • 初步倾向 Stripe，但具体接哪家先不锁死——积分系统本身设计成 "内部余额+流水"，支付渠道只是"给余额充值"的一个外部入口，换渠道 不影响积分模型本身。
  • ⚠️ 需要提醒的风险点：Stripe 对中国大陆发卡的信用卡/本地支付方式 支持有限（合规和可用性都有限制）。如果这个直播间的目标观众以国内 用户为主（现有 live.html/admin.html UI 全是中文，产品语言明显 面向国内），大概率还需要同时接入支付宝/微信支付才能覆盖主力 用户的实际支付习惯，不能只上 Stripe。这一点建议在真正开发充值流程 前明确一下目标用户地域，见第 8 节。

7.4 个人中心「我的作品」（已确认）

  • 付费生成的内容（模式二上传的衣服、模式三的新人物及其视频），即使 已经从直播排播/复用池下线（3.3 节第 7 点"到期处理"），用户仍要能在 自己的账号下单独查看/回放——不是"下线=消失"，只是"下线=不再出现在 公开直播间和其他人的衣柜/随机池里"。
  • 数据模型含义：生成的视频/换装图/人物记录要挂在 userId 下长期可查， 和"是否还在直播池中"是两个独立的状态维度（呼应 docs/structure/architecture.md 2.7 节"人物生命周期"里提到的 status: active|expired 设计，这里进一步要求 expired 状态下这些 记录依然可被拥有者检索，不是软删除后就不可访问）。
  • 具体页面/交互（列表、是否能重新分享到直播间等）留到对应分期再细化， 这里只确认"数据要保留、要能查"这个底线。

8. 待验证事项（不是产品决策分歧，是需要技术验证/调研才能定的点）

  1. Stage1 换装模型具体选型：fal.ai 平台上有哪些图片编辑/换装类 模型适合"人物+服装 → 换装图"这个场景，需要小范围测试几个人物+衣服 组合，比较一致性/速度/成本后再定。
  2. H3 Console reference_video_urls 实测：H3-CONSOLE.md 里这个 字段目前"未实测，仅从控制台 UI tab 推断存在"，Stage2 落地前第一步 要用真实调用验证这条路径是否按预期工作。
  3. 参考跳舞视频/配乐正式素材来源：目前先用测试素材占位，正式版权 素材（自制还是购买授权）待确认，后台字段已预留（6.3 节）。
  4. 人脸识别黑名单模型选型：用什么模型/服务做"涉政等敏感人物"识别 过滤，需要调研候选方案。
  5. 积分具体数值：充值档位、每次新增衣服/新增人物扣多少积分、新 人物每个 10 秒片段的积分单价——机制已定（7.2 节），数值上线前再定。
  6. 支付网关选型：初步倾向 Stripe，但需要先确认目标观众地域——若 以国内用户为主，大概率要同时/改为接入支付宝/微信支付（7.3 节）， 这一点建议尽早拍板，避免影响充值流程的开发方向。
  7. "我的作品"页面的第三方实名认证需求：第一期只做"我已满18岁" 勾选式确认（5.1 节），是否需要更严格的第三方实名认证，看实际运营 风险再评估，不预设一定要做。

9. 分期建议（不是承诺的排期，是依赖顺序参考）

  1. 第一期：后台先把「人物库 / 衣服库 / 参考跳舞视频库」CRUD 模块 搭出来，用内部 H3 Console 批量跑冷启动种子内容（4.3 节），验证 Stage1→Stage2 全流水线可行性（不接入付费/审核/账号）。
  2. 第二期：dance.html 上线（含首次进入的年龄确认+免责声明，5.1 节），接入「衣柜选衣服」免费模式（3.1 节）+ 相同人物+衣服组合去重 缓存（4.6 节），复用现有排播队列基础设施（此阶段全部免费内容仍按 v1 投票排序，还不涉及"付费插队"这条新规则）。
  3. 第三期：用户注册体系上线（邮箱登录），把匿名 cookie 身份绑定 到账号——账号是后面付费功能的前提，必须先落地。
  4. 第四期：积分体系（余额/流水/配置化扣费）+ 充值支付渠道接入 （7.3 节，先确认目标地域再选具体渠道），先上线免费换衣服 + 付费 传衣服（模式二），验证扣费/退还/公共库沉淀链路。
  5. 第五期：付费传人物（模式三）+ 自动人脸黑名单审核 + "购买 10 秒 片段数 / 到期下线 / 续播"这套人物生命周期管理 + 排播优先级改造（付费 新人物插队播放，见 3 节"共同后置流程"）+ 个人中心"我的作品"页面 （7.4 节），接入 fal.ai 实时算力路径（4.3 节）。