小游戏乐园(gamehub)业务需求文档
文档版本:v1.0(2026-11-19)|对应产品状态:gamehub 2026-11-19 代码(体验版发布通道已就绪)
本文档的目的:让接手的开发者(或其 AI Agent)在不读源码的情况下,准确知道每款游戏「应该是什么样」, 以便判断现有实现是否达标、新需求应该落在哪个模块、改动后用什么标准验收。
主读者画像:接手迭代的工程师 / AI Agent;使用环节是「接需求 → 定位模块 → 实现 → 按验收标准自测」; 既有知识假设:会用微信小程序框架与 Node,但不熟悉本项目的游戏规则细节与历史决策; 任务目标:快速定位功能归属并完成迭代;预期阅读时长 15 分钟(先读第 1、2 章,按需查第 3 章); 成功标准:不问原作者即可回答「某款游戏规则是什么、改哪、怎么验收」。
范围:全部 7 款已上线游戏的功能需求、全局通用需求、非功能需求。 本文档不覆盖:技术实现方案与部署步骤(见《小游戏乐园-架构与部署手册.md》); 协作守则与页面进度台账(见《小程序项目档案.md》);尚未立项的新游戏需求(新增时在 §5 追加变更记录)。
1. 产品概述
| 项 | 内容 |
|---|---|
| 产品定位 | 微信小游戏聚合平台:按分类 / 标签浏览游戏,一键邀请微信好友同玩,记录战绩 |
| 目标用户 | 想和朋友快速开一局轻量游戏的微信用户,无需注册、无需下载 |
| 核心价值 | 打开即玩(静默登录)+ 好友邀请即达(分享卡片直达房间)+ 多种玩法聚合 |
| 游戏数量 | 7 款,全部已上线可玩(2026-11-19 删除了 5 款「即将上线」占位游戏) |
游戏按同步方式分两类,这决定了需求能否作弊、延迟要求、以及代码落点:
| 类型 | 游戏 | 特征 |
|---|---|---|
| 联机游戏(服务端权威) | 同词相遇、你画我猜、棋类对战(好友局)、斗地主、记忆翻牌(联机局) | 两台设备共享房间状态,结果由云端决定,客户端只发指令 |
| 单机游戏(本地计算) | 反应大挑战、骰子与硬币、记忆翻牌(单人/同屏双人)、棋类对战(人机局) | 不联网、无 RPC 延迟;结果可被改客户端伪造,但无对手无奖励,可接受 |
2. 全局业务需求
以下需求适用于所有游戏,验收时逐条过。
G-01 静默登录
- 打开小程序即自动登录(
wx.login→ 云端换票),全程无任何点击、无授权弹窗; - 登录失败不阻塞浏览类功能(首页、详情、单机游戏全部可用);
- 仅在进入联机大厅且自动登录确实失败时,才出现「重新登录」手动按钮;
- 验收:首次打开 → 大厅直接显示「创建房间」;杀进程重开 → 仍是已登录(会话复用)。
G-02 游戏目录浏览
- 首页展示 7 款游戏卡片(图标 emoji、名称、分类·标签、简介、本人最高分、游玩次数);
- 分类筛选:全部 / 益智 / 反应 / 休闲 / 派对;标签筛选可叠加,可一键清除;
- 首页列表不得出现「即将上线」占位游戏(当前目录内全部可玩)。
G-03 游戏详情与评论
- 详情页展示玩法说明、个人最高分、累计游玩次数、评论列表;
- 评论需有昵称档案(来自「我的」页设置);评论与昵称目前为本机存储(换设备不迁移,属已知限制);
- 底部两个按钮:「开始游戏」(直达对应入口,见 §3 各游戏)与「邀请好友一起玩」(微信分享卡片)。
G-04 游玩记录
- 单机游戏结算后写入本地历史(游戏、成绩、时间),「我的」页可查看、可一键清空;
- 上限 200 条;联机游戏结算同样写入(如斗地主得分、同词相遇轮数)。
G-05 分享邀请与房间通用规则
| 规则 | 要求 |
|---|---|
| 房间号 | 同词相遇 / 你画我猜 / 棋类 / 联机翻牌 4 位数字;斗地主 6 位数字;唯一索引保证不重复 |
| 分享卡片 | onShareAppMessage 的 path 携带房间参数,好友点击直达加入界面 |
| 加入原子性 | 同一房间只能被一人抢入;房主重复加入返回原座位(幂等) |
| 恢复 | 大厅列出「我进行中的房间」,可恢复;掉线重进不丢局(棋类靠 moves 重放) |
| 并发 | 所有写操作带乐观锁(轮次 / turn / epoch_serial / serial),过期提交被服务端拒绝并提示刷新 |
3. 各游戏业务需求
3.1 同词相遇 💞(wordmeet,联机)
- 需求原文:两人加入同一房间,各自输入词语,不同就继续下一轮,直到输入同一个词即相遇成功。
- 规则:房主创建房间 → 好友加入 → 每轮双方各提交一个词 → 房主结算:相同则
finished并记录相遇词,不同则进入下一轮; - 交互:轮次历史回看;每轮结果有「详情」按钮,点击弹出 AI 复盘(流式输出双方思考分析;失败回落本地词面简析并诚实标注来源;按轮缓存不重复计费;关闭弹窗即中断请求);
- 数据:云端
word_rooms(RLS 限双方可见);战绩(总轮数,越小越好)写入本地历史; - 验收:双方提交后 2 秒内互相可见;相同词即结算;AI 复盘弹窗可流式生成、可中断、二次打开走缓存。
3.2 记忆翻牌 🃏(memory,单机 + 联机三形态)
- 单人:翻 8 对,计时计步,不记分;
- 同屏双人(一台手机):轮流翻两张,翻对 +1 分且继续翻(可连击),翻错不加分、牌回翻后换手;8 对分完弹窗显示比分与胜者(平局单独文案);切换模式即重开一局;
- 联机(各用手机):房间 4 位号;服务端洗牌(客户端永远拿不到牌序,未翻开位置返回
null);翻错的一对双方都要看见亮 1 秒后由服务端状态驱动回翻换手;乐观翻牌(点击即翻、显示呼吸占位,RPC 回来后对齐);配对成功的图案一直保留,不得变回问号;房主可「再来一局」重新洗牌; - 验收:双人翻错必须先回翻再换手;联机新房间 0 张可见、翻一张只露一张;配对后图案不消失;提交中轮询不得把乐观翻开的牌打回背面。
3.3 反应大挑战 ⚡(reaction,单机)
- 屏幕变绿瞬间点击,5 轮取平均反应毫秒数;抢跑无效;成绩写入历史。
3.4 骰子与硬币 🎲(dice-coin,单机)
- 需求原文:骰子可选数量,掷出后提示大小或正反。
- 骰子:1–6 颗可选;判定线 = 颗数 × 3.5,总和大于线报「大」、小于报「小」、正好压线报「平」(如 2 颗出 7 点必须显示「平」,不得归入大小);
- 硬币:点击翻转,CSS 旋转角度累加(每次至少多转三圈),落地按朝上那面报「正 / 反」;揭晓文字不得抢在动画结束前出现;
- 交互:摇动过程骰面每 90ms 随机闪换 8 次后落定;动画期间锁定按钮、玩法切换与颗数修改;保留最近 8 次记录;页面必须允许滚动(窄屏内容超出屏幕,禁滚动会裁掉记录区);
- 验收:2 颗出 7 显示「平」;连续两次同面硬币都要真的转起来。
3.5 你画我猜 🎨(draw-guess,联机)
- 画手从题库三选一 → Canvas 作画(颜色 / 粗细 / 橡皮 / 撤销 / 清空)→ 猜手实时看画并提交答案;
- 答案保密是硬需求:猜手只能看到字数提示,答案存独立表且行级策略限定仅当前画手可读(不是前端隐藏);
- 猜中:画手端判定并揭晓,猜手 +2、画手 +1;每局结束轮换画手;支持主动揭晓与结束结算;
- 笔画 600×600 逻辑坐标同步,猜手端 2 秒内可见;
- 验收:非画手直接调云接口读答案必须被拒;换色 / 撤销 / 清空后对方画布同步。
3.6 棋类对战 ♟️(board-games,人机 + 联机)
- 三棋种:五子棋 15×15、象棋 9×10(含送将 / 将死 / 困毙)、围棋 19×19(提子 / 禁入点 / 打劫 / 双虚着后贴 6.5 目);
- 人机局:完全本机(AI 在
utils/boardai.js),不写云端; - 好友局:房主执先手(象棋红 / 五子棋黑 / 围棋黑),加入者后行;云端只存 moves,双方客户端重放同一局面;
turn乐观锁防双落子; - 双方视角是硬需求:象棋执黑方棋盘转 180°(自己坐在下方),但棋子文字与河界文字必须正立;五子棋 / 围棋不翻(180° 自重合,翻了只会让坐标播报对不上);
- 验收:执黑方点自己下方的棋能选中且落子位置与手指一致;联机双方重放局面一致;同时落子只有一人成功。
3.7 斗地主 🃏(dou-de-zhu,联机)
- 需求原文:双人、三人、四人开房间;双人玩时从一副牌随机去掉 17 张。
- 发牌:双人 17+17+3(54 张随机去 17)/ 三人 17×3+3 / 四人 13×4+2;服务端洗牌,连开两局牌必须不同;
- 流程:叫地主(不叫 / 1 / 2 / 3 分,叫 3 直接当地主;全不叫自动重发)→ 地主领底牌(随后公开)→ 出牌;
- 牌局逻辑全部在服务端:牌型识别、大小比较、扣牌、回合推进、结算都由云端函数完成,客户端只发「叫分 / 出牌 / 不出」;
epoch_serial乐观锁; - 仿真牌桌 UI 是硬需求:牌桌背景全屏铺底且清晰不糊;扑克牌为 CSS 仿真牌(左上角点数花色索引 + 中央大花色,无位图);手牌一行铺满(按张数动态算牌宽,20 张也不出血);每张牌左上角点数花色始终可读(不被邻牌盖住);选中只「抬起」不放大、不加 z-index;支持点选与横向拖动连选一段(再拖反向取消);抬手后自动计算合法出法并生成放大预览带(放牌桌中央固定卡槽,绝不压住手牌行);「提示」循环给出能管上的最小牌;
- 计分:得分 = 底分 × 2^炸弹数,地主双倍收赔;
- 验收:非当前回合 / 过期 serial 出牌被拒;管不上服务端拒绝;手牌角标零遮挡(
tests/ddz-preview.js的cornerCoveredCount必须为 0);预览带不压手牌(preview.overlapsHand必须为 false)。
4. 非功能需求
| 编号 | 需求 | 标准 |
|---|---|---|
| N-01 | 发布包体积 | 主包 ≤ 2MB;当前实测 761 KB;每次改动后跑 node tests/ddz-pkgsize.js |
| N-02 | 帧流畅度 | 手势进行中禁止整表 setData;轮询不得打断进行中的手势或乐观 UI |
| N-03 | 隐私合规 | .wbapp_*.privacy.json 与微信后台「用户隐私保护指引」内容一致;仅收集昵称与对局输入内容 |
| N-04 | 异常兜底 | 云能力不可用时不得白屏:AI 复盘回落本地简析、登录失败落到手动兜底、轮询失败静默重试;房间拉取失败必须重试 + 会话自愈(连续 3 次才判死),不得一次失败就踢回大厅(utils/roomguard,错误屏带「重试」按钮) |
| N-05 | 兼容 | 窄屏(iPhone SE 320pt)不裁内容:骰子页必须可滚动;联机翻牌 / 斗地主布局以 375px 为基准 |
| N-06 | 支付红线 | 本项目不得接入任何虚拟支付(个人主体小程序 + iOS IAP 限制),后续如需道具须先过资质评估 |
5. 需求变更记录
| 日期 | 变更 | 原因 | 影响 |
|---|---|---|---|
| 2026-11-04 | 初版范围:同词相遇、你画我猜、记忆翻牌(单机)、反应大挑战、斗地主 | — | — |
| 2026-11-05~10 | 新增:棋类对战(三棋种 + 双方视角)、斗地主仿真牌桌、记忆翻牌双人/联机、骰子与硬币、同词相遇 AI 复盘 | 用户迭代需求 | 手册 §3.11–§3.17 对应技术方案 |
| 2026-11-19 | 删除 5 款「即将上线」占位游戏(数字速算 24 / 拼图大师 / 节奏点击 / 消除乐无穷 / 成语接龙) | 用户要求清理占位 | 目录剩 7 款全可玩;后续新增游戏走 data/games.js + §2.3 说明 |
新增 / 修改需求时:先在本表追加一行,再改对应需求卡;技术方案变化同步《架构与部署手册》对应小节。