dressup-dance-room-mvcp.md 26 KB

换装跳舞直播间 — 技术设计文档(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
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 \
relatedAssetId string \ null
balanceAfter number 变动后余额,写入时计算好,避免每次汇总流水
paymentRef string \ null
createdAt number (ts)

M.3 characters(人物库)

字段 类型 说明
id string 主键
name string
imageUrl string 人物参考图
tags array
source enum admin_seed \
ownerUserId string \ null
isDefault boolean 是否为直播默认人物;第一期全库最多一条为 true(6.1 节已确认,不做多人物轮换)
moderationStatus enum auto_passed \
totalSegments number \ null
remainingSegments number \ null
status enum active \
createdAt number (ts)

M.4 garments(衣服库)

字段 类型 说明
id string 主键
name string
category string 分类标签(古风/泳装/校服…)
thumbnailUrl string
imageUrl string 原图
source enum admin_seed \
ownerUserId string \ null
moderationStatus enum pending \
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 \
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 \
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 \
backend enum h3_console \
priority enum normal \
requestedByUserId string \ null
width/height number dance 频道默认 480×832;live 频道走独立的 H3_GEN_PARAMS,目前也是 480×832(docs/done 2.2 节),两者不共享同一份配置

M.8 直播时刻表状态(非持久化数据库表,live-state.json 风格的内存+落盘结构,dance.html 独立一份)

{
  "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 \
assetId string
verdict enum auto_pass \
reason string \ null
reviewedBy string system 或管理员 userId
createdAt number (ts)

M.10 ER 关系图

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 字段在拼装时填入:

  • <Picture 1> = Stage1 换装合成图(composed_images.imageUrl)
  • <Video 1> = 参考跳舞视频(dance_refs.videoUrl),只作动作/运镜/ 节奏参考,不是视觉身份来源
  • <Audio 1> = 复用 <Video 1> 的配乐轨(H3 规范里参考视频不因为 含声就自动产生 <Audio N>,需要显式定义,见 docs/h3skill.md H15)
subject_definitions:
<Subject 1> is the young woman whose identity is defined by <Picture 1>.
<Picture 1> is the character reference frame: preserve her
{{appearanceDescriptor}} exactly as shown, changing only her pose and
motion to match the choreography described below.
<Video 1> is the reference choreography clip that defines the camera
rhythm and dance structure the target video should follow; it is not a
visual identity source.

summary:
[reference generation] The target video shows <Subject 1>, wearing the
outfit from <Picture 1>, performing {{motionDescriptor}} following the
pacing and camera movement established in <Video 1>.

retention_analysis:
<Subject 1> (appears in [Shot 1]): fully_preserved - her face, hairstyle,
and outfit from <Picture 1> are retained throughout.
<Video 1>: weak_reference - only the choreography rhythm and camera
movement pattern are referenced, no visual content is retained.
<Audio 1>: fully_copy - the background music track from <Video 1> is
reused verbatim.

detailed_description:
A vibrant, mobile-first vertical dance video with warm, glossy studio
lighting. [Shot 1] <Subject 1>, established from <Picture 1> with
{{appearanceDescriptor}}, stands centered in a medium-full shot against a
softly lit backdrop. She performs {{motionDescriptor}}, her weight
shifting smoothly on the beat, arms tracing clean arcs in rhythm with the
music. The camera holds mostly static with a slow, subtle Push In across
the shot, keeping her fully in frame throughout. Her expression is
confident and playful, eyes occasionally meeting the camera. Fabric of
her outfit moves naturally with each step and turn. The routine follows
the pacing and structure established in <Video 1> — building energy
through the middle of the clip before settling. The ending pose returns
close to the opening stance so the clip can loop cleanly for repeated
live playback.

overall_soundscape:
Soft ambient room tone under the music, with faint fabric rustle as
<Subject 1> moves and rhythmic footfall on the studio floor.

non_diegetic_music:
An upbeat track carries the routine; its tempo, instrumentation, and
dynamics are reused from <Audio 1>, driving the pacing of her movement
throughout.

填入示例(仅示意,非真实素材):{{appearanceDescriptor}} = "shoulder-length wavy black hair, a fitted red qipao with gold trim, and a slender, graceful build";{{motionDescriptor}} = "a lively Latin-inspired routine with hip sways and raised-arm turns"。

已知未过机械验收的地方(对应需求文档 8 节第 9 条,正式接入前需要 按 docs/h3skill.md §1.7 的 22 项清单逐条核实,这里不假装已经过审): detailed_description 的英文词数需要卡在 350–500 词区间(H6)——上面 这版是手写的示例长度,没有做逐词计数;retention_analysis 用的四个 取值(fully_preserved/weak_reference/fully_copy)都在 H9 白名单 内,但整体六段的五处标签同义(H14)等细节建议正式接入前再核一遍。


V — View:前后端界面设计

V.1 观众端页面

页面 路径(建议) 说明
换装跳舞直播间 dance.html 主页面,见 V.1.1
登录/注册 弹窗(不单独开页,跟 v1 昵称弹窗交互一致,见架构文档/docs/done 2.5 节) 邮箱输入 + 验证码/密码,首次触发付费操作时弹出
我的作品 my-works.html 或 dance.html?tab=mine(建议做成 dance.html 内的一个面板而不是独立页面,减少一个页面壳) 7.4 节
充值 弹窗,from 积分不足拦截 或 顶部"我的积分"入口 7.3 节,具体支付渠道待定

V.1.1 dance.html 区域划分(复用 live.html 视觉语言,见需求文档 2 节)

┌─────────────────────────────────────────────┐
│ 顶部条:Logo | 在线人数 | 我的积分 | 头像/登录 │
├───────────┬───────────────────┬─────────────┤
│           │                   │             │
│  左侧栏    │   播放器(9:16)   │  右侧栏      │
│ 衣柜/传衣 │   + 当前播放信息   │ 在线互动展示 │
│ /传人 tab │   (复用 live.html│ (点赞/排队 │
│           │   的 now-playing)│  列表,无输 │
│           │                   │  入框)      │
│           │                   │             │
├───────────┴───────────────────┴─────────────┤
│ 移动端:底部 tab 切换(衣柜/传衣/传人/我的) │
└─────────────────────────────────────────────┘
  • 播放器容器按 9:16 设计(4.4 节),不是 live.html 现有横向容器的简单 拉伸。
  • 左侧栏三个 tab:衣柜(默认)/ 传衣服 / 传人,对应需求文档 3 节三种模式。
  • 首次进入弹年龄确认(5.1 节),非模态强制,一次性记忆(cookie/账号)。

V.2 后台管理页面

在现有 admin.html(docs/done 2.8 节)基础上新增,交互风格保持一致 (表格 + 行内编辑 + 新增表单,见需求文档 6 节开篇):

页面 对应资源 需求文档章节
admin-characters.html M.3 6.1
admin-garments.html M.4 6.2
admin-dance-refs.html M.5 6.3
admin.html(扩展现有表格新增列) M.7 6.4
admin-playback.html M.8(dance 频道排播干预) 6.5
admin-users.html M.1 + M.2 用户/积分管理,7 节

后台导航建议在现有 admin.html 顶部加一排二级导航链到这些新页面, 不新起一套独立的后台框架。

V.3 后端 API 清单

延续 server.js 手写路由风格(无框架),按资源分组:

观众端:
GET  /api/dance/library?sort=              # dance 频道浏览三 tab,等价 v1 /api/library
GET  /api/dance/live/state?cid=&uid=        # dance 频道播出状态,等价 v1 /api/live/state
GET  /api/dance/wardrobe                    # 衣柜列表(garments,isActive=true)
POST /api/dance/pick                        # 模式一:{characterId?, garmentId} 免费提交
POST /api/dance/upload-garment              # 模式二:multipart 图片 + 走审核+扣积分
POST /api/dance/upload-character             # 模式三:multipart 图片 + 年龄确认+黑名单审核+积分档位(决定 remainingSegments)
POST /api/dance/queue/vote/:id              # 免费队列投票,等价 v1 /api/queue/vote
GET  /api/dance/my-works                    # 我的作品(需登录)
POST /api/auth/register                     # 邮箱注册
POST /api/auth/login
POST /api/credit/topup                      # 发起充值(对接支付网关,7.3 节)
POST /api/credit/topup/webhook              # 支付回调

后台:
CRUD /api/admin/characters[/:id]
CRUD /api/admin/garments[/:id]
CRUD /api/admin/dance-refs[/:id]
CRUD /api/admin/generated-videos[/:id]      # 扩展现有 /api/admin/library
POST /api/admin/playback/insert             # 插播/置顶
POST /api/admin/playback/skip               # 跳过当前
POST /api/admin/playback/pause-fill         # 暂停自动填充
POST /api/admin/blacklist                   # 拉黑用户/资产
GET  /api/admin/moderation-log
GET  /api/admin/users
POST /api/admin/credit/adjust               # 人工调整积分(客服场景)

内部(生成流水线编排,不对前端暴露):
generateComposedImage(characterId, garmentId)      # Stage1,查缓存(M.6唯一索引)→未命中调fal.ai
captionComposedImage(composedImageId)              # Stage1完成后自动打标,写 appearanceDescriptor(M.11)
generateDanceVideo(composedImageId, refDanceVideoId, backend)  # Stage2,按 M.11 模板拼 prompt,backend按4.3节路由

C — Control:界面按钮/交互动作设计

C.1 dance.html

按钮/交互 触发条件 动作 反馈
衣柜卡片点击 始终可点(免费,无需登录) POST /api/dance/pick {garmentId} 立即在"生成中"区出现一条;命中缓存(4.6节)秒级进"接下来播放"
"传衣服"上传按钮 需登录 若未登录先弹登录;选图 → 客户端基础校验(大小/格式)→ 上传 → 展示预计消耗积分 → 二次确认 提交后进图片审核队列;通过后自动排入生成,展示状态
"传人"上传按钮 需登录 + 已完成年龄确认(5.1节) 选图 → 选择/展示积分档位(决定 remainingSegments,7.2节)→ 可选搭配衣服(选衣柜或再传一张,不选则随机)→ 二次确认扣积分 提交后走黑名单自动审核(5节),通过直接生成,不阻塞用户等待
年龄确认弹窗"确认"按钮 首次进入 dance.html 写 ageConfirmed=true(cookie 或账号,取决于是否已登录) 弹窗关闭,露出主界面
点赞(❤️) 浏览三 tab 内 POST /api/like/:id(复用 v1) 数字 +1
排队投票(▲) 免费队列条目 POST /api/dance/queue/vote/:id(复用 v1 投票逻辑,仅对 priority: normal 条目生效——paid_boost 条目不展示投票按钮,见需求文档 3 节"共同后置流程") 高亮 + 票数更新
"我的作品"入口 需登录 打开 V.1 的我的作品面板 列出该账号名下 generated_videos(含 status: expired 的人物产出)
"我的积分"/充值入口 始终可见(未登录显示"登录后查看") 打开充值弹窗 对接支付网关(7.3节,渠道待定)
静音/全屏 复用 live.html 现有 muteBtn/播放器交互 同 v1 同 v1

C.2 后台管理页面

按钮/交互 所在页面 动作
新增/编辑/删除 人物、衣服、参考视频 各自 admin 页 对应 CRUD API(V.3),风格照抄现有 admin.html 行内编辑
"设为直播默认人物" 开关 admin-characters.html 置该条 isDefault=true,同时把其他所有条目置 false(第一期全局唯一,6.1节)
审核通过/驳回(pending→approved/rejected) admin-garments.html(user_paid 来源条目) 更新 moderationStatus,写 moderation_log
人工下架人物/内容 admin-characters.html/admin-generated-videos 5节兜底手段,写 moderation_log(verdict: admin_takedown)
插播/置顶下一条 admin-playback.html POST /api/admin/playback/insert,写入 M.8 priorityInbox
跳过当前 admin-playback.html POST /api/admin/playback/skip
暂停/恢复自动填充 admin-playback.html POST /api/admin/playback/pause-fill,暂停期间 ensureSchedule 只消费 priorityInbox/freeQueue,不再随机填充素材库
拉黑用户/资产 admin-playback.html 或 admin-users.html 写黑名单表,后续该用户/资产提交直接拒绝,不进流水线
人工调整积分 admin-users.html POST /api/admin/credit/adjust,写 credit_ledger(reason: admin_adjust)

P — Process:用户流程设计

P.1 匿名免费观众:选衣柜(对应需求文档 3 节模式一)

sequenceDiagram
  participant V as 观众(未登录)
  participant S as server.js
  participant Cache as composed_images 缓存(M.6)
  participant Fal as fal.ai
  participant H3 as H3 Console

  V->>S: 首次进入 dance.html
  S-->>V: 弹年龄确认(5.1节)
  V->>S: 确认已满18岁
  V->>S: POST /api/dance/pick {garmentId}
  S->>Cache: 查 (defaultCharacterId, garmentId)
  alt 命中缓存
    S-->>V: 直接排入队列(秒级)
  else 未命中
    S->>Fal: Stage1 换装合成
    Fal-->>S: composedImageUrl
    S->>Fal: captionComposedImage 自动打标(M.11,生成 appearanceDescriptor)
    Fal-->>S: 2-3 条外观特征文字
    S->>S: 按 M.11 模板拼装 Stage2 prompt
    S->>H3: Stage2(冷启动算力,4.3节)
    H3-->>S: 视频完成
    S->>S: 写入 generated_videos + composed_images 缓存
    S-->>V: 排入队列
  end
  Note over S: ensureSchedule 按 v1 投票逻辑排序(priority: normal)

P.2 注册观众:付费传衣服(模式二)

  1. 点"传衣服" → 未登录则先走 P.4 登录/注册。
  2. 选图 → 前端展示"这将消耗 N 积分"(数值待定,8节)。
  3. 确认 → 后端校验余额 → 不足则拦截,引导充值(P.4 充值流程)。
  4. 余额充足 → 预扣积分(credit_ledger 写一条负数流水)→ 图片走轻量 内容审核。
  5. 审核不过 → 全额退还积分(写正数流水,reason: refund_moderation_reject) → 前端提示。
  6. 审核通过 → garments 新建一条 moderationStatus: approved,默认 isActive: true(沉淀进公共库)→ 走 Stage1/Stage2(可能命中已有 "默认人物+这件新衣服"缓存吗?不会命中,因为这件衣服刚创建,Stage1 必然是新生成)→ 完成后排入队列,priority: normal(模式二不享受 插队特权,只有模式三新人物才有,见需求文档 3 节)。
  7. 生成失败(Stage1/Stage2)→ 退还积分,garments 该条标记不可用/删除 (避免衣柜库里出现一件"存在但没有可用换装产物"的死资产)。

P.3 注册观众:付费传人物(模式三,风险最高的流程)

sequenceDiagram
  participant V as 观众(已登录,已年龄确认)
  participant S as server.js
  participant Blk as 人脸黑名单模型
  participant Fal as fal.ai
  participant Credit as credit_ledger

  V->>S: 选积分档位(决定 remainingSegments)+ 上传人物照 + (可选)选/传衣服
  S->>Credit: 预扣积分
  S->>Blk: 自动人脸识别过滤(5节,非强制人工预审)
  alt 命中黑名单
    S->>Credit: 全额退还
    S-->>V: 拒绝,提示原因
  else 未命中,自动通过
    S->>S: characters 新建一条 source:user_paid, remainingSegments=购买档位对应值
    S->>Fal: Stage1 换装合成(若未指定衣服则随机挑一件衣柜库)
    S->>Fal: Stage2(付费实时算力,4.3节,约4s级)
    Fal-->>S: 视频完成
    S->>S: generated_videos 新建,priority: paid_boost
    S-->>V: 排入 priorityInbox,插队播放(不参与投票)
  end
  Note over S: 每播完一段,remainingSegments -= 1
  Note over S: 配额耗尽 → characters.status = expired,从排播/复用池移除<br/>但记录保留,用户可在"我的作品"回看,可再充值续播

P.4 登录/注册 + 身份迁移

  1. 触发点:模式二/三的任一付费操作、或主动点"登录"。
  2. 邮箱注册/登录(7.1节)成功后,检查是否存在 viewer_uid/ viewer_nickname cookie(v1 遗留身份)——若存在,把该 uid 写入 新账号的 legacyUid 字段,历史投票/点播记录(挂在旧 uid 上的) 通过 legacyUid 关联查询,不做数据搬迁,只做关联(架构文档 2.7 节过渡方案)。
  3. 后续 uid 仍然写在 cookie 里(免费投票等匿名场景继续用它),但 付费操作一律要求 userId(登录态)。

P.5 充值

  1. 触发点:付费操作余额不足自动弹出,或主动点"我的积分"。
  2. 选充值档位 → 跳转/弹出支付网关(7.3节,渠道待定,标注 Stripe 对 国内支付方式支持有限的风险,见架构文档待验证表)。
  3. 支付成功回调 POST /api/credit/topup/webhook → 写 credit_ledger (reason: topup, delta: +N, paymentRef) → 更新 users.creditBalance。
  4. 支付失败/取消 → 不产生流水,前端提示重试。

P.6 运营/管理员:素材维护 + 事后审核 + 播放干预

  • 日常巡查(对接 5 节"事后人工兜底"):定期查看 moderation_log 里 verdict: auto_pass 但被举报/人工发现有问题的人物内容 → 在 admin-characters.html 手工下架 → 写 admin_takedown 记录。
  • 播放干预:直播过程中运营通过 admin-playback.html 插播/跳过/ 暂停自动填充(6.5节),不需要走观众端的正常提交流程。
  • 素材库维护:定期给 garments/dance_refs 上下架,给 admin_seed 人物/衣服打标签分类。

P.7 系统自动化流程

  1. 冷启动批量生成(第一期,9节):运营在后台批量选定 人物×衣服组合,脚本/后台按钮触发批量 generateComposedImage + generateDanceVideo(走内部 H3 Console,4.3节),铺满初始衣柜库/ composed_images 缓存,不涉及观众端。
  2. 排播 tick:dance.html 独立的 ensureSchedule 定时任务(同 v1 每 2s,架构文档 1.3/2.6节),优先消费 priorityInbox(付费插队), 其次按投票消费 freeQueue,都为空时随机填充素材库(同 v1 逻辑, 避开冷却期)。
  3. 人物到期检测:每次消费完 priorityInbox 里某人物的一段后, remainingSegments -= 1,归零则置 characters.status = expired 并从后续排播候选中过滤掉(架构文档 2.7节)。