huajishe-tts/docs/dev-log/decisions.md

决策记录 · Decisions

按时间倒序排列。所有决策已锁定，相关讨论不再重复。

---

2026-08-16

D1. 规则引擎：用 boardgame.io

决定：使用本仓库（boardgame.io）作为规则引擎，不自写 reducer。

理由：

• 已实现 reducer / phases / stages / plugins / MCTS / server
• 自写要 1-2 个月，boardgame.io 直接用
• 测试覆盖率高、文档完善

D2. 桌面壳：Tauri

决定：选择 Tauri，不选 Electron 或仅 Web。

理由：

• 包小（~5MB vs Electron ~100MB）
• Rust 内核，跨平台自编译友好（macOS / Windows / Linux）
• 符合用户"reVC 式自编译分发"诉求

D3. 游戏定义格式：沿用 Game + 自定义 ui

决定：沿用 boardgame.io Game 定义 + 自定义 ui 字段，不另创 DSL。

理由：

• 50+ 示例游戏可直接复用
• 降低学习成本
• ui 字段是纯附加，不影响 reducer

D4. 项目位置：新建 sibling 仓库

决定：在 /home/e2hang/code/Projects/boardgame/tts-like/ 新建，boardgame.io 作为 npm 依赖。

理由：

• 职责清晰
• 可以独立发版
• 不会污染上游

D5. 第一个游戏做 War

决定：Phase 1.4 第一个游戏是 War（规则极简、单一按钮）。

理由：

• 规则简单，专注验证引擎 + 按钮 + UI 链路
• 与卡牌游戏惯例接近

D6. 资产格式：SVG 内嵌优先

决定：卡牌图主要以 SVG 字符串（inline），fallback DataURL/URL。

理由：

• 文件小（一张卡 1-5 KB）
• 可访问、可在 React 里直接渲染
• 可版本控制

D7. zone 坐标系统：固定像素 + Board 视口缩放

决定：zone 用绝对像素坐标，Board 缩放由 viewport 缩放控制。

D8. 动画策略：CSS transition 默认

决定：默认 CSS transition，游戏可关闭或覆盖。

D9. 可访问性：v1 仅鼠标

决定：v1 不实现键盘/屏幕阅读器支持。v2 加键盘，v3 加 a11y。

D10. 触屏/移动端：v1 仅桌面

决定：v1 假设桌面浏览器，触屏在 v2 单独评估。

D11. 多选 UI：仅 Shift+click

决定：v1 仅 Shift+click 多选，框选 v2。

D12. 牌堆数量显示：角标

决定：pile 上显示数量徽章（角标），来源 G.zones[zoneId].length。

---

2026-08-17

D13. War 拆 move：flip + collect

决定：把原 flip 拆成两个 move：flip（翻到 pile）+ collect（收给赢家）。

理由：

• 单 move 让 pile 永远空，玩家看不到"对比"
• 两 move 让 UX 清晰：先翻牌看，再确认收牌

D14. DragTest / War 都不设 zone owner

决定：2 人游戏中所有 zone 公开（owner 留空），双方都能看到。

理由：

• 卡牌游戏惯例：能看到对手牌堆的大小（虽然看不到牌面）
• 之前设 owner 导致对方 zone 完全隐藏，UX 不通

D15. War 加 turn: ActivePlayers.ALL

决定：在 War 加 turn: { activePlayers: ActivePlayers.ALL }，让两个玩家能随时调 flip/collect。

理由：

• War 本身不分回合（双方都"现在"行动）
• 不加 → SocketIO 拒绝 player 1 调 move（disallowed move: collect）

D16. 联机优先走本地 LAN，不上云

决定：Phase 2 在本地局域网联机，不部署到云。

理由：

• 用户没给云服务器访问权限
• 本地 LAN 验证机制本身已经足够
• Docker 镜像保留为 v2 部署素材

D17. App.tsx 加 Mode 切换（本地 / 联机）

决定：在 web App 顶部加 "本地" / "联机" 切换按钮，联机模式下显示可配置 server URL/room/player/secret。

理由：

• 测试时本地模式最方便
• 联机配置要持久化（localStorage），避免每次重输

D18. SocketIO URL 用 http:// 不是 ws://

决定：SocketIO 客户端配置 server: 'http://localhost:8000'，不是 ws://。 （已在 lessons-learned §23 记录）

---

2026-08-23

D19. 联机房间管理用 boardgame.io 内置 Lobby REST

决定：不做自定义 REST 端点，直接复用 boardgame.io Server 自带的 Lobby API（/games、/games/:name/create、/games/:name/:id/join 等）。

理由：

• Server 已经在 server.run() 时自动 mount 这些路由
• 客户端 SDK LobbyClient（boardgame.io/client）已经封装好 fetch
• 自加路由要管 CORS / 鉴权 / 协议，重复造轮子
• 改一个 game 列表要改的地方最少

D20. dev 默认 origins 用 RegExp 列表，不用 '*'

决定：parseOrigins() 默认返回 RegExp 列表（/^https?:\/\/localhost(:\d+)?$/ 等），不返回字符串 '*'。

理由：

• boardgame.io 的 isOriginAllowed 把字符串 '*' 当字面量匹配（lessons-learned §9.1）
• RegExp 才能表达"localhost 任意端口"
• 显式 RegExp 列表比 '*' 安全

生产环境：必须用具体 origin 列表或精确 RegExp，不能 '*'。

D21. credentials 不再硬编码 p0/p1

决定：联机模式下 OnlineConfig.credentials 由 LobbyClient.joinMatch 返回的 playerCredentials 写入，不再硬编码。

理由：

• dev-log 08 的 OnlineConfigBar 还能让用户手动输入 p0/p1，但那是 workaround
• boardgame.io 的 credentials 是 server 颁发的随机 token（默认 nanoid(11)），不能用固定值
• 自动填充降低出错率
• OnlineConfig.credentials 空时 <OnlineGameView> 显示"请先创建或加入房间"提示，不挂载 Client

D22. War shuffle 接受注入的 random 参数（测试用）

决定：shuffle(arr) 改为 shuffle(arr, random = Math.random)，调用方仍是 Math.random 默认。

理由：

• 单元测试要确定性（lastWinner 不要随机）
• 注入 PRNG 比 monkey-patch Math.random 干净
• boardgame.io 的 seed 参数只影响 random.D6() 等内置 PRNG，不影响外部 Math.random

D23. War 平局时 collect 不清空 pile（修 bug）

决定：collect 在 lastWinner === 'tie' 时早 return，pile 不动（等下一轮 flip 触发"战争"）。

理由：

• 老代码无条件清 pile，但平局时牌没分配给任何玩家——2 张牌消失
• dev-log 07 D13 描述的就是"平局 → pile 留着"，但实现漏了
• 单测 p0Deck.length + p1Deck.length 期望 50 实际 52 时抓到的 bug

---

2026-08-23（LAN 部署后）

D24. dev 默认 origins 覆盖 LAN 网段

决定：parseOrigins() 默认 RegExp 列表显式覆盖 192.168.x.x / 10.x.x.x / 172.16-31.x.x / 100.x.x.x（Tailscale）。

理由：

• dev-log 09 的 RegExp ^https?://localhost(:\d+)?$ 只匹配 hostname localhost，不匹配 LAN IP → 用户从其他机器访问时 fetch 全 404
• boardgame.io 的 isOriginAllowed 函数把 RegExp 走 RegExp.test() 分支

生产：必须用 ALLOWED_ORIGINS 环境变量设具体 origin 列表（不要用 dev 默认）。

D25. LobbyRoomList joinRoom 成功后必须 refresh

决定：joinRoom 在成功（+失败）后调 await refresh()，让本地 rooms state 与 server 同步。

理由：

• 不刷 → 本地 list 残留旧 players[].name → "加入 P1" 按钮还显示着 → 重复点击 → 409
• 与 createRoom 保持行为一致（createRoom 早就 refresh）

D26. War E2E 容忍 tie（不强制 pile === 0）

决定：E2E 断言 expect(...).toHaveText(/^[01]$/) 而不是 '0'。

理由：

• dev-log 09 §问题 4 修了 tie 行为：collect 在 tie 时保留 pile 等下一轮
• 服务端 Math.random() 偶发 tie，E2E 用确定性断言会 flake
• 容忍 tie + 不改生产 server 是最简单做法

---

2026-08-24

D27. 统一端口（/api 前缀）

决定：页面和 API 都走单一端口。dev 用 vite proxy，prod 用 server static serve + /api mount。

理由：

• 不再需要两个端口，LAN 只需放行一个
• CORS 完全消失（同源请求）
• 生产只需一个 node dist/server.js 进程
• 见 dev-log 12

D28. 玩家命名系统

决定：joinMatch 传 playerName，大厅显示名字，游戏内用 POST /api/games/:name/:id/update 改名，名字持久化到 localStorage。

理由：

• "P0/P1" 对玩家不友好
• boardgame.io 自带 update 端点，改名成本低
• 为未来需要显示名字的游戏（德州扑克）打基础

D29. 静态 serve 用原生 fs 不用 koa-send

决定：静态文件 serve 用 node:fs/promises 手写，不引入 koa-send。

理由：

• pnpm add 被权限拦截
• 需求简单（SPA fallback + MIME 表），40 行内搞定
• 少一个依赖

---

2026-08-24（Holdem 游戏落地）

D30. 引擎层引入 HoldemView 类型供 UI 复用 helper

决定：新增 export type HoldemView = Omit<HoldemState, 'deck' | 'hands'>，把只读 helper（pids/host/seatedWithChips/nextSeat/canAct 等）签名从 HoldemState 放宽到 HoldemView。

理由：

• UI 拿到的是 playerView 剥过 secret 的 ViewG，缺 deck/hands，无法直接传给 HOLDEM_HELPERS.host(G)
• 强转 as HoldemState 绕过了类型安全，且掩盖了"该函数不该读 secret"的意图
• 结构类型让 HoldemState 和 ViewG 都自动满足 HoldemView，零运行时成本
• 保密约束在编译期可见：读 hands/deck 的函数（buildPots/resolveHand）保持 HoldemState 不变

D31. 大厅支持可变人数（2..9）+ setupData 表单

决定：LobbyRoomList 新增 maxSeats + setupOptions props，创建表单按 maxSeats > 2 显示座位选择器，加入按钮从硬编码 P0/P1 改为遍历 m.players 动态渲染。onSelect 回调加 numPlayers 参数。

理由：

• 既有 2 人游戏（War/Mill/DragTest）和 Holdem（2-9 人）共用大厅
• boardgame.io 的 createMatch 已支持 numPlayers + setupData，LobbyClient 只需透传
• OnlineConfig 加 numPlayers 让 Client({ numPlayers }) 在切房间时正确重建

D32. Holdem 本地模式做 9 座切换而非固定 P0

决定：HoldemLocalView 用下拉框切 P0..P8，key={seat} 重建 Client 触发 playerView 重算，而非像 CardLocalView 固定 playerID="0"。

理由：

• 德州扑克的 playerView 保密性是核心，单机调试要能切座位验证"别人看不到我的底牌"
• key 变化触发 React 重建，boardgame.io Client 重新订阅 playerID 的 view
• 比依赖 debug 面板切 playerID 更直观

---

待定（暂未锁定）

• 联机协议：暂定复用 boardgame.io master socket.io 协议（不加层）
• 房间管理：6 位短码 + 二维码分享
• 资产存储：本地 + 远程 CDN（v1 优先 DataURL）
• 游戏市场：v3 再说