# 01 · 初始需求与架构设计

## 做什么

用户要求做一个 **类似 Tabletop Simulator 的桌游模拟器**，核心要求：

| 维度 | 要求 |
| --- | --- |
| 玩法定义 | 用户可编写代码（类似 TTS 的 Mod，但用 JS/TS） |
| 内容 | 自带牌类、棋类、token 等基本元素 |
| 联机 | 通过用户已有的公共域名服务器做中转 |
| 平台 | 跨平台（类 reVC 的"自编译分发"模型） |
| 视觉 | 2D 简洁界面，重规则不重特效 |
| 技术栈 | Node / Web 即可 |

## 遇到什么问题

1. **范围模糊**：TTS 是 3D 物理模拟 + 大量商业功能。要做"轻量级 TTS-like"，边界在哪？
2. **技术栈选择**：跨平台的方式有 Web / Electron / Tauri / 纯原生。各自优劣？
3. **规则引擎**：自己写还是用 boardgame.io？后者是本仓库的现成引擎。
4. **决策锁定**：技术栈不确定会让所有后续工作悬空。

## 怎么解决

### 锁定 3 个核心决策

1. **规则引擎**：用 boardgame.io（本仓库的源码）。理由：已实现 reducer / phases / plugins / MCTS / server，省下 1-2 个月造轮子。
2. **桌面壳**：Tauri。理由：包小（~5MB vs Electron ~100MB）、原生、Rust 内核、跨平台自编译友好。
3. **游戏定义格式**：沿用 boardgame.io `Game` + 自定义 `ui` 字段。理由：示例代码可直接复用。

### 锁定其他设计选择

- **资产格式**：SVG 内嵌字符串优先（轻量、可访问、可在 React 里直接渲染）
- **网络**：复用 boardgame.io master 的 socket.io 协议（不发明新协议）
- **服务器**：用户公共域名上跑 boardgame.io Server
- **跨平台**：Web 一份搞定浏览器访问；Tauri 壳装成桌面 app

### 整体架构（四层分离）

```
┌─────────────────────────────────────┐
│ UI Layer（SVG + React）              │
├─────────────────────────────────────┤
│ Game Definition（用户写的 TS/JS）     │
├─────────────────────────────────────┤
│ Rules Engine（boardgame.io core）    │
├─────────────────────────────────────┤
│ Network Layer（Socket.IO 中转）       │
└─────────────────────────────────────┘
```

### 实施分 5 阶段

- **P1**：本地 2D MVP（先做 War 验证链路）
- **P2**：联机（部署 server + 房间管理）
- **P3**：游戏生态（热重载 + 文档）
- **P4**：Tauri 打包

## 成果

- 详细规划落地为 `docs/impl.md`（17 KB，403 行）
- 3 项决策已固化在 `docs/dev-log/decisions.md`

## 关联

- [02-ui-primitives-api-design.md](./02-ui-primitives-api-design.md) — 下一步：UI 原语 API 设计
- [decisions.md](./decisions.md) — 决策详细记录