# 开发日志 · Dev Log

按时间 + 主题切的开发过程记录。每篇文档遵循同一结构：

> **做什么**（用户要求）→ **遇到什么问题** → **怎么解决**

## 索引

| # | 文档 | 主题 |
| --- | --- | --- |
| 01 | [初始需求与架构设计](./01-initial-scope-and-design.md) | TTS-like 桌游模拟器的目标、约束、决策 |
| 02 | [UI 原语 API 设计](./02-ui-primitives-api-design.md) | `<Board> <Zone> <Card> <Token> <ActionButton>` 接口规范 |
| 03 | [项目骨架搭建](./03-monorepo-scaffold.md) | pnpm workspace + Vite + Tauri 初始结构 |
| 04 | [UI 原语实现](./04-ui-primitive-impl.md) | Board/Zone/Card 联通 game.ui schema |
| 05 | [拖拽 + 落点判定](./05-drag-and-drop.md) | HTML5 drag-and-drop + 多选 + 验证 |
| 06 | [三个示例游戏](./06-three-games.md) | DragTest / War / Mill (九子棋) |
| 07 | [Bug 修复 · 第一轮](./07-bugfixes-round-1.md) | War 牌堆不可见、DragTest 桌→桌重复加卡 |
| 08 | [本地局域网联机](./08-local-lan-multiplayer.md) | tsx server + SocketIO + 2 客户端实测 |
| 09 | [房间列表 UI + 完整测试](./09-room-list-ui-and-complete-tests.md) | LobbyRoomList + E2E/unit/Docker 修复 |
| 10 | [部署后修复：LAN CORS + join 409](./10-cors-and-join-bugs.md) | CORS 覆盖 LAN、joinRoom refresh、tie 容忍测试 |
| 11 | [用户测试反馈 · 第一轮](./11-user-test-feedback-round-1.md) | connecting 卡死、UI 重复入口、无法自检、防误删缺失 |
| 12 | [统一端口 + 玩家命名系统](./12-unified-port-and-player-names.md) | /api 前缀、vite proxy、静态 serve、名字显示/改名 |
| 13 | [德州扑克（Holdem）游戏](./13-holdem-game.md) | 引擎 + 评估器 + 牌桌 UI + 可变人数大厅 + E2E |
| 14 | [双升游戏 + 单端口启动/部署](./14-double-up-game.md) | DoubleUp 引擎+UI+联机、start.sh(PORT=5173)、玩家名 server 权威、固定人数大厅 |
| — | [踩坑总结](./lessons-learned.md) | 所有踩过的坑（按现象分类） |
| — | [决策记录](./decisions.md) | 已锁定决策 + 日期 |

## 仓库结构

```
docs/
├── dev-log/                  ← 本目录
│   ├── README.md
│   ├── 01-initial-scope-and-design.md
│   ├── 02-ui-primitives-api-design.md
│   ├── 03-monorepo-scaffold.md
│   ├── 04-ui-primitive-impl.md
│   ├── 05-drag-and-drop.md
│   ├── 06-three-games.md
│   ├── 07-bugfixes-round-1.md
│   ├── 08-local-lan-multiplayer.md
│   ├── 09-room-list-ui-and-complete-tests.md
│   ├── 10-cors-and-join-bugs.md
│   ├── 11-user-test-feedback-round-1.md
│   ├── 12-unified-port-and-player-names.md
│   ├── 13-holdem-game.md
│   ├── 14-double-up-game.md
│   ├── lessons-learned.md
│   └── decisions.md
├── impl.md                   整体实现规划（高层）
└── ui-primitives.md          UI 原语 API 详细规范
```

## 进度总览

- **架构 + 骨架**：✅ 完成
- **本地 2D MVP**（拖拽 + 3 个游戏）：✅ 完成
- **联机**：✅ Phase 2（创建房间 + 房间列表 + E2E/unit 覆盖）
- **游戏生态**：✅ Holdem（德州扑克，2-9 人，含隐藏信息 + 边池）；✅ DoubleUp（双升，固定 4 人，拖拉机/甩牌/抠底）
- **桌面壳（Tauri）**：⏳ Phase 4（待启动）
- **脚本化层（玩家自写游戏）**：⏳ Phase 3（待启动）