桌游教学与多人联机平台

AI 驱动的现代化桌游平台，专注于桌游教学与联机对战

支持多人实时对战、本地同屏、交互式教学，提供完整的大厅、社交、创作工具与管理后台。

在线体验：easyboardgame.top

📑 目录

• ✨ 特性
• 🏗️ 技术栈
• 📦 项目结构
• 🚀 快速开始
• 🎮 添加新游戏
• 🐳 Docker 部署
• 🛠️ 常用命令
• 🧪 测试
• 📄 文档
• 🤝 贡献
• 📜 许可证
• 💖 赞助

✨ 特性

• 多人实时对战 — 基于自研游戏框架 + Socket.IO，功能有房间创建/加入/观战/重赛/日志/撤回，内置乐观更新引擎实现低延迟操作体验
• 丰富的游戏库 — 召唤之战 (Summoner Wars)、王权骰铸（Dice Throne / dicethrone / 王权）、Smash Up、井字棋等
• 本地同屏模式 — 同一设备上和朋友面对面对战
• 交互式教程 — 内置 Tutorial 引擎，支持 AI 自动演示和分步引导
• 社交系统 — 好友、聊天、对局邀请、战绩查看
• 游戏工具 — 预览特效与音频，快速切图等，音频来自购买的素材包
• 简易原型工具（搁置） — 可视化游戏原型构建器，快速验证规则想法
• 国际化 (i18n) — 中英双语支持
• 管理后台 — 用户管理、房间监控、反馈处理、系统健康检查
• Docker 一键部署 — 同域 / Cloudflare Pages 分离部署均可

🏗️ 技术栈

为什么选择前端

一者是最适宜 AI，能全自动完成和测试；二者是在不追求华丽表现的情况下游戏引擎对于桌游这类规则独特的游戏帮助不是很大；三者是完全不需要美术素材

前端：React 19 · TypeScript · Vite · Tailwind CSS · Framer Motion · Three.js · React Router · TanStack Query · i18next

后端：自研游戏引擎 (Koa + Socket.IO) · NestJS · MongoDB · Redis · Winston (日志系统)

基础设施：Docker · Docker Compose · GitHub Actions CI/CD · Cloudflare Pages / R2

📦 项目结构

├── src/
│   ├── games/           # 游戏实现（每个游戏一个目录）
│   ├── engine/          # 引擎层（Undo / Flow / Prompt / Tutorial / EventStream / Transport 等系统）
│   ├── components/      # UI 组件（大厅 / 对局 / 社交 / 管理后台）
│   ├── contexts/        # React Context（Auth / Audio / Social / Modal 等）
│   ├── services/        # Socket 服务（lobby / match / social）
│   ├── ugc/             # 简易原型构建工具与运行时
│   └── server/          # 服务端共享模块（DB / 存储 / 模型）
├── server/              # 服务端基础设施
│   ├── logger.ts        # Winston 日志系统
│   └── middleware/      # Koa 中间件（日志 / 错误处理）
├── logs/                # 日志文件目录（自动轮转）
├── apps/api/            # NestJS API 服务（认证 / 管理 / 社交）
├── server.ts            # 游戏服务器入口（Koa + GameTransportServer）
├── docker/              # Dockerfile 与 Nginx 配置
├── scripts/             # 构建 / 部署 / 资源处理脚本
├── docs/                # 项目文档
│   └── logging-system.md  # 日志系统文档
└── e2e/                 # Playwright 端到端测试

🚀 快速开始

前置要求

• Node.js >= 18
• Git
• Docker（可选，用于 MongoDB）

安装与启动

# 克隆仓库
git clone https://github.com/zhuanggenhua/BoardGame.git
cd BoardGame

# 安装依赖
npm install

# 复制环境变量模板
cp .env.example .env

Windows 用户：将 cp 替换为 copy。

方式一：使用 Docker（推荐，数据持久化）

npm run dev

方式二：无 Docker（纯内存模式，适合快速体验）

无需安装 Docker 和 MongoDB，对局数据存在内存中，重启后丢失。 该模式会自动跳过排行榜归档、UGC 动态注册等依赖 Mongo 的能力。

npm run dev:lite

启动后访问 http://localhost:5173 即可。

环境变量

开发环境只需复制 .env.example 即可运行，无需额外配置。核心变量：

变量	默认值	说明
VITE_DEV_PORT	5173	前端开发端口
GAME_SERVER_PORT	18000	游戏服务端口
API_SERVER_PORT	18001	API 服务端口
MONGO_URI	mongodb://localhost:27017/boardgame	数据库连接
JWT_SECRET	开发默认值	JWT 密钥（生产环境必须修改）

完整说明见 .env.example。

🎮 添加新游戏

项目内置了完整的 AI 辅助创建工作流，分 6 个阶段逐步完成（骨架 → 类型 → 领域逻辑 → 系统组装 → UI → 收尾）。

使用支持 Skill 的 AI 编辑器（或者直接扔文档），调用 .windsurf/skills/create-new-game 技能即可开始，AI 会引导你完成全部流程……大概。

数据录入使用的截图工具推荐pixpin

可以开新分支提pr，我会用ai审核

模型选择建议

• GPT：最听话最稳定，排查 bug 和审查代码的首选，就是太过啰嗦导致规划任务比较耗人脑，写的代码也不够整洁，慢是最大的缺点
• Claude：规划任务和进行决策都很出色，体感代码质量最好，但容易没有充分阅读项目就开始动手，所以还是需要 GPT 审查兜底。似乎有更高的正确性（有点不好形容，但claude的决策是需要人工干预最少的，有些让gpt死循环的问题也能给出正确答案）
• Gemini：前端唯一真神，识图能力强于 Claude，很适合通过规则 PDF 和卡图来生成数据（大部分情况需要手动截图不然也不准），但干其他活容易改一个出一个bug

个人的省钱组合：windsurf/warp + kiro 阉割版claude + 反重力

单开编辑器容易被限流，因为很多时候同时有十多条任务在跑 小tip：使用规范驱动开发，claude写完后gpt立刻审核一遍，每次提交再审核一遍应该能大幅减少ai错误

🐳 Docker 部署

本地验证

docker compose up -d
# 访问 http://localhost:3000

生产部署（推荐镜像部署）

服务器上只需 Docker，无需克隆仓库。脚本会自动下载 compose 文件、引导配置环境变量、拉取镜像并启动：

# 下载部署脚本并执行（首次部署会进入交互式配置向导）
curl -fsSL https://raw.githubusercontent.com/zhuanggenhua/BoardGame/main/scripts/deploy/deploy-image.sh -o deploy.sh
bash deploy.sh

# 后续更新
bash deploy.sh update

# 拉取慢时，先单独拉镜像再 update（避免 compose pull 并发抢带宽）
docker pull ghcr.io/zhuanggenhua/boardgame-game:latest
docker pull ghcr.io/zhuanggenhua/boardgame-web:latest
bash deploy.sh update

前置要求：服务器已安装 Docker 和 Docker Compose（docker compose 命令可用）。

详细部署文档见 docs/deploy.md。

🛠️ 常用命令

npm run dev                # 启动完整开发环境
npm run build              # 构建前端
npm run generate:manifests # 重新生成游戏清单
npm run generate:locales   # 生成卡牌多语言文件
npm run compress:images    # 压缩图片资源
npm run compress:audio     # 压缩音频资源（wav → ogg）
npm run assets:manifest    # 生成资源清单
npm run check:arch         # 架构检查

# 音频注册表 & 资源上传（新增/修改音频文件后必须执行）
node scripts/audio/generate_common_audio_registry.js  # 重新生成音频注册表
npm run assets:download  # 从 R2 下载资源到本地（合作者 clone 后首次运行）
npm run assets:upload    # 上传压缩资源到 R2（需配置 R2_* 环境变量）

git push --no-verify

注意：新增或修改音频文件后，需要依次执行 compress:audio → generate_common_audio_registry.js → assets:upload，否则远程 registry.json 缺少新 key 会导致音频无法播放。

🧪 测试

• Vitest 单元测试 — 游戏领域逻辑、引擎系统、API 服务等（2500+ 测试用例，99.4% 通过率）
• GameTestRunner — 游戏领域专用测试运行器，输入命令序列 → 执行 pipeline → 断言最终状态
• Playwright E2E — 端到端集成测试

快速开始

# 运行所有单元测试
npm test

# 运行特定游戏的测试
npm run test:summonerwars
npm run test:smashup
npm run test:dicethrone

# 运行 E2E 测试
npm run test:e2e

详见 自动化测试文档。

📄 文档

• 架构可视化 — 动画 SVG，一图看懂整体架构与管线流程
• 架构设计文档 — 完整技术架构说明
• 部署指南 — 同域 / Pages 分离 / 镜像部署完整说明
• 前端框架 — 游戏 UI 框架与组件约定
• 后端框架 — API 与游戏服务架构
• API 文档 — 认证、社交、管理等接口说明
• 原型构建器 — 简易游戏原型工具
• 自动化测试 — 测试策略与实践

🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add amazing feature'
4. 推送分支：git push origin feature/amazing-feature
5. 提交 Pull Request

📜 许可证

本项目代码基于 MIT License 开源。

游戏图片素材来自对应桌游的官方图包和民间汉化，版权归原作者所有，仅供学习交流使用，不可商用。

💖 赞助

如果喜欢这个项目，可以请作者喝杯咖啡。如需要，可以备注加入到赞助列表。