桌游教学与多人联机平台

# 桌游教学与多人联机平台


[![React](https://img.shields.io/badge/React-19-61DAFB?logo=react)](https://react.dev/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript)](https://www.typescriptlang.org/) [![Custom Engine](https://img.shields.io/badge/Game_Engine-自研-FF6B6B)](src/engine/) [![Tailwind CSS](https://img.shields.io/badge/Tailwind-4.1-06B6D4?logo=tailwindcss)](https://tailwindcss.com/) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

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

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

> **在线体验**：[easyboardgame.top](https://easyboardgame.top)

## 📑 目录

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

## ✨ 特性

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

## 🏗️ 技术栈
<details>
<summary>为什么选择前端</summary>

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

</details>

**前端**：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](https://nodejs.org/) >= 18
- [Git](https://git-scm.com/)
- [Docker](https://www.docker.com/)（可选，用于 MongoDB）

### 安装与启动

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

# 安装依赖
npm install

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

> **Windows 用户**：将 `cp` 替换为 `copy`。

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

```bash
npm run dev
```

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

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

```bash
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](.env.example)。

## 🎮 添加新游戏

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

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

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

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

<details>
<summary>模型选择建议</summary>


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

个人的省钱组合：windsurf/warp + kiro 阉割版claude + 反重力
> 单开编辑器容易被限流，因为很多时候同时有十多条任务在跑
> 小tip：使用规范驱动开发，claude写完后gpt立刻审核一遍，每次提交再审核一遍应该能大幅减少ai错误
</details>


## 🐳 Docker 部署

### 本地验证

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

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

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

```bash
# 下载部署脚本并执行（首次部署会进入交互式配置向导）
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](docs/deploy.md)。

## 🛠️ 常用命令

```bash
npm run dev                # 启动完整开发

... (truncated)