# 家庭游戏中心 (Family Game Center) - 产品需求文档 (PRD)
**文档版本:** 1.0
**最后更新:** 2024-12-29
**状态:** 已审批，进入开发阶段
**目标平台:** Linux (Ubuntu 22.04 LTS) / 开发平台: Windows 11
---
## 📋 文档目录
1. [项目概述](#项目概述)
2. [功能需求](#功能需求)
3. [技术方案](#技术方案)
4. [系统架构](#系统架构)
5. [开发规范](#开发规范)
6. [API 设计](#api-设计)
7. [数据库设计](#数据库设计)
8. [UI/UX 设计规范](#uiux-设计规范)
9. [安全需求](#安全需求)
10. [测试计划](#测试计划)
11. [部署方案](#部署方案)
12. [验收标准](#验收标准)
---
## 项目概述
### 1.1 项目背景
为父母（年龄 50+ 岁）设计的易用家庭游戏平台。该平台旨在提供一个完全锁定的游戏环境，使非技术用户无法误操作进入系统，只能使用游戏功能。
### 1.2 项目目标
| 目标 | 说明 |
|------|------|
| **易用性** | 父母无计算机知识也能独立使用 |
| **安全性** | 系统级锁定，用户无法退出或破坏系统 |
| **稳定性** | 无中断运行 48+ 小时 |
| **游戏性** | AI 对手难度可调，赢率 40-60% |
| **维护性** | 单人可维护和更新 |
### 1.3 产品范围
**包含:**
- 4 款主要游戏 (斗地主、拖拉机、卡五星、赛车)
- Linux Kiosk 启动器
- 响应式菜单 UI
- 本地 AI 对手
- 游戏存档管理
- 基础统计功能
**不包含:**
- 网络在线多人对战
- 云同步和备份
- 用户账户系统
- 第三方集成
- 语音/视频功能
### 1.4 项目成功标准
✓ MVP 版本 (斗地主 + 菜单): 6-8 周
✓ 完整版 (全部游戏): 12-18 周
✓ 总成本: 硬件 5-15K，软件 0 元
✓ 团队规模: 1-3 人
✓ 风险等级: 低-中等
---
## 功能需求
### 2.1 用户故事
#### 故事 1: 启动和菜单
```
作为 父亲
我想 开机后直接进入游戏菜单
这样 我无需学习系统操作，只需选择想玩的游戏
```
**验收标准:**
- 系统启动后 5 秒内进入菜单
- 菜单显示 4 个游戏卡片
- 卡片字体 32px+，易于阅读
- 按钮 80px+，易于点击
- 菜单背景颜色高对比度 (WCAG AAA)
#### 故事 2: 启动游戏
```
作为 母亲
我想 点击游戏卡片启动游戏
这样 我可以开始游玩
```
**验收标准:**
- 点击卡片 3 秒内启动游戏
- 游戏加载时显示进度提示
- 游戏结束自动返回菜单
- 支持按 ESC 返回菜单
#### 故事 3: 无法退出
```
作为 家人
我想 用户无法通过快捷键或菜单退出游戏
这样 游戏不会被误关闭或系统被破坏
```
**验收标准:**
- Alt+F4 无效
- Alt+Tab 无效
- Windows 键无效
- 右键菜单禁用
- 任务栏隐藏
- TTY 无法切换 (Ctrl+Alt+Fx)
#### 故事 4: AI 对手
```
作为 玩家
我想 和智能电脑对手对战
这样 我可以随时游戏，不需要其他玩家
```
**验收标准:**
- 所有游戏都有 2-4 个 AI 对手
- AI 难度可调 (简单/中等/困难)
- AI 出牌合法且有策略性
- AI 响应时间 1-2 秒
#### 故事 5: 保存进度
```
作为 玩家
我想 每局游戏的成绩和统计被自动保存
这样 我可以看到我的进度和胜率
```
**验收标准:**
- 游戏结束后自动保存成绩
- 显示历史成绩和统计数据
- 统计包括: 总局数、胜率、平均用时
- 数据持久存储在本地数据库
### 2.2 功能清单
#### 2.2.1 菜单系统 (Priority: P0 - 必须)
| 功能 | 说明 | 优先级 |
|------|----------------------------------------|--------|
| **游戏列表展示** | 网格布局显示 4 个游戏卡片 | P0 |
| **游戏卡片** | 包含海报、名称、简描 | P0 |
| **启动游戏** | 点击卡片启动对应游戏 | P0 |
| **时间显示** | 菜单顶部显示当前时间 | P1 |
| **返回菜单** | 游戏结束自动返回，支持 ESC 返回 | P0 |
| **响应式布局** | 适配 1080p 到 4K 分辨率, 以2K分辨率 150%缩放作为基准开发 | P0 |
| **高对比度** | WCAG AAA 标准配色 | P0 |
| **父母友好** | 大字体、大按钮 | P0 |
#### 2.2.2 斗地主游戏 (Priority: P0 - 必须)
| 功能 | 说明 | 优先级 |
|------|------|--------|
| **基础规则** | 单张、对、顺、炸、王炸判定 | P0 |
| **手牌显示** | 玩家手牌按大小排序显示 | P0 |
| **出牌交互** | 鼠标/触屏选牌并出牌 | P0 |
| **地主判定** | 系统自动判定地主 | P0 |
| **AI 对手** | 2 个 AI 农民对手 | P0 |
| **游戏流程** | 发牌→抢地主→轮流出牌→结束 | P0 |
| **声音效果** | 出牌音效、胜负音效 | P1 |
| **游戏统计** | 保存胜负和用时 | P1 |
**牌型规则:**
- 单张: 任何一张牌
- 对牌: 同点数的两张牌
- 三张: 同点数的三张牌
- 顺子: 5 张及以上连续的牌 (2 不能在顺子中)
- 炸弹: 同点数的四张牌 (可以压任何牌)
- 王炸: 红黑王 (最大)
- 其他: 简化版，不实现飞机等复杂牌型
#### 2.2.3 拖拉机游戏 (Priority: P1 - 高)
| 功能 | 说明 | 优先级 |
|------|------|--------|
| **基础规则** | 四人跑牌，拖拉机机制 | P1 |
| **主牌概念** | 主花色、主点数 | P1 |
| **AI 对手** | 3 个 AI 对手 | P1 |
| **游戏流程** | 发牌→选主→轮流出牌→计分→结束 | P1 |
#### 2.2.4 卡五星麻将 (Priority: P2 - 可选)
| 功能 | 说明 | 优先级 |
|------|------|--------|
| **基础规则** | 五人麻将变种 | P2 |
| **AI 对手** | 4 个 AI 对手 | P2 |
| **胡牌类型** | 简化版，5-10 种常见胡牌 | P2 |
#### 2.2.5 赛车游戏 (Priority: P1 - 高)
| 功能 | 说明 | 优先级 |
|------|------|--------|
| **基础机制** | 加速、减速、转向、碰撞 | P1 |
| **AI 对手** | 1 个 AI 赛手 | P1 |
| **赛道** | 简单环形赛道，3 圈 | P1 |
| **计时** | 完成赛道的用时和排名 | P1 |
#### 2.2.6 系统功能 (Priority: P0 - 必须)
| 功能 | 说明 | 优先级 |
|------|------|--------|
| **自动启动** | 系统启动后自动进入菜单 | P0 |
| **快捷键禁用** | 完全禁用系统快捷键 | P0 |
| **进程监控** | 游戏异常退出时自动返回菜单 | P0 |
| **数据持久化** | 游戏数据本地保存 | P0 |
| **日志记录** | 系统和游戏日志记录 | P1 |
| **故障恢复** | 自动修复数据损坏和异常状态 | P1 |
### 2.3 非功能需求
| 类别 | 需求 | 验收标准 |
|------|------|---------|
| **性能** | 启动时间 | < 5 秒进入菜单 |
| **性能** | 菜单响应 | < 100ms UI 反馈 |
| **性能** | 内存占用** | < 500MB (菜单+游戏) |
| **性能** | 帧率 | 60fps 稳定 |
| **可靠性** | 运行时长 | 无中断 48+ 小时 |
| **可靠性** | 故障恢复 | 自动重启恢复 |
| **安全性** | 系统锁定 | 三层防护机制 |
| **兼容性** | 分辨率 | 1080p, 1440p, 2560p, 4K |
| **兼容性** | 输入 | 鼠标、触屏、手柄 |
| **可维护性** | 代码** | 注释完整，易扩展 |
| **可维护性** | 文档** | API、部署、故障排查 |
---
## 技术方案
### 3.1 技术栈选择
#### 3.1.1 开发平台 (Windows 11)
```
IDE/编辑器: VS Code / JetBrains IDE
Golang: 1.20+ (Golang for Windows)
Node.js: 18+ LTS (Windows版)
Godot Engine: 4.1+ (Windows版)
Git: Git Bash or GitHub Desktop
包管理器: npm (Node.js), go mod (Golang)
```
**开发优势:**
- 所有开发工具都有完整的 Windows 支持
- Golang 和 Node.js 可在 Windows 上原生编译
- Godot 有完整的 Windows 编辑器
- 跨平台编译: 在 Windows 编译 Linux 二进制
#### 3.1.2 部署平台 (Ubuntu 22.04 LTS)
```
操作系统: Ubuntu 22.04 LTS (Server 版本推荐)
系统配置: Kiosk 模式 + systemd + Openbox
启动器: Golang 二进制 + zserge/webview
菜单UI: Vue 3 构建输出
游戏: Godot 导出的 Linux 64-bit 二进制
运行时: 无需额外依赖 (所有编译为静态二进制)
```
**部署优势:**
- Fedora Silverblue 不可变文件系统，或 Ubuntu Server 最小化
- Kiosk 配置完全锁定系统
- 无强制系统更新
- 极低资源占用
### 3.2 架构设计
```
┌─────────────────────────────────────────┐
│ 用户交互层 (User Layer) │
│ 鼠标/触屏/键盘 │
└──────────────────┬──────────────────────┘
↓
┌─────────────────────────────────────────┐
│ 应用层 (Application Layer) │
│ │
│ ┌────────────────┐ ┌──────────────┐ │
│ │ Golang Launcher│ │ Process Mgr │ │
│ │ - Webview │ │ - Game spawn │ │
│ │ - 全屏模式 │ │ - 监控 │ │
│ └────────┬───────┘ └──────┬───────┘ │
│ │ │ │
│ ┌────────┴──────────────────┴────┐ │
│ │ HTTP Server (localhost:8888) │ │
│ └────────────────┬───────────────┘ │
│ │ │
│ ┌────────────────┴──────────────┐ │
│ │ Vue 3 前端菜单 │ │
│ │ - 游戏网格 │ │
│ │ - 响应式布局 │ │
│ └────────────────┬──────────────┘ │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ 游戏层 (Game Layer) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌────────┐ │
│ │Godot Game│ │Godot Game│ │Pixi.js │ │
│ │ 斗地主 │ │ 拖拉机 │ │ 赛车 │ │
│ └──────────┘ └──────────┘ └────────┘ │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ 系统层 (System Layer - Linux) │
│ │
│ ┌────────────────────────────────────┐ │
│ │ systemd 系统管理 │ │
│ │ - 自动登录 kiosk 用户 │ │
│ │ - 启动 game-launcher 服务 │ │
│ │ - 禁用睡眠、更新等 │ │
│ └────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────┐ │
│ │ X11/Wayland Display Server │ │
│ │ - Openbox 极简窗口管理 │ │
│ │ - 禁用快捷键 (X11 事件) │ │
│ │ - 禁用系统菜单 │ │
│ └────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────┐ │
│ │ Linux Kernel │ │
│ │ - SELinux / AppArmor │ │
│ │ - kiosk 用户权限管理 │ │
│ └────────────────────────────────────┘ │
└─────────────────────────────────────────┘
```
### 3.3 技术决策表
| 组件 | 选型 | 原因 |
|------|------|------|
| **启动器** | Golang | 内存 20MB, 启动 <100ms, 单二进制 |
| **菜单 UI** | Vue 3 + TypeScript | 响应式, 易修改, 开发快 |
| **卡牌游戏** | Godot 4 + GDScript | UI 系统优秀, 易学, 体积小 |
| **赛车游戏** | Pixi.js (Web 版) | 2D 性能最优, 易于参数调整 |
| **AI 算法** | 决策树 + 蒙特卡洛 | 快速开发, 难度可调, 可解释 |
| **数据库** | SQLite | 轻量级, 无需服务器, 易于备份 |
| **配置** | JSON | 易读易写, 无需解析库 |
---
## 系统架构
### 4.1 模块划分
```
project-root/
│
├─ launcher/ # Golang 启动器 (Module-1)
│ ├─ cmd/main.go # 入口点
│ ├─ internal/
│ │ ├─ launcher/launcher.go # 核心启动器逻辑
│ │ ├─ server/http.go # HTTP 服务器
│ │ ├─ process/manager.go # 进程管理
│ │ ├─ config/config.go # 配置加载
│ │ └─ logger/logger.go # 日志系统
│ ├─ go.mod
│ ├─ go.sum
│ └─ Makefile # 编译脚本
│
├─ frontend/ # Vue 3 菜单 (Module-2)
│ ├─ src/
│ │ ├─ App.vue # 根组件
│ │ ├─ main.ts # 入口
│ │ ├─ components/
│ │ │ ├─ GameGrid.vue # 游戏网格
│ │ │ ├─ GameCard.vue # 游戏卡片
│ │ │ └─ LoadingSpinner.vue # 加载提示
│ │ ├─ views/
│ │ │ ├─ MainMenu.vue # 菜单视图
│ │ │ ├─ StatisticsView.vue # 统计视图 (可选)
│ │ │ └─ SettingsView.vue # 设置视图 (可选)
│ │ ├─ services/
│ │ │ └─ api.ts # API 通信
│ │ ├─ types/
│ │ │ └─ game.ts # 类型定义
│ │ └─ styles/
│ │ └─ main.css # 全局样式
│ ├─ public/
│ │ ├─ games.json # 游戏配置
│ │ ├─ images/ # 游戏海报
│ │ └─ fonts/ # 中文字体
│ ├─ package.json
│ ├─ tsconfig.json
│ ├─ vite.config.ts
│ └─ Makefile
│
├─ games/ # 游戏项目
│ │
│ ├─ doudizhu/ # 斗地主 (Module-3)
│ │ ├─ project.godot # Godot 项目配置
│ │ ├─ scenes/
│ │ │ ├─ Game.tscn # 主场景
│ │ │ ├─ Card.tscn # 卡牌节点
│ │ │ ├─ Player.tscn # 玩家区域
│ │ │ └─ UI/
│ │ │ ├─ HandUI.tscn
│ │ │ ├─ TableUI.tscn
│ │ │ └─ InfoPanel.tscn
│ │ ├─ scripts/
│ │ │ ├─ Game.gd # 主逻辑 (~800 行)
│ │ │ ├─ CardLogic.gd # 规则判定 (~300 行)
│ │ │ ├─ AIPlayer.gd # AI 对手 (~500 行)
│ │ │ └─ UIController.gd # UI 控制 (~200 行)
│ │ ├─ assets/
│ │ │ ├─ images/
│ │ │ │ ├─ cards/ # 108 张牌纹理
│ │ │ │ └─ ui/
│ │ │ ├─ sounds/
│ │ │ │ ├─ card_play.wav
│ │ │ │ ├─ win.wav
│ │ │ │ └─ lose.wav
│ │ │ └─ fonts/
│ │ └─ export_presets.cfg # 导出配置
│ │
│ ├─ tractor/ # 拖拉机 (Module-4)
│ │ ├─ project.godot
│ │ ├─ scenes/
│ │ ├─ scripts/
│ │ │ ├─ Game.gd
│ │ │ ├─ CardLogic.gd # 拖拉机规则
│ │ │ └─ AIPlayer.gd
│ │ └─ assets/
│ │
│ ├─ mahjong/ # 卡五星 (Module-5, 可选)
│ │ ├─ project.godot
│ │ ├─ scenes/
│ │ ├─ scripts/
│ │ │ ├─ Game.gd
│ │ │ ├─ MahjongLogic.gd # 麻将规则
│ │ │ └─ AIPlayer.gd
│ │ └─ assets/
│ │
│ └─ racing/ # 赛车 (Module-6, Pixi.js)
│ ├─ src/
│ │ ├─ main.ts
│ │ ├─ Game.ts # 游戏主类
│ │ ├─ Car.ts # 车辆物理
│ │ ├─ Track.ts # 赛道管理
│ │ ├─ AI.ts # AI 赛手
│ │ └─ UI.ts # UI 管理
│ ├─ assets/
│ │ ├─ images/
│ │ ├─ sounds/
│ │ └─ fonts/
│ ├─ package.json
│ └─ tsconfig.json
│
├─ shared/ # 共享资源
│ ├─ fonts/
│ │ ├─ SourceHanSansSC-Regular.otf # 中文字体
│ │ └─ SourceHanSansSC-Bold.otf
│ ├─ images/
│ │ ├─ doudizhu.jpg # 游戏海报
│ │ ├─ tractor.jpg
│ │ ├─ mahjong.jpg
│ │ └─ racing.jpg
│ └─ sounds/
│ ├─ ui_click.wav
│ ├─ ui_hover.wav
│ └─ bgm.ogg
│
├─ config/ # 配置文件
│ ├─ kiosk/
│ │ ├─ gdm-custom.conf # GDM 自动登录
│ │ ├─ systemd-service.ini # systemd 服务
│ │ ├─ openbox-rc.xml # Openbox 配置
│ │ └─ xset-config.sh # X11 配置脚本
│ └─ app/
│ ├─ launcher.json # 启动器配置
│ └─ games.json # 游戏清单
│
├─ scripts/ # 构建和部署脚本
│ ├─ build-windows.bat # Windows 编译脚本
│ ├─ build-linux.sh # Linux 编译脚本
│ ├─ build-all.sh # 全量编译脚本
│ ├─ cross-compile.sh # 交叉编译脚本
│ ├─ deploy.sh # 部署脚本
│ ├─ setup-kiosk.sh # Kiosk 配置脚本
│ └─ verify.sh # 验证脚本
│
├─ docs/ # 文档
│ ├─ PRD.md # 本文档
│ ├─ ARCHITECTURE.md # 架构详解
│ ├─ DEVELOPMENT.md # 开发指南
│ ├─ API.md # API 文档
│ ├─ DEPLOYMENT.md # 部署指南
│ ├─ TESTING.md # 测试指南
│ └─ TROUBLESHOOTING.md # 故障排查
│
├─ tests/ # 测试用例
│ ├─ launcher/
│ ├─ frontend/
│ ├─ games/
│ └─ integration/
│
├─ README.md # 项目概述
├─ Makefile # 顶层编译脚本
├─ docker-compose.yml # 可选: Docker 支持
└─ .github/
└─ workflows/ # CI/CD 配置
```
### 4.2 依赖关系
```
启动器 (Golang)
│
├─ 依赖: zserge/webview (嵌入式浏览器)
│ stdlib (net/http, os/exec, etc.)
│
└─→ 启动 HTTP 服务器 (localhost:8888)
│
├─ 提供静态文件: 菜单 UI (Vue)
│
├─ 提供 API 端点: /api/launch
│ │
│ └─→ 调用 os/exec 启动游戏进程
│
└─ 提供 Webview
│
└─→ 显示菜单 UI
│
└─→ 用户交互
│
└─→ 调用 API 启动游戏
游戏进程 (Godot / Pixi.js)
│
├─ 通过 IPC/stdio 接收启动参数
│
└─ 独立运行，不需与启动器通信
(游戏结束时自己主动退出)
菜单 UI (Vue 3)
│
├─ 依赖: Vue 3, TypeScript, Vite
│
└─ 运行于 Webview 中
│
├─ 加载 games.json
│
└─ 通过 fetch API 调用启动器 HTTP 接口
```
---
## 开发规范
### 5.1 代码规范
#### 5.1.1 Golang 代码规范
```go
// 文件头注释
// Package main 描述此包的用途
package main
import (
"fmt"
"os"
// 标准库分组
"github.com/zserge/webview"
// 第三方库分组
)
const (
// 常量大写 + 下划线
DEFAULT_WEB_PORT = 8888
LAUNCHER_VERSION = "1.0.0"
)
type GameLauncher struct {
// 字段注释
currentGame *exec.Cmd // 当前运行的游戏进程
webPort int // HTTP 服务器端口
config Config // 配置对象
}
// NewGameLauncher 创建启动器实例
// 返回: *GameLauncher - 启动器指针
func NewGameLauncher() *GameLauncher {
return &GameLauncher{
webPort: DEFAULT_WEB_PORT,
}
}
// Start 启动游戏启动器
// 返回: error - 错误信息
func (gl *GameLauncher) Start() error {
// 函数实现
return nil
}
```
**规则:**
- 变量名用驼峰命名 (camelCase)
- 常量用大写 (CONSTANT_NAME)
- 每个公共函数必须有注释
- 每个包必须有注释说明其用途
- 错误处理不能忽略: `if err != nil { return err }`
- 使用 `fmt.Sprintf` 构建字符串，不要用 `+`
#### 5.1.2 Vue/TypeScript 代码规范
```typescript
// 文件头注释
/**
* GameLauncher.vue - 游戏启动器主组件
*
* 功能:
* - 显示游戏菜单网格
* - 处理游戏启动逻辑
* - 显示加载状态
*/
```
**规则:**
- 使用 `const` 优于 `let`，尽量避免 `var`
- 使用 TypeScript，不要用 JavaScript
- 组件名使用 PascalCase (GameCard.vue)
- 变量名使用 camelCase
- 使用 BEM 命名法管理 CSS 类名
- 必须包含 ARIA 无障碍属性
- 类型定义在每个文件头部
#### 5.1.3 GDScript 代码规范
```gdscript
# 文件头注释
## CardLogic.gd - 卡牌逻辑和规则判定
##
## 实现斗地主的卡牌判定算法
## 包括牌型检查、胜负判定等
class_name CardLogic
# 常量定义
const CARD_RANKS = ["9", "10", "J", "Q", "K", "A", "2"]
const CARD_SUITS = ["♠", "♥", "♦", "♣", "王"]
# 静态函数
static func is_valid_play(cards: Array) -> bool:
"""检查出牌是否合法"""
if cards.is_empty():
return false
# 单张
if cards.size() == 1:
return true
# 对牌
if cards.size() == 2:
return cards[0].rank == cards[1].rank
return false
# 实例函数
func get_best_play(hand: Array, table_cards: Array) -> Array:
"""根据手牌和桌面牌，给出最佳出牌"""
# 实现逻辑
return []
```
**规则:**
- 类名使用 PascalCase (CardLogic)
- 函数名使用 snake_case (is_valid_play)
- 常量使用 SCREAMING_SNAKE_CASE
- 每个公共函数使用 `##` 文档注释
- 避免全局变量，使用类成员变量
### 5.2 分支管理
```
main (生产分支)
│
├─ develop (开发分支)
│ │
│ ├─ feature/launcher (启动器功能)
│ ├─ feature/menu-ui (菜单 UI)
│ ├─ feature/doudizhu (斗地主)
│ ├─ feature/ai-algorithm (AI 算法)
│ └─ bugfix/xxx (bug 修复)
│
└─ release/v1.0 (发版分支)
```
**规则:**
- 功能开发: `feature/功能名`
- bug 修复: `bugfix/bug名`
- 发版准备: `release/版本号`
- 每个 PR 必须有描述和关联 issue
- 至少一人 code review 后才能合并
### 5.3 提交规范
```bash
# 格式: ():
#
#