0.2.1

好友德州 v0.2.1

v0.2.1 汇总了 v0.2.0 之后的全部改动：单实例生产保障（备份、CI、限流、指标、告警）、账号注销与隐私说明、管理审计查询、优雅停机、下注区重做、牌桌布局修复和发牌动画。

本次修复了三个只在特定人数或特定屏幕下才会出现的牌桌遮挡缺陷，其中两个此前被写错的测试掩盖着。已部署环境建议升级；服务端与客户端都需要更新，并且必须先执行数据库迁移。

发布方式

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

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

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

升级须知

• 必须先迁移再启动服务：本次新增迁移 000007_account_deletion，扩展了账本 reason 约束。服务端启动时会校验迁移版本，未迁移会拒绝启动。
• docker stop 必须给足宽限期：游戏服务现在会等所有牌桌打完当前手再退出（默认最多 120 秒）。请使用 docker stop -t 150 texas-game-server；Docker 默认只等 10 秒就强制杀进程，正在进行的那一手会作废。
• 服务端与客户端建议一起更新：只更新服务端不会出错，但账号注销与审计查询没有入口，加注档标签也仍显示旧文案。
• 新增可选环境变量 SHUTDOWN_DRAIN_TIMEOUT_SECONDS（默认 120）。不配置即使用默认值。

重要修复

玩家框遮挡：三个此前未被发现的缺陷

牌桌的座位/公共牌不重叠测试自己按「alignment × 半宽」另算了一份座位位置，而 Flutter Align 的真实语义是按 可用空隙 = 桌宽 - 框宽 插值。两者相差一个框宽，真实的玩家框比测试以为的更靠近中心，因此测试在"会不会压住公共牌"这件事上是偏松的。按真实语义复算后暴露出：

• 紧凑布局 4 人桌：侧边玩家框实际压进公共牌区 67 像素。
• 桌面端 3 人桌：桌面使用纯椭圆分布，会把斜角座位放在靠近中心处，同样压住公共牌区。现已与手机统一为沿桌沿的周边分布。
• 10 人桌玩家框互相遮挡：按角度投影的分布并不均匀，底边会挤下三个玩家框，相邻两框中心只差 159 像素而框宽 216，直接重叠 57 像素。现改为沿座位中心矩形的周长等距分布。

修复方式不是调整断言数字，而是由布局统一提供 seatRect，实现与测试共用同一套换算，杜绝两处各算各的。现在校验覆盖 8 种画布 × 2～10 人 × 三类检查：玩家框彼此不重叠、不遮挡公共牌区、不侵入聊天框与下注框，另加不被画布裁切。

玩家框位置与桌面空间

玩家框此前整个压在桌面之内，桌内被占的面积远大于桌外空白，中间的公共牌区和下注筹码反而局促。现在玩家框约 1/3 落在桌内、2/3 落在桌外的空白区。

修正过程中还发现：可见的绿色桌面比布局用的 tableRect 四周内缩 54/70 像素，早先按 tableRect 计算落位，结果玩家框整个悬在桌外还差 15 像素才碰到桌沿。现已统一以桌沿为基准。

加注档按钮标签与实际额度不符

底池远大于剩余筹码时，多个比例档会同时超过上限被压到最大加注额，但标签没有跟着改。界面上会出现一个写着「1/2 池」、实际却是你能加的最大额的按钮，旁边还有一个额度几乎相同的「全下」。

现在能全下时直接丢弃这些档位（服务端的 maxRaiseTo 就是全下额度向下取整的结果，两者相差不到一个小盲，全下已经覆盖）；不能全下时保留但改名为「最大加注」。

左上角房间信息与连接状态重叠

此前用固定偏移量猜测标题高度，标题实际更高时两行文字叠在一起。现改为同一列排布，间距由内容决定。

下注区重做

参考成熟线上平台的做法重做了下注区，交互全平台统一，摆放按屏幕分层。

• 固定三个大按钮：弃牌任何时候都合法；能过牌时第三个键是下注，不能过牌时是跟注加加注。全下不再单独占一个按钮。
• 额度与提交分成两步：预设档、滑块、直接输入都只改额度，按钮上的数字同步变化，再点按钮才提交。此前点预设档会立即下注。
• 全下靠把额度推到最右。这里有一处容易出错的细节：服务端的 maxRaiseTo 是向下取整到小盲倍数的，剩余筹码不是整数倍时它小于真实全下额度。若滑块右端取 maxRaiseTo 就永远滑不出全下，若把全下额度当作加注提交则会被服务端以 invalid_amount 拒绝。现在滑块右端是真实全下额度，且只有该点提交 all_in。
• 按钮配色：弃牌与跟注原先用低饱和深色，与面板底色对比不足，看起来像不可点击的禁用键。现在三个可用态都明显亮于底色，禁用态单独用一个低彩度暗色。

摆放：手机上下注区移到牌桌右侧竖排，牌桌下方腾出的空间让给玩家框和公共牌区，牌桌纵向增加约 10%。大屏改为左侧聊天、右侧竖排下注区，与手机位置一致，换端不需要重新适应。

画布宽度不足以同时容纳「聊天 + 牌桌 + 下注区」时，聊天自动改为弹窗，与手机一致。

发牌动画

所有发牌一律「逐张背面落桌 → 停顿 → 一起翻开」。

• 底牌：从小盲开始一张一张轮流发，本人的两张随后翻开，别人的牌背在翻牌阶段淡出，不常驻玩家框。
• 公共牌：翻牌 3 张逐张落下后一起翻开；转牌与河牌同理。
• 全下：服务端在全下后一次性发完剩余公共牌，客户端仍逐张演出。
• 发两次：第一块牌面同样有发牌演出；第二块牌面不再瞬间替换第一块，而是第一次的牌收起为顶部点数条、第二次的牌自上而下滑入并淡进。第一块牌面的展示时间也改为从它翻开之后才开始计。

演出期间禁用行动输入，避免玩家在牌还没翻开时就做决定。牌局进行中加入的待入座观战者不在发牌顺序里，不会闪出牌背。断线重连后拿到的第一份快照里牌已经在桌上，不会补一段发牌动画。

已知取舍：服务端的行动倒计时在演出期间不会暂停，因此翻前第一个行动的玩家会少约一秒决策时间。经权衡未在服务端引入补偿逻辑。

账号注销、隐私与审计

• 用户可自行注销账号：需输入当前密码确认，必须不在房间内；钱包中剩余的娱乐筹码整体转入创建时间最早的在用管理员，双方各记一条 account_deletion 流水且注明来源；注销后原用户名可以被重新注册；管理员不能自行注销，避免服务器失去管理入口。
• 隐私说明：注册页与个人信息页内置说明对话框，正文与 PRIVACY_NOTICE.md 同源。
• 管理审计查询：管理员可在客户端按类别、用户或房间查询管理操作、账号变更与语音进出记录。
• 语音加入/退出元数据：以审计事件持久化，含房间与离开原因，不含任何音频内容。
• 举报功能经评估后不做——熟人私人牌局的定位下，它解决不了实际问题。

生产保障

• 数据库备份与恢复：定时备份、归档校验、异地复制（腾讯云 COS）、恢复演练，以及针对备份脚本静默失败的巡检——这是最危险的情况，能在 36 小时内发现。
• 分层限流：登录/注册/刷新按 IP、密码错误按用户名、房间与钱包操作按用户、TRTC 凭证按用户、单 IP WebSocket 并发上限，配合 TRUSTED_PROXIES 可信代理解析。
• 可观测性：令牌保护的 /metrics，新增 texas_goroutines、texas_memory_heap_bytes、texas_process_start_time_seconds 与 texas_draining；账本对账定时任务；健康巡检与钉钉/企业微信告警。
• 24 小时稳定性观测脚本：判定协程泄漏、内存增长与静默重启，并在服务端指标改名时立即失败而不是静默记 0。
• 优雅停机：收到停止信号后停开新局、取消自动准备并广播原因，等所有牌桌打完当前手再退出。客户端凭 session.authenticated 的 serverInstanceId 识别服务端重启，并明确提示上一手作废。
• CI：服务端 gofmt/vet/test 与 -race、客户端 analyze/test、shellcheck 与仓库卫生检查。

工程与文档

• 牌桌页从 3180 行降至约 805 行，语音状态与自动行为判定抽成不接触 BuildContext 的控制器，此前无法测试的规则现在有了直接覆盖。
• 清理协议中五个从无发送点的常量，以及恒不命中的 revisionFromError。该分支比较的错误码与规则引擎实际产生的不一致，两个分支都返回 0。协议报文无变化。
• 文档按「什么时候需要读它」重新组织：六份历史阶段清单合并进开发历程后移除，产品与架构规划由 792 行精简至 226 行，只保留别处没有的决策背景。
• 新增 ADR-002：多实例与 Redis 暂不实施，并写明若要实施必须满足的约束与重新评估的触发条件。
• 新增 验收指南：24 小时稳定性观测、9 个弱网与断线场景、四端冒烟清单，附可直接填写的记录模板。

已知限制

• 仍是单游戏服务实例，进程异常时该实例上进行中的那一手会作废。
• 24 小时稳定性观测与弱网验收的工具和清单已就绪，但尚未实跑。
• 牌桌几何的自动化校验覆盖布局计算；子组件内容溢出（例如超长昵称）仍需真机冒烟。
• iOS 不在验收范围。