【WIP】feat: UNO Flip 模式

[DoyoDia]

以独立游戏模式（gameMode: 'classic' | 'flip'）实现 UNO Flip。规则基线核对自 Mattel 官方说明书 GDR44，设计文档见 docs/uno-flip-mode-design.md。

为什么不是村规

村规插件的能力边界是 GameState → GameState，只能改变动作处理流程；而 UNO Flip 改变的是数据模型本身——双面牌、8 种颜色、6 种新卡型、对手可见手牌背面、独立计分表。

官方规则里三个容易搞错的点

• 两面都没有 0 牌（1–9 各两张，18 张/色）→ 村规「0 牌交换手牌」在 Flip 下必须禁用
• 亮面没有带色 +2：带色罚摸牌是 +1，+2 是万能牌，两个不同卡型
• Flip 卡整体反转弃牌堆：新顶牌是本轮第一张弃牌，不是刚打出的 Flip 卡

质疑罚则也不同：Flip 是 2/4，经典是 4/6；wild 在 Flip 计 40 分而非 50。

核心架构决策

双面牌采用「当前活动面 + back」而非 { id, light, dark }：

• 现有 187 处 card.type / card.color 读取点零改动，canPlayCard / 计分 / 机器人估值自动作用于活动面
• classic 模式 back === undefined，零成本，既有行为逐位不变
• 官方「按结束时所在面计分」天然满足
• 代价（deckHash 稳定性、翻面一致性）用双面归一化身份 + 单一 flipAll 入口 + 不变量测试解决

牌组配对固定（来自实物牌组记录，已交叉校验与官方配比逐项吻合）。这不是细节：配对固定意味着可以从对手手牌背面反推其正面持牌，是本模式的核心博弈层。

可见性

PlayerView 新增 handBacks：对手手牌背面对所有人可见，本人手牌一律剥离 back——官方规则下你看不到自己手牌的背面。批量广播路径也做了剔除。有专门的测试守着这条。

机器人

新卡型估值 + 翻面时机判断；从对手背面反推持牌按难度分级开放（novice/easy 不用、normal 只看颜色、hard 完整反推）。

公平性守卫测试：构造两个只有「机器人自己手牌背面」不同的局面，断言所有评分因子完全一致。这条守卫用「故意注入作弊代码 → 测试变红 → 移除 → 变绿」验证过有效。

村规

11 条 Flip 专属村规。经典与 Flip 的叠加/挡罚共用一套谓词（stack-rules.ts），两个既有插件按模式自动分派，经典语义有回归测试锁定。预设按模式分派，切换模式时归一化村规（服务端权威校验）。

顺带修复的既有缺陷（与 Flip 无关）

新增的随机对局性质测试（3 机器人自动打完整局，断言每步动作都能被引擎接受）压出两个死锁，经典模式对照组同样复现，影响已发布的「派对」「疯狂」预设：

1. 「同数字全出」连出打光同数字牌后补 PASS → 轮次已推进，PASS 非法 → 机器人循环 break 且不重新调度 → 永久卡死
2. 「同数字全出」+「7 牌交换」：出 7 立刻进入选交换目标阶段，后续连出动作全部非法 → 同样卡死

另外修了：isFunctionCard 只认经典卡型导致「空手赢不算」对 Flip 罚摸牌失效；GameSession.create 不传 settings 时首牌可能是万能牌导致测试约 4% 偶发失败。

验证

shared 399 / server 129 / mcp 4 全部通过
构建：shared / server / client / admin / mcp 全绿
e2e：flip-demo 全程开着「疯狂」预设打完整局，28 条断言通过
     经典模式 smoke 无回归

packages/e2e/flip-demo.mjs（pnpm --filter @uno-online/e2e flip-demo）真开一局并断言可见性、双面模型、翻面、牌框、设置面板布局等。

不含发版

按仓库惯例发版是独立 PR，本 PR 不含版本号提升与 CHANGELOG。

已知未完成

• 移动端玩家列表未展示对手背面（空间受限，桌面端与罗盘已覆盖）
• Flip 卡面资源包只预留了索引段（100–153 / 200–253），尚无内置主题资源，Flip 卡型走内置矢量渲染

🤖 Generated with Claude Code