0.4.2

好友德州 v0.4.2

服务端与客户端都需要更新，并且必须先执行数据库迁移。

发布方式

本 Release 不会直接附带 Web、Windows、Android、HarmonyOS 或 iOS 安装包，仅发布 Git 标签对应的源码快照。

客户端需要写入自建游戏服务地址，语音需要部署者自己的腾讯云 TRTC 配置，Android 与 HarmonyOS 正式分发还涉及各自的平台签名，因此各平台产物应由部署者根据自己的环境构建、签名和测试。

从空服务器开始部署，请参阅自建部署指南。已有部署的版本升级流程请参阅生产环境更新手册。

升级须知

• 必须先迁移再启动服务：本次新增迁移 000010_spectators，为 rooms 增加观战位设置四列，为 room_members 增加 spectating，座位号允许为 0，座位唯一约束改为只对真实座位生效。服务端启动时会校验迁移版本，未迁移会拒绝启动。
• 服务端与客户端必须一起更新：本版新增了 WebSocket 命令（table.spectate.enter、table.seat.take、table.spectator.settings.set）与快照字段（spectators、spectatorSettings、spectatorFee、spectatorFees、spectating、座位上的 holeCards 与 pendingSpectate）。
• Web 端部署者请检查反向代理：如果 nginx 层自行处理 CORS，Access-Control-Allow-Headers 必须包含 X-Client-Version，且 OPTIONS 预检要放行；否则 Web 端会显示「无法连接游戏服务」。服务端自带的 CORS 已修复。
• 版本门槛请在所有人装好 0.4.2 之后再设为 4002。0.4.1 及更早的客户端不给语音凭证请求带版本头，门槛一开语音就连不上（见下文）。已开启门槛的部署，在客户端更新完成前请先把门槛填回 0。
• 强烈建议在服务器上跑一遍真实 PostgreSQL 集成测试。本版改动了 room_members 的约束与索引，内存仓储的单元测试拦不住这类问题。更新手册的对应章节已重写：测试环境文件只需 TEST_DATABASE_URL 一个变量，指向单独的测试库；先只跑 Postgres 用例，再跑全量。

新增功能

观战位（OB）

房间成员可以不占座位地留在房间里观战，最多 10 人，与座位数无关。

• 切换：手间的准备区有「进入观战」，观战面板有「上桌」；手间立即生效，牌局进行中只记录意向、本手结算后应用。座位满时立即拒绝，不排队；上桌必须有筹码。
• 看牌费：观战者付费后能看到本手所有参与者的手牌。费用 = 房主设置的大盲倍数 × 大盲，默认 10 个大盲，可设 0～100，0 为免费。费用在全员准备完成、发牌之前收取，平分给即将参与本手的上桌玩家，余数从庄位起顺时针逐枚。余额不足的观战者本手不收费也不给看牌，补码后下一手恢复。
• 看牌权按手发放，免费模式也不例外：开局时在观战位的人才能看本手；手间进入看不到刚结束那手的盖牌，牌局中途进入看不到进行中的这手。
• 可见性：服务端按接收者裁剪，普通玩家的快照里永远没有别人的手牌。
• 权限：房主可在「房间管理」里分别关闭观战者的语音、文字与赞赏/嘲讽，默认全部允许，服务端校验。语音的实际推流在客户端，服务端只能拒绝状态广播，由客户端配合关麦。
• 其他：观战者可补码、不能准备、不能换座、不能私下申请看牌、不能成为表情目标；房主可随时移出观战者（包括牌局进行中）；右上角「X/N（OB: Y）」点开房间名单；观战者不画在牌桌上。

收费放在发牌前是因为引擎在 StartHand 里记下每人的起始筹码作为结算守恒校验的基线，发牌后再加钱会让 Σ(结束 − 起始) ≠ 0。看牌费只在观战者与上桌玩家之间转移，牌桌筹码总量不变，持久化走与结算相同的事务与幂等保证。

牌桌调整

• 弃牌确认：轮到自己且可以过牌时点「弃牌」先弹窗确认；需要跟注时直接提交。弹窗期间若已超时轮到别人，确认也不会把弃牌打到别人的回合上。
• 赞赏/嘲讽气泡从玩家框底部向上飘，全程留在玩家框的竖向范围内；此前从框中心上方起飘，顶排座位的气泡一出现就在画布外被裁掉。
• 四色牌：黑桃黑、红桃红、方块蓝、梅花绿，公共牌与玩家框小牌同一套；玩家框小牌从 27×34、10 号字放大到 30×36、12 号字。试玩反馈小牌里黑桃与梅花分不清，靠颜色区分才是根本解法，尺寸受玩家框高度限制只能放大一档。
• 玩家框不再显示行动倒计时：轮到谁由高亮边框表示，倒计时只在公共牌区显示一处。

重要修复

Web 端无法连接游戏服务

v0.3.0 加 X-Client-Version 请求头后，服务端 CORS 的 Access-Control-Allow-Headers 没有声明它，浏览器预检失败，前端只看到一句笼统的连接失败；原生客户端不走 CORS，全都正常。现已放行，预检 OPTIONS 也绕过版本门禁。

开启版本门槛后语音提示「获取语音凭证失败」

客户端有两个 HTTP 客户端：所有接口走 GameApiClient 并带版本头，唯独语音凭证走独立的 TrtcCredentialClient，没带头。版本门禁包在整个服务外层，不带头的请求一律 426，客户端把任何非 200 都显示成凭证失败。这是 v0.3.0 的遗留问题，门槛首次开启才触发。0.4.2 补上请求头并增加断言测试。

观战位审查修复（0.4.1）

服务端：

• 0 筹码的观战者上桌会被持久化成「已入座却不在引擎里」，此后全桌人的准备、重连、快照全部失败。现在上桌必须有筹码，手结束时被看牌费掏空的人的上桌意向自动放弃。
• 免费模式此前只要在观战位就能看牌：输了的人手间进观战就能看到对手刚盖掉的牌再坐回去。改为看牌权同样只在开局时发放。
• Postgres 的满员计数把观战者算了进去，5 人上桌加 5 人观战就把新人挡在门外。
• 换座可能牵扯观战者：0 号位会匹配到第一个观战者，交换后写库撞约束。
• 看牌费幂等键在运行时第一手不再用空串，避免重启后账本静默漏记。
• 房主可在牌局进行中移出观战者；唯一没准备的人进观战后，其余人已全准备时立即开局。

客户端：

• 观战者点「补码」此前静默无效（页面只在座位里找自己）。
• 房间管理的移出列表此前不含观战者。
• 付费后看别人的座位被整个换成「本人座位」样式，昵称、断线、全下全没了；改为只翻牌，其他信息照旧。
• 「本手看不到牌」被当成「筹码不足」：看牌权是开局时发放的，手间与中途进入的观战者 canSeeHoleCards 必然为 false。快照新增 spectatorFee，只有筹码真的低于看牌费才提示补码。
• 看牌费输入框改用平台数字面板（HarmonyOS 横屏约定）；观战者点座位不再弹换位申请；同一错误连续出现按序号提示；房主设置未连接时不假装成功；头部与名单分母用房间最大人数；补齐错误码文案；屏蔽列表里观战者显示昵称。

只在真实 Postgres 上跑的两条用例

迁移升降级用例写死了 6 个版本，自 000007 起就已过期；改为以嵌入目录的版本数为准。集成测试里的「2 人房」并不存在（创建时会强制 10 人），满员判断从未被触发；改为直接把库里的 max_players 改成 2 再验证。两处都是测试本身的问题。

断线重连用例的竞态

TestWebSocketReconnectRestoresCurrentHandAndPrivateCards 在关掉客人的连接后只读房主连接上的下一条快照就断言客人已断线；房主连接上可能还排着开局前后的几条快照，断线通知在它们之后，CI 的慢机器上会随机撞上旧快照而误判。改为一直读到「客人显示为断线」为止。服务端逻辑没有问题，也没有改动。

测试

服务端新增约 40 项观战用例，覆盖房间、牌桌管理、传输三层：费用平分与守恒（含真实账本）、按手计费、中途切换、离开与断线、自动准备、权限与范围、0 筹码上桌、免费模式不漏牌、换座隔离、牌局中移出观战者、进观战触发开局。客户端新增约 30 项：观战面板三态、名单、设置、拦截、弃牌确认、气泡轨迹、补码筹码来源、错误序号、语音凭证版本头。Postgres 集成测试新增观战者持久化、两名观战者共用 0 号位、观战设置往返、满员只数上桌。

已知限制

• 仍是单游戏服务实例，进程异常时该实例上进行中的那一手会作废。
• 观战者的语音限制只能由客户端配合执行；改过的客户端可以绕过。
• 牌局进行中没有「进入观战」入口（需求定义在准备区），服务端支持的中途意向目前只会由「上桌」产生。
• 看牌费流程、名单、鸿蒙数字面板尚未在真机完整验证；HarmonyOS 原生代码无法在本机编译。
• iOS 不在验收范围。