huajishe-tts/docs/texas/04-allin-hand-comparison.md

问题 4：all-in 与比牌归属权（side-pot 分配）问题

现象（用户反馈）

“德州扑克有 all in 问题和牌判断大小问题，归属权不行。”

拆成两件事：

1. all-in 相关的归属权：多个玩家不同筹码 all-in 时，边池（side pot）赢家归属不对 / 钱分错。
2. 比牌判断大小：比牌（evaluate / compare）结果不对，或平局分池（奇数筹码）归属不对。

现状分析（基于 holdem.ts + holdem-eval.ts 精读）

4.1 牌型评估器（holdem-eval.ts）—— 重点排查

• evaluate5：逐档判断（同花顺→四条→葫芦→同花→顺子→三条→两对→一对→高牌）， ranks 是降序用于同档比较，compareHands 先比 category 再逐位比 ranks。 未发现明显 bug：wheel(A-2-3-4-5) 在 straightHigh 里正确返回 5；同花只数 suit；葫芦/四条的 kicker 取降序正确。
• 需补的确定性单测（证明或证伪）：
  • 皇家同花顺 vs 同花顺、四条 vs 葫芦、葫芦 vs 同花、两对 kicker 次序、A 高 vs K 高；
  • 平局：完全相同的 7 张 → compareHands === 0（已在 holdem.test.ts 间接覆盖，需独立断言）。
  • A 既当高又当低：A-2-3-4-5 与 A-K-Q-J-T 应都识别为顺子且后者更大。

4.2 边池构建（buildPots，holdem.ts:293）—— 归属权核心

• 按 totalBetThisHand 的贡献层级切池；eligible = 该层 inHand && !folded 的贡献者。
• 逻辑基本正确（单测 3 人 all-in 100/300/300、未跟注返还 已通过）。
• 潜在问题点：
  • 空层 / 全弃层：winElig.length === 0 时把整层还给 contrib[0]（唯一贡献者）。这在“某层所有人弃牌、但有人更早 all-in 死钱”的极端情况下可能把钱退错人。 标准规则：若某一贡献层级上所有人都弃牌，该层金额应并入仍能摊牌的最大边池或退给未弃牌者。 现有实现退给 contrib[0]（该层第一贡献者）不够严谨。
  • 边池的赢家归属：resolveHand 对每个 pot 在 pot.eligible 里比牌定赢家（正确）。
  • 奇数筹码归属：orderFromButton 按“距按钮顺时针距离”排序，resolveHand 里 extra 从左往右 +1。 标准：奇数筹码给按钮左侧第一个赢家（顺时针）。当前 seatDistance(from=btn, pid) 定义是顺时针距离， orderFromButton 升序即“离按钮最近的顺时针赢家先拿”，与标准一致（已在 holdem.test.ts:493 验证）。

4.3 all-in 街道推进（roundComplete / advance）—— 已定位真实 bug

roundComplete 三个分支（holdem.ts:198）：

• list.length === 0 → true（正确）
• list.length === 1 → return G.players[list[0]].betThisRound >= G.currentBet;
• list.length >= 2 → 全部 acted && betThisRound === currentBet

问题在 list.length === 1 分支：它只看 betThisRound >= currentBet，完全忽略了 acted！ 若唯一可行动者已经跟平了当前注、但 acted === false（例如他 limp 后别人 all-in、街道尚未因级联结束）， 该分支会误判 roundComplete = true，提前结束本街，导致该玩家被跳过、轮不到他过牌/确认。

已用确定性单测复现（见 holdem-probe.test.ts）：

stacks=[0,0,500], bets=[100,100,100], totals=[100,100,100],
acted=[true,true,false], currentBet=100, dealerButton='0'
→ roundComplete 返回 true（错误），应为 false

而 acted=[true,true,true] 时返回 true（正确）。说明 bug 仅在“单可行动者 + 已 match 但未 acted”时触发。

这正是“归属权不行 / all-in 出问题”的根因之一：本应继续行动的人被跳过，边池在错误时机结算。

修复（holdem.ts）：

if (list.length === 1) {
  const p = G.players[list[0]!]!;
  const stillNeedsToAct = p.betThisRound < G.currentBet || G.acted[list[0]!] === false;
  return !stillNeedsToAct;
}

即：单可行动者仍“未完成（需跟注或尚未 acted）”时，不算 roundComplete。

拟采用方案

1. 修 roundComplete 的 list.length === 1 分支： 改为“该玩家是否还能行动（call 不为 0 且未 all-in）”，即：

   if (list.length === 1) {
     const p = G.players[list[0]];
     const canStillCall = p.betThisRound < G.currentBet; // 还有注要跟
     return !canStillCall;
   }
   

   这样只剩 1 人且面对未 match 的 all-in 注时，仍要等他 call/fold 才结束。

2. 加固 buildPots 的空层处理：

   • 若某层 winElig.length === 0 且存在其他仍有 inHand && !folded 的玩家， 该层金额应并入“下一个有赢家的边池”或按总贡献退还给未弃牌者。
   • 简化稳妥版：空层时，把金额加进主池的赢家集合（即所有未弃牌者摊牌），避免凭空退给某一个人。
   • 同时补单测覆盖“某层全弃牌”场景。

3. 扩充 holdem-eval 单测 + 加 compareHands 平局/大小断言，证明比牌正确； 若发现 bug 当场修。重点加：A-2-3-4-5 顺、同花顺>四条、两对踢脚次序、完全相同的手牌 compare===0。

4. resolveHand 平局/边池综合单测：构造 3 人不同 all-in + 平局，断言每个池的赢家与金额。

验证

• 新增单测覆盖：roundComplete 单可行动者面对大 all-in 注 → 返回 false； buildPots 空层；evaluate7 各类牌型大小；resolveHand 多池 + 平局资金守恒（总发出 = 总池）。
• 资金守恒断言：Σ stack + pot 在每手前后恒定（已有 holdem.test.ts:558，扩展）。
• 联机手测：3 人不同筹码 all-in → 摊牌后各池赢家与金额符合预期。