feat(结算): 实现血战麻将查叫与退税功能

新增局终处理逻辑,当牌墙耗尽且有多家未胡时:
1. 退税:未听牌玩家需退还此前杠分收入
2. 查叫:未听牌玩家向听牌玩家赔付最大理论点炮值
新增 SettlementType.TUI_SHUI 和 SettlementType.CHA_JIAO 结算类型
新增 ReadyHandOption 记录最优听牌选项

支持一炮多响裁决,新增 ResponseActionResolutionBatch 承载多赢家结果
在 GameSession 中新增 settlementHistory 保留结算记录供复用
更新开发文档要求加强关键区域的中文注释
This commit is contained in:
hujun
2026-03-20 15:05:00 +08:00
parent 34809fd0f3
commit b84d0e8980
11 changed files with 501 additions and 78 deletions

View File

@@ -29,12 +29,30 @@
- `明杠/点杠`:放杠者单独支付 2 分
- `补杠`:所有未胡玩家各支付 1 分
- `暗杠`:所有未胡玩家各支付 2 分
- `GameSession` 已新增 `PostGangContext`,只记录“杠后补摸到下一次自摸/弃牌裁决”这段窗口,用于判断 `杠上花/杠上炮`
- `GameSession` 已新增
- `PostGangContext`:只记录“杠后补摸到下一次自摸/弃牌裁决”这段窗口,用于判断 `杠上花/杠上炮`
- `settlementHistory`:记录已应用结算结果,供局终 `退税/查叫` 直接复用
- 海底相关不新增额外状态对象,直接复用“胡牌时牌墙已空”这一现有事实,保持 `KISS`
- 查叫/退税已接入局终处理:
- 触发时机:牌墙耗尽且仍有多家未胡时
- 处理顺序:先 `退税`,再 `查叫`
- `退税`:未听牌玩家若此前有杠分收入,需要按原支付关系逐笔退还
- `查叫`:未听牌玩家向仍在场且已听牌玩家,按对方理论最大可胡牌型的点炮赔分支付
- 已新增 `SettlementType.TUI_SHUI``SettlementType.CHA_JIAO`
- 已新增 `ReadyHandOption`,用于查叫时记录最优听牌目标牌与对应结算明细
- 一炮多响已接入响应裁决:
- `HU` 现在支持多赢家同窗裁决,只要响应窗口内有多个 `HU` 声明,就会一起结算
- `PENG/GANG` 仍保持单赢家,顺位规则不变
- 抢杠胡窗口也会复用这套多赢家 `HU` 裁决路径
- 已新增 `ResponseActionResolutionBatch` 承载多赢家响应结果
- `HuEvaluator` 已补 `七对` 胡牌判定,并暴露 `isSevenPairs` / `isPengPengHu` 给计分层复用。
- 当前仍未实现:
- 自摸加番/加底地方变体
- 天胡、地胡
- 查叫、退税、过水不胡、一炮多响
- 文档约定已`docs/DEVELOPMENT_PLAN.md`后续前端、后端、数据库表结构与 SQL 脚本都需要补充必要中文注释,重点说明复杂规则、关键字段、状态切换、约束原因和索引用途。
- 最小验证:`cd backend && mvn clean test`,当前 48 个测试通过。
- 过水不胡
- 文档约定已加强`docs/DEVELOPMENT_PLAN.md`
- 后端复杂规则、状态切换、结算口径和跨阶段流程,必须补适量中文注释
- 前端复杂交互、实时消息消费、动作面板联动和视图状态切换,必须补适量中文注释
- 数据库表结构、迁移脚本、初始化 SQL、索引和存储过程必须补中文注释说明业务含义、约束原因、字段口径和回滚要点
- 麻将规则判断、结算分摊、响应裁决、实时消息边界、局终处理、数据迁移与回滚脚本,默认视为中文注释必需区域
- 最小验证:`cd backend && mvn clean test`,当前 51 个测试通过。