小游戏乐园(gamehub)技术架构、业务架构与部署手册
项目路径:
D:\mycodes\MyApp\vx\wordsMeeting\gamehub技术形态:原生微信小程序 + WorkBuddy 托管云服务(Serverless 后端) 文档版本:v1.1(2026-11-19)|初版 v1.0(2026-11-04) 应用 ID:wbapp_ybUCXOWtc9v5IgfbOqHymv| 应用名称:小游戏乐园 | 域名前缀:game-hub变更记录 - v1.1(2026-11-19):游戏目录删除 5 款「即将上线」占位游戏(现为 7 款全部可玩);功能地图与目录结构补齐棋类对战(pages/board)、联机翻牌(pages/memory)、
data/drawwords.js与全部utils/模块;更新包体积实测值(761 KB)与测试断言数(validate 482);修正技术债清单与后续规划。 - v1.1 追加(2026-11-19):新增 §3.18 房间拉取守卫 —— 修复「进房间玩老是自动退出」:utils/roomguard.js(失败分类 + 会话自愈)+ 五房间页接线 + 错误屏「重试」按钮;validate 断言增至 499,包体积 771 KB。 - v1.0(2026-11-04):初版,覆盖同词相遇 / 你画我猜 / 斗地主 / 本地小游戏与部署全流程。配套文档:业务需求与验收标准见《小游戏乐园-业务需求文档.md》;协作守则与页面进度台账见《小程序项目档案.md》。
一、项目概览
| 项 | 内容 |
|---|---|
| 产品定位 | 小游戏聚合平台:按分类/标签浏览小游戏,一键邀请好友同玩,记录历史战绩、评论与分享 |
| 核心差异点 | 「同词相遇」为双人实时联机游戏,靠 WorkBuddy 云服务实现两台手机共享同一房间状态 |
| 技术栈 | 原生微信小程序(WXML/WXSS/JS)+ WorkBuddy Cloud SDK + PostgreSQL 云数据库 |
| 后端形态 | WorkBuddy 托管 Serverless(数据库 / 身份认证 / 文件存储),无需自建服务器 |
| 当前状态 | 代码完成、工程静态校验 482 项通过、云端自检通过;WorkBuddy 发布通道已打通(预览应用卡 + 分享面板可发布体验版);真机联机实测仍待补(见 §4.6 清单) |
二、业务架构
2.1 用户与角色
| 角色 | 描述 | 能力边界 |
|---|---|---|
| 游客(未登录) | 浏览首页分类/标签、查看游戏详情与评论列表 | 不能参与双人联机、不能发表评论(评论需昵称档案) |
| 注册用户(微信登录) | 默认已登录(打开小程序即静默登录);创建/加入房间、提交词语、结算战绩 | 只能读写自己参与的房间(由 RLS 策略强制) |
| 房主(owner) | 创建房间的一方 | 额外负责本轮结算(判断词语是否相同、推进轮次) |
身份来源:
wx.login拿 code →cloud.auth.signInWithWechat(code, appId)→ 云端返回 session,session.user.id即 RLS 中的auth.uid()。
2.2 功能地图
小游戏乐园
├── 首页(pages/index)
│ ├── 分类筛选:全部 / 益智 / 反应 / 休闲 / 派对
│ ├── 标签筛选(多标签命中)
│ └── 游戏卡片:图标、简介、分类·标签、本人最高分、游玩次数
├── 游戏详情(pages/detail)
│ ├── 玩法说明、个人最高分 / 累计游玩 / 评论数
│ ├── 评论区(发表 / 浏览,昵称来自本地档案)
│ ├── 邀请好友(微信分享卡片)
│ └── 开始游戏 → 内置可玩游戏 或 「即将上线」提示
├── 游戏运行(pages/play)
│ ├── 记忆翻牌(memory):单人计时计步 / 双人同屏轮流 / 联机房间(pages/memory)
│ ├── 反应大挑战(reaction):5 轮取平均反应毫秒
│ └── 掷骰子 / 掷硬币(dice):1–6 颗骰子判大小、硬币判正反
├── 同词相遇 · 大厅(pages/wordmeet/lobby)
│ ├── 微信登录 / 登录状态恢复
│ ├── 创建房间(4 位房间号)→ 分享邀请
│ ├── 输入房间号加入
│ └── 恢复「我进行中的房间」
├── 同词相遇 · 房间(pages/wordmeet/room)
│ ├── 等待好友加入 / 提交词语 / 实时同步对方状态
│ ├── 轮次历史回看
│ └── 相遇结算(相同词语 → 结束)→ 分享战绩
├── 你画我猜 · 大厅(pages/draw/lobby)
│ ├── 创建 / 加入房间、恢复进行中房间
│ └── 微信分享邀请
├── 你画我猜 · 房间(pages/draw/room)
│ ├── 画手三选一选题、Canvas 作画、颜色/粗细/橡皮/撤销/清空
│ ├── 猜手实时看画、提交答案,画手端自动判定猜中
│ ├── 每局轮换画手,猜中猜手 +2、画手 +1
│ └── 主动揭晓、结束结算、分享战绩
├── 棋类对战 · 大厅(pages/board/lobby)
│ ├── 选择棋种:五子棋 / 象棋 / 围棋
│ ├── 人机对战(完全本机,不写云端)或好友对战(创建房间)
│ ├── 创建房间(4 位房间号)→ 分享邀请;输入房间号加入
│ └── 恢复「我进行中的房间」
├── 棋类对战 · 房间(pages/board/room)
│ ├── Canvas 棋盘:五子棋 15×15 / 象棋 9×10(河界居中)/ 围棋 19×19
│ ├── 象棋执黑方棋盘 180° 坐标换算,棋子文字始终正立(§3.16)
│ ├── 人机局:`utils/boardai.js` 本机思考;好友局:`turn` 乐观锁 + moves 重放
│ └── 结算文案、最后一手高亮、双方视角各自坐在下方
├── 斗地主 · 大厅(pages/ddz/lobby)
│ ├── 选择人数:双人 / 三人 / 四人(并展示对应发牌规则)
│ ├── 创建房间(6 位房间号)→ 分享邀请
│ ├── 输入房间号加入
│ └── 恢复「我进行中的房间」
├── 斗地主 · 房间(pages/ddz/room)—— 仿真牌桌
│ ├── 牌桌背景:`assets/ddz/table.jpg` 全屏铺底 + 径向蒙层压暗,突出白色牌面
│ │ (原图 1440×1912 → 旋转 180° → **缩到 1080 宽**(覆盖 3x 屏,不再被拉伸放大)
│ │ → 轻模糊 0.3 消 JPEG 块噪 → sharp 强锐化 → 亮度 0.70 / 饱和度 0.76 压暗)
│ ├── 仿真扑克牌:纸面渐变 + 内高光 + 圆角投影 + 左上角点数/花色索引 + 中央大花色
│ │ (牌面用 CSS + Unicode 花色矢量绘制,54 张牌零加载延迟、任意分辨率清晰)
│ ├── 座位区:头像色块(昵称首字)/ 剩余张数角标 / 地主皇冠 / 叫分 / 牌背堆叠
│ ├── 叫地主(不叫 / 1 / 2 / 3 分)→ 地主领底牌 → 正式出牌
│ ├── 手牌:**一行铺满全部手牌**(按张数动态算牌宽与重叠步进,无需横向滑动),
│ │ 重叠只压住上一张牌的右侧,每张牌左上角点数/花色始终完整可读;选中抬起 + 金色描边
│ ├── 选牌手势:**点一下选一张** 或 **按住横向拖动连选一整段**
│ │ (拖动锚点原本未选中 → 整段选中;原本已选中 → 整段取消选中;松手前可随时反向拖)
│ ├── 牌桌中央:底牌 / 上一手出牌 / 我方牌堆(背面叠层 + 张数角标)
│ ├── 提示(循环给出能管上的最小牌)、重选、不出、炸弹倍数、结算得分
│ └── 1.5s 轮询同步云端牌局(服务端权威,客户端只发指令)
└── 我的(pages/profile)
├── 昵称设置(评论与成绩署名)
├── 累计游玩次数 / 玩过的游戏数
├── 历史游玩记录列表
└── 一键清空
2.3 游戏目录(内置数据,7 款,全部可玩)
| ID | 名称 | 分类 | 标签 | 玩法入口 |
|---|---|---|---|---|
| wordmeet | 同词相遇 💞 | 派对 | 双人 / 词语 / 默契 | pages/wordmeet/lobby |
| memory | 记忆翻牌 🃏 | 益智 | 记忆 / 单人 / 联机 / 经典 | pages/play/play?id=memory(单人 / 同屏双人)+ pages/memory/lobby(联机) |
| reaction | 反应大挑战 ⚡ | 反应 | 反应 / 手速 / 单人 | pages/play/play?id=reaction |
| dice-coin | 骰子与硬币 🎲 | 休闲 | 随机 / 运气 / 聚会 | pages/play/play?id=dice |
| draw-guess | 你画我猜 🎨 | 派对 | 双人 / 聚会 / 画画 | pages/draw/lobby |
| board-games | 棋类对战 ♟️ | 益智 | 双人 / 人机 / 棋类 | pages/board/lobby(五子棋 · 象棋 · 围棋) |
| dou-de-zhu | 斗地主 🃏 | 派对 | 棋牌 / 多人 / 斗地主 | pages/ddz/lobby(双人 · 三人 · 四人) |
2026-11-19 已删除 5 款「即将上线」占位游戏(math24 / puzzle-img / tap-rhythm / eliminate / idiom), 首页列表与详情页不再出现占位角标。目录内每条记录仍带
playable: true字段, 新增未完成玩法时可将该字段置false(首页会显示「即将上线」角标,详情页按钮置灰逻辑已简化为直接「开始游戏」,需同步恢复)。
目录定义在 data/games.js,字段:id / title / category / tags[] / emoji / color / desc / type / playable。
2.4 核心业务流程:同词相遇
房主 云端 word_rooms 好友
│ │ │
│ ①创建房间 ────────────────────────►│ status=waiting │
│ │ round=1, room_code=4位 │
│ ②分享邀请卡片 ─────────────────────────────────────────────────► │
│ │◄──── ③微信登录 + 输入房间号 ─┤
│ │ joiner_id=好友uid │
│ │ status=playing │
│ ④轮询(2s) ◄────────────────────────┤◄──────── ④轮询(2s) ─────────┤
│ │ │
│ ⑤提交词语 word_a ─────────────────►│ │
│ │◄──── ⑥提交词语 word_b ───────┤
│ ⑦房主结算 advanceRound ───────────►│ │
│ · word_a == word_b → status=finished, final_word=该词 │
│ · 否则 → history 追加本轮, round+1, 清空 word_a/word_b │
│ ⑧结算页展示最终词语与总轮数 ─────────────────────────────────────► │
│ ⑨写入本地游玩记录(score=总轮数,越小越好) │
关键机制:
- 房主唯一结算者:只有
role === 'a'(房主)会触发advanceRound,避免双方同时结算造成轮次错乱; - 轮次乐观锁:所有写操作带
.eq('round', room.round)条件,命中 0 行即判定「本轮已被结算」; - 房间号唯一:
word_rooms_code_idx唯一索引 + 客户端冲突重试(最多 3 次,捕获23505); - 加入原子性:
joinRoom同时带status='waiting'与joiner_id IS NULL条件,只有一人能抢到房间。
2.5 状态机
房间状态 word_rooms.status
waiting ──好友加入──► playing ──词语相同──► finished
│ │
│ └──词语不同──► playing (round+1)
页面状态 room.js data.viewState
loading → error | join | waiting | playing | finished
2.6 数据资产与归属
| 数据 | 存储位置 | 归属 | 备注 |
|---|---|---|---|
| 游戏目录 | 代码内置(data/games.js) |
全局 | 无需数据库 |
| 游玩记录 | 本机 wx.storage(gh_history) |
单设备 | 最多 200 条;未上云 |
| 评论 | 本机 wx.storage(gh_comments) |
单设备 | 每游戏最多 100 条;未上云 |
| 用户昵称档案 | 本机 wx.storage(gh_profile) |
单设备 | 未上云 |
| 房间与词语 | 云端 word_rooms |
双人共享 | 已上云,RLS 保护 |
| 你画我猜房间、笔画、猜测、比分 | 云端 draw_rooms |
双人共享 | 已上云,2 秒轮询同步 |
| 你画我猜当前答案 | 云端 draw_secrets |
仅当前画手 | 已上云,独立 RLS,猜手无权读取 |
设计取舍:评论与历史仍为本地存储,是因为它们属于「单机体验数据」;跨设备同步属于后续增强项(见 §5)。
三、技术架构
3.1 分层视图
┌───────────────────────────────────────────────────────────┐
│ 表现层 (WXML / WXSS / Page) │
│ index · detail · play · profile · wordmeet/lobby · room │
├───────────────────────────────────────────────────────────┤
│ 页面逻辑层 │
│ 筛选渲染 / 分享卡片 / 轮询调度 / 状态机推进 / 成绩记录 │
├───────────────────────────────────────────────────────────┤
│ 数据访问层 (utils) │
│ store.js → 本地:记录 / 评论 / 昵称档案(wx.storage) │
│ wordroom.js→ 云端:word_rooms 表 CRUD + 业务语义封装 │
├───────────────────────────────────────────────────────────┤
│ 云客户端 utils/cloud.js │
│ createMiniProgramWorkBuddyCloud(endpoint, publishableKey)│
│ + workbuddy-cloud-diagnostics.js(失败请求诊断) │
├───────────────────────────────────────────────────────────┤
│ 微信平台运行时 (wx.*) │
│ wx.login / wx.getStorageSync / wx.showToast / 分享卡片 │
└───────────────────────────────────────────────────────────┘
│ HTTPS
▼
┌───────────────────────────────────────────────────────────┐
│ WorkBuddy 托管云服务(Serverless) │
│ ├ 云数据库 PostgreSQL(word_rooms 表 + RLS 策略) │
│ ├ 身份认证(微信登录 → session / auth.uid()) │
│ ├ 文件存储(预留给头像/截图/素材) │
│ └ 资源点计量(按 CPU、容量、调用次数等计费) │
└───────────────────────────────────────────────────────────┘
3.2 技术栈明细
| 层 | 选型 | 版本 / 说明 |
|---|---|---|
| 客户端框架 | 原生微信小程序 | style: v2,lazyCodeLoading: requiredComponents |
| 视图 | WXML + WXSS | 无第三方 UI 库,纯手写样式 |
| 逻辑 | 原生 JS(CommonJS) | 未使用 ES Module / 框架,兼容微信开发者工具默认配置 |
| 云 SDK | @tencent-ai/workbuddy-cloud-sdk |
^0.1.4-dev.ca27990.202610161713,入口 /miniprogram |
| 后端 | WorkBuddy 托管(CloudBase 计量) | Serverless,PostgreSQL |
| 依赖管理 | npm | 仅 1 个运行时依赖,SDK 已构建进小程序包 |
| 本地存储 | wx.getStorageSync / setStorageSync |
全部读写包 try/catch,异常不阻塞 UI |
3.3 目录结构与职责
gamehub/
├── app.js / app.json / app.wxss # 应用入口:页面注册、全局样式、会话缓存
├── project.config.json # 微信开发者工具工程配置(当前 appid=touristappid)
│ # packOptions.ignore 决定发布包内容(不看 .gitignore!),见 §4.8
├── sitemap.json # 搜索收录规则
├── package.json # npm 依赖(云 SDK)
├── .wbapp_*.privacy.json # 隐私保护指引声明
├── data/
│ ├── games.js # 游戏目录(分类/标签/玩法元数据)
│ └── drawwords.js # 你画我猜题库(画手三选一)
├── utils/
│ ├── cloud.js # 云客户端初始化(endpoint + publishableKey)
│ ├── store.js # 本地存储层:记录 / 评论 / 昵称档案
│ ├── roomguard.js # 房间拉取失败分类 + 会话自愈(五房间页共用,防误判踢人,§3.18)
│ ├── wordroom.js # 同词相遇:房间/提交/结算
│ ├── wordai.js # 同词相遇:AI 复盘 prompt / 模型挑选 / 流式 / 兜底
│ ├── drawroom.js # 你画我猜:房间/选题/笔画/猜词/轮换/结算
│ ├── memorygame.js # 联机翻牌:牌面映射 / 状态投影 / 可点判定 / 增量补丁
│ ├── memoryroom.js # 联机翻牌:RPC 封装(只走函数,不直连表)
│ ├── boardeng.js # 棋类规则引擎(纯函数:五子棋/象棋/围棋统一接口)
│ ├── boardai.js # 棋类 AI(本机人机局)
│ ├── boardmeta.js # 棋类元数据(棋种配置:棋盘规格/先后手/文案)
│ ├── boardroom.js # 棋类房间数据层(turn 乐观锁)
│ ├── boardview.js # 棋类双方视角换算(flipRC 自逆,象棋执黑翻转)
│ ├── ddzcards.js # 斗地主牌型引擎(纯函数,与云端 ddz_classify 同构)
│ ├── ddzroom.js # 斗地主:建房/加入/拉取状态 + 服务端动作 RPC 封装
│ ├── ddzlayout.js # 斗地主手牌布局:按张数算牌宽/重叠步进,一行铺满
│ ├── ddzgesture.js # 斗地主拖动连选手势:命中判定 / 选区 / 选中回滚
│ ├── ddzauto.js # 斗地主自动选牌:合法牌型枚举 / 能压优先
│ ├── dicelib.js # 掷骰子/掷硬币规则(纯本地随机,不上云)
│ └── workbuddy-cloud-diagnostics.js # 云请求失败诊断包装
└── pages/
├── index/ 分类标签筛选 + 游戏列表
├── detail/ 游戏详情 + 评论 + 分享邀请
├── play/ 记忆翻牌(单人/同屏双人)、反应大挑战、掷骰子/掷硬币
├── memory/ 联机翻牌:lobby 建房加入、room 云端牌桌
├── board/ 棋类对战:lobby 选棋种建房加入、room Canvas 棋盘
├── profile/ 昵称、历史记录、清空
├── wordmeet/
│ ├── lobby/ 登录、创建/加入房间、恢复进行中房间
│ └── room/ 房间页:轮询同步、输入词语、AI 复盘、结算
├── draw/
│ ├── lobby/ 创建/加入你画我猜房间
│ └── room/ Canvas 作画、实时猜词、轮换画手、比分结算
└── ddz/
├── lobby/ 选人数、创建/加入房间、恢复进行中房间
└── room/ 仿真牌桌:叫地主、选牌出牌、提示/不出、结算
# 另:cloud/ddz.sql 与 cloud/memory.sql 为云端可部署脚本(打进发布包前被 ignore 排除)
# assets/ddz/ 为斗地主位图素材(牌桌背景 / 牌背)
3.4 云端数据模型
表 public.word_rooms
| 列 | 类型 | 说明 |
|---|---|---|
| id | BIGINT GENERATED ALWAYS AS IDENTITY | 主键 |
| owner_id | TEXT NOT NULL DEFAULT auth.uid() | 房主用户 ID(RLS 归属字段) |
| owner_name | TEXT | 房主昵称快照 |
| joiner_id | TEXT | 加入者用户 ID |
| joiner_name | TEXT | 加入者昵称快照 |
| room_code | TEXT NOT NULL | 4 位数字房间号(唯一) |
| status | TEXT NOT NULL DEFAULT 'waiting' | waiting / playing / finished |
| round | INT NOT NULL DEFAULT 0 | 当前轮次,兼作乐观锁版本号 |
| word_a / word_b | TEXT | 本轮双方词语(房主 / 加入者) |
| history | JSONB NOT NULL DEFAULT '[]' | 历史轮次数组 [{round,a,b}] |
| final_word | TEXT | 相遇成功时的共同词语 |
| created_at / updated_at | TIMESTAMPTZ | 时间戳,updated_at 用于大厅排序 |
索引:word_rooms_code_idx UNIQUE (room_code)
RLS 策略(ALTER TABLE word_rooms ENABLE ROW LEVEL SECURITY)
| 策略 | 命令 | 条件 |
|---|---|---|
word_rooms_select |
SELECT | owner_id = auth.uid() OR joiner_id = auth.uid() OR status = 'waiting' |
word_rooms_insert |
INSERT | WITH CHECK owner_id = auth.uid() |
word_rooms_update |
UPDATE | USING (owner_id = auth.uid() OR joiner_id = auth.uid() OR (status='waiting' AND joiner_id IS NULL)),WITH CHECK (owner_id = auth.uid() OR joiner_id = auth.uid()) |
授权:GRANT SELECT, INSERT, UPDATE ON TABLE public.word_rooms TO authenticated
设计要点:处于
waiting的房间对所有登录用户可见(才能被搜到并加入),但只有房主与加入者可写;joiner_id IS NULL保证不会两个人同时抢占同一个房间。
你画我猜:public.draw_rooms + public.draw_secrets
draw_rooms 保存房间号、双方身份、status(waiting/playing/finished)、phase(prepare/drawing/revealed)、局数、当前画手、字数提示、笔画 JSONB、猜测 JSONB、双方比分、揭晓答案与结算文本。房间级 RLS 与 word_rooms 相同。
draw_secrets 仅保存 room_id + word,通过外键在删除房间时级联清理。其 SELECT/INSERT/UPDATE 三条策略都要求:当前用户的身份必须与 draw_rooms.drawer_role 指向的画手一致。因此猜手即使直接调用云接口也读不到答案,不是只靠前端隐藏。
笔画采用 600×600 逻辑坐标,双方根据屏幕宽度等比缩放;每条笔画结束后整体同步,单条最多 600 点、每局最多 200 条,避免超长触控与 JSONB 无界增长。猜中判定在画手端进行;每局结束轮换画手,新画手选题后才写入新密文并进入 drawing。
棋类对战:public.board_rooms
| 列 | 类型 | 说明 |
|---|---|---|
| id | BIGINT IDENTITY | 主键 |
| owner_id / owner_name | TEXT | 房主(象棋执红先行;五子棋/围棋执黑先行) |
| joiner_id / joiner_name | TEXT | 加入者(象棋执黑后行;五子棋/围棋执白后行) |
| room_code | TEXT UNIQUE | 4 位房间号 |
| game_type | TEXT | gomoku / chess / go |
| status | TEXT | waiting / playing / finished |
| turn | TEXT | a / b,当前行棋方(乐观锁) |
| moves | JSONB | 完整着法列表 [{r:'a',m:{...}}],掉线重进重放恢复 |
| result / winner | TEXT | 结算文本与胜方 |
RLS 与 word_rooms 同构(waiting 可见、双方可写)。submitMove 以 .eq('turn', role) 做乐观锁,双方同时落子只有一人成功。规则引擎 utils/boardeng.js 为纯函数(五子棋连五、象棋全规则含送将/将死/困毙、围棋提子/禁入点/打劫/双虚着贴 6.5 目计分),双方客户端各自重放同一份 moves 得到一致局面,云端不跑规则。人机对战完全本机运行,不写云端。回归测试 tests/board-test.js(30 断言)。
视角:象棋有红黑身份,两人必须各自看到自己坐在下方。执黑时整块棋盘转 180°,但这只是坐标换算(utils/boardview.js),不是给 canvas 加旋转——棋子字和「楚河汉界」始终正着画,否则坐在下方的人会看到一屏倒字。详见 §3.16。
斗地主:public.ddz_rooms + public.ddz_hands + public.ddz_bottom
| 表 | 说明 |
|---|---|
ddz_rooms |
房间主表:房间号(唯一索引)、人数 2/3/4、阶段 deal/bid/assign/play/finished、房主与座位昵称、地主座位、当前回合 turn_seat、上一手牌型 last_sig、出牌堆 heap、各座位手牌/已出张数、炸弹数、结算 result、乐观锁 epoch_serial |
ddz_hands |
各座位手牌,主键 (room_id, seat);RLS 限定仅本人可读自己那行 |
ddz_bottom |
底牌隔离表,主键 room_id;RLS 限定仅地主且处于 assign/play 阶段可读,领牌后底牌转写入 ddz_rooms.bottom_cards 公开 |
斗地主与前几款不同:牌局逻辑完全在服务端。客户端只发送「叫分 / 出牌 / 不出」三类指令,所有洗牌、牌型识别、大小比较、手牌增删、回合推进与结算都由 SECURITY DEFINER 函数完成,客户端无法伪造手牌或改写牌局。
服务端函数:
| 函数 | 作用 |
|---|---|
ddz_deck() |
返回 54 张牌常量数组 |
ddz_rank(text) |
牌编码 → 点数(3..10/J/Q/K/A/2/小王/大王 = 3..17) |
ddz_classify(text) |
牌型识别,返回签名 '<类型>:<主牌点数>:<长度>' |
ddz_beats(text, text) |
大小比较:火箭 > 炸弹 > 同型同长比点数 |
ddz_join(room_id, name) |
原子分配座位号,同一用户重复调用返回原座位 |
ddz_deal(room_id) |
房主开局:洗牌并发牌,双人模式从 54 张中随机去掉 17 张 |
ddz_deal_internal(room_id) |
发牌内部实现,已 REVOKE 掉 PUBLIC/anon/authenticated 的执行权,只能被上面的 SECURITY DEFINER 函数调用 |
ddz_bid(room_id, bid) |
叫地主:叫 3 分直接当地主;全叫 0 分自动重发 |
ddz_take_bottom(room_id) |
地主领底牌,底牌公开,阶段转 play |
ddz_play(room_id, cards, serial) |
出牌:校验牌型、管上一手、扣减手牌、推进回合、判胜负结算 |
ddz_pass(room_id, serial) |
不出:连续两人都不要则上一手玩家自由出牌 |
ddz_finish(room_id, reason) |
房主强制结束对局 |
发牌布局(ddz_deal_internal):
| 人数 | 牌源 | 每家手牌 | 底牌 | 合计 |
|---|---|---|---|---|
| 2 人 | 一副 54 张随机去掉 17 张 | 17 | 3 | 37 |
| 3 人 | 一副 54 张 | 17 | 3 | 54 |
| 4 人 | 一副 54 张 | 13 | 2 | 54 |
洗牌(必须先展开再排序)——历史上在这里踩过 PostgreSQL 的坑:
-- ❌ 错误:目标列表里的集合返回函数在 ORDER BY 之后才展开,
-- random() 实际只对 1 行排序 → 牌序恒定,每局发的牌完全一样
deck := ARRAY(SELECT unnest(ddz_deck()) ORDER BY random());
-- ✅ 正确:先在 FROM 里把数组展开成 54 行,再逐行随机排序
deck := ARRAY(
SELECT c FROM unnest(ddz_deck()) AS c
ORDER BY md5(c || chr(58) || clock_timestamp()::TEXT || chr(58) || random()::TEXT)
);
排序键额外混入 clock_timestamp() 与 random(),即使连接池重置 PRNG 也不会退化成固定牌序。
双人的「随机去掉 17 张」= 洗好后丢掉牌堆前 17 张,天然随机。
云端 SQL 版本化:gamehub/cloud/ddz.sql 是斗地主全套表结构 + RLS + 授权 + 14 个服务函数的可部署脚本(本次事故的直接产物——线上 SQL 此前只存在于控制台,没有版本记录)。测试用「函数体 md5」比对本地文件与线上函数,确保两者不会漂移;tests/ddz-test.js 同时锁定洗牌写法,防止改回错误写法。
双端同构:客户端 utils/ddzcards.js 与服务端 ddz_classify / ddz_beats 必须返回完全一致的签名。共享向量表 tests/ddz-vectors.js(42 条)同时用于客户端回归测试与云端 parity 校验,任一端改规则都会立刻暴露不一致。
并发控制:epoch_serial 作为乐观锁。出牌 / 不出必须携带客户端看到的 epoch_serial,服务端比对不一致直接拒绝并提示刷新,避免重复提交与双回合同步推进。
胜负与计分:地主出完最后一张牌即地主胜;农民出完记入 out_seats,所有农民都出完则农民胜。得分 = 底分 × 2^炸弹数,地主赢则双倍收、输则双倍赔。
服务端回归自检 ddz_selftest() 用 set_config('request.jwt.claim.sub', ...) 注入身份串跑完整链路(建房 → 加入 → 发牌 → 叫地主 → 领底牌 → 出牌 → 不出 → 结算 → 级联清理),24 项断言覆盖 2/3/4 人布局与地主/农民两条胜负路径;末尾并入 ddz_selftest_shuffle()——连开 6 局三人局,断言每局布局正确、无重复牌、且 6 局拿到 6 套互不相同的手牌(直接验证洗牌随机性)。两个自检函数均已 REVOKE 掉 PUBLIC/anon/authenticated 的执行权。
⚠ 授权收口注意:PostgreSQL 新建函数默认授予
PUBLICEXECUTE,只 REVOKE anon/authenticated 是收不住的(has_function_privilege仍返回 true),必须把PUBLIC一起 REVOKE。
3.5 身份与会话(默认登录)
设计目标:用户打开小程序即处于已登录状态,不需要任何点击。
| 环节 | 实现 | 位置 |
|---|---|---|
| 启动即登录 | App.onLaunch 触发 ensureSession() |
app.js |
| 会话获取顺序 | ① cloud.auth.getSession() 复用云端已有会话 → ② 无会话则 wx.login 取 code → cloud.auth.signInWithWechat(code, appid) 静默换票 |
app.js resolveSession() |
| 会话缓存 | Promise 单例缓存(this.sessionPromise),多页面共享一次登录 |
app.js ensureSession() |
| 失败重试 | 登录失败不缓存,页面下次进入自动重试;大厅/房间页额外自动重试 1 次 | app.js / lobby.js / room.js |
| 昵称兜底 | 登录成功后,若本地仍是默认昵称则用微信昵称填充(不覆盖用户自定义昵称) | app.js syncNickname() |
| 手动兜底 | 自动登录确实失败时,大厅才显示「重新登录」按钮 | lobby.js onLogin() |
页面统一用 authState 三态:checking(正在自动登录…) / signed-out(自动登录未成功,可手动重试) / signed-in。
登录链路唯一收敛在
app.js:全工程只有app.js调用wx.login与signInWithWechat(静态校验脚本会强制这一点),避免多处登录逻辑不一致。 登录失败时通过诊断助手输出结构化日志(stage、message),便于定位是wx.login失败、AppID 取不到,还是服务端拒绝换票。 前置条件:需已绑定小程序账号(或试用版)并在应用管理的身份认证中开启「微信登录」开关,否则静默登录会失败并落到手动兜底界面。
3.6 实时同步方案
| 方案 | 是否采用 | 说明 |
|---|---|---|
| 轮询(2 秒) | ✅ 当前采用 | 实现简单、成本可控、无需长连接;双人轻量交互 2 秒延迟可接受 |
| WebSocket / 实时推送 | ⏳ 备选 | 需云函数或实时订阅能力,待平台支持后升级 |
同步链路:客户端 setInterval(2000) → getRoom(id) → 云端返回最新房间 → 页面按 viewState 分支渲染。
3.7 关键设计决策与取舍
| 决策 | 选择 | 理由 |
|---|---|---|
| 数据层形态 | 本地 + 云端双层并存 | 单机游戏无需联网;只有需要跨设备共享的「同词相遇」上云 |
| 本地层抽象 | 独立 utils/store.js |
后续把评论/记录迁上云时,只替换该文件,页面零改动 |
| 房间结算权 | 归房主单点结算 | 避免并发双写导致的轮次错乱;配合 round 乐观锁兜底 |
| 房间号 | 4 位数字 + 唯一索引 + 重试 | 便于口头/输入分享;索引保证唯一,重试应对极小概率冲突 |
| 隐私数据 | 仅昵称等非敏感信息 | 隐私清单声明「发表游戏评论、与好友同局游戏时共享你输入的词语」 |
| 前端密钥 | 只放 publishableKey |
服务端按 Origin 校验,环境 ID 与真实密钥不下发到前端 |
3.8 安全与合规
- 数据隔离:RLS 行列级安全策略限制房间读写范围,非参与者无法读取他人对局内容;
- 凭据管理:前端仅持有
publishableKey(可公开标识,无权限),endpoint为公开访问入口,鉴权在服务端; - 隐私指引:
.wbapp_ybUCXOWtc9v5IgfbOqHymv.privacy.json声明用户发布内容范围,发布时需同步填写微信后台的用户隐私保护指引; - 数据生命周期:云服务暂停后数据按会员等级保留 30/60 天,期满未恢复永久删除,重要数据需定期导出。
3.9 容量与成本模型
云服务按资源点计费(与 AI 积分是两套独立口径),计费项包括:数据库 CPU 使用量、数据库容量、服务调用次数、访问频率超额部分、文件存储读写/容量/流量、短信验证码条数、云函数算力等。
对当前项目的用量估算口径:
| 场景 | 主要消耗项 | 说明 |
|---|---|---|
| 单人玩记忆翻牌/反应 | 几乎为 0 | 全本地,仅本地 storage |
| 双人同词相遇一轮 | 数据库读写 + 2 次轮询请求 | 每 2 秒 1 次 getRoom,是主要消耗来源 |
| 好友规模 | 房间数 × 轮数 × 轮询频率 | 轮询频率若从 2s 降到 4s 可减半消耗 |
优化选项(未实施):轮询自适应退避(对手已提交后停止轮询)、只在页面可见时轮询(当前已用 onHide 停轮询)。
3.10 已知技术债
- 评论、游玩记录、昵称仍为本地存储,换设备即丢失;
- 房间不做超时回收,长期不玩的房间会一直占用
waiting状态; - 轮询固定 2 秒(联机翻牌 900ms),未做自适应退避;
project.config.json中appid仍为touristappid(游客模式),绑定正式小程序后需由发布流程写入;- 测试全部为本地 Node 断言脚本(累计约 1300 条断言),无 CI 自动触发,需在每次提交前手动运行(命令清单见 §4.1)。
发布体积红线(曾导致发布失败,见 §4.7):微信主包 ≤ 2MB(预览/真机调试 ≤ 4MB)。 发布通道只读
project.config.json的packOptions.ignore,不读.gitignore—— 所以tests/、cloud/这类开发目录必须显式写进 ignore,否则会被打进代码包导致 上传报errcode 80051。当前实测 761 KB(2026-11-19,含 miniprogram_npm 166 KB),node tests/ddz-pkgsize.js可随时自查。
3.11 斗地主选牌交互设计(增量 setData + 自动识别 + 放大预览带)
需求原文:「选牌不是很流畅,拖动选牌后自动计算可以出的多张牌并放大展示, 但是不要压着旁边的牌,不然看不到旁边的牌了」。拆成三件事分别处理:
① 流畅 —— 增量 setData + 轮询不重绘
| 症状 | 根因 | 处理 |
|---|---|---|
| 拖动时整排手牌闪 | 每次 touchmove 都 setData({ myHand: <20 张牌对象> }) |
改成单卡路径写入 myHand[i].selected |
| 连续选中有多余重绘 | 每次都把全部牌重写一遍 | 用 this.viewSelected 快照做差集,只写状态真的变了的牌 |
| 每 1.5s 轮询把手牌重排一次 | applyState 每次重建 myHand |
比对 codes.join(','),只有手牌真的变了才重建 |
| 轮询的整页 setData 打断手势 | 拖动中也在下发全量数据 | 拖动期间把轮询结果挂起到 pendingState,抬手后补上 |
实测:enumeratePlays(20 张) 单次约 0.12ms —— 算法不是瓶颈,setData 的 payload 才是,
所以优化重心全在「少下发」上。
② 自动计算「可以出的多张牌」 —— 新增纯函数模块 utils/ddzauto.js:
- 整组选中的牌本身就是合法牌型 → 原样采用,只额外告知
canBeat(不擅自改用户的选择); - 整组不合法 →
enumeratePlays枚举合法子组合,优先从「能压过上一手」的组合里挑, 同等条件下按「张数最多 → 牌型最小 → 主牌最小」排序; - 一个合法牌型都凑不出 → 明确报「不是有效牌型」。
拖动抬手时 settleSelection() 把选区收敛成算出来的那一手,于是「出牌」按钮出的就是预览里那一手。
③ 放大展示且不压住旁边的牌 —— 结构性解决,不是靠调 z-index:
- 放大牌绝不放在手牌行里。手牌是重叠排列的,就地放大必然溢出到邻牌身上。
预览带改放在牌桌中央的固定卡槽(
.table-slot),与手牌行完全分离。 - 卡槽高度固定、预览带绝对定位(
position: absolute)→ 预览出现/消失不会推动手牌行, 否则拖动过程中手牌被顶走,手指会跟丢目标。 - 选中牌只「抬起」不「放大」,并且刻意不加
z-index: 加了z-index的选中牌会盖住右邻牌的点数角标(这正是「看不到旁边的牌」的根因); 去掉后按文档顺序绘制,邻牌角标始终可读,选中牌自身的角标靠布局步进step ≥ MIN_STRIP(32rpx)保证。tests/ddz-preview.js用elementFromPoint逐张断言这一点(cornerCoveredCount必须为 0)。 - 牌多时预览折成两行(≤7 张一行、≥8 张两行),保证放大的牌始终比手牌里的牌宽 (20 张手牌时手牌只有 70rpx 宽,预览 8~18 张时仍有 71~104rpx)。
3.12 记忆翻牌的 3D 翻转陷阱(opacity 会毁掉 preserve-3d)
需求原文:「记忆翻牌翻牌成功后把图片保留着,不要变成问号」。
现象:配对成功的两张牌,配对瞬间能看见图案,但很快变回蓝底白问号。
根因不是逻辑,是 CSS 3D 扁平化:
.card-inner { transform-style: preserve-3d; } /* 3D 容器 */
.card-open { transform: rotateY(180deg); } /* 翻到正面 */
.card-front { transform: rotateY(180deg); backface-visibility: hidden; }
.card-matched { opacity: 0.55; } /* ← 元凶 */
opacity < 1 会让浏览器把该元素渲染成独立分组,从而把 transform-style: preserve-3d
强制扁平化为 flat。扁平化之后,.card-front 自身的 rotateY(180deg) 被判定为
「背面朝前」而 backface-visibility: hidden 把它隐藏 —— 露出来的反而是没有任何翻转的
.card-back,也就是那个问号。
规律:3D 翻转容器(
preserve-3d)及其 3D 子元素上,一律不能出现opacity/filter/backdrop-filter/mask/clip-path。 想要「变淡」的效果,就把样式做在子元素内部(背景色、描边、角标), 或者给 3D 容器外面再包一层普通 div。
修复(pages/play/play.wxss):
| 之前 | 之后 |
|---|---|
.card-matched { opacity: 0.55 } |
.card-matched .card-front { background/边框/内阴影 } —— 已配对改成浅绿底 + 绿框 |
| 无状态标识 | .card-done 绿色 ✓ 角标(wx:if="{{item.matched}}") |
| 无反馈 | @keyframes card-pop:关键帧里自带 rotateY(180deg),配对瞬间弹一下又不破坏翻转姿态 |
配套的逻辑加固(pages/play/play.js):
- 状态写入从「就地 mutate
this.data.cards后整表setData」改为路径式增量写入setData({ 'cards[3].flipped': true }),配对时只下发那两张牌; - 回翻定时器挂到实例字段
this.flipTimer,在onUnload与initMemory里都clearTimeout—— 旧定时器持有旧牌面的引用,落到新一局上会把新牌覆盖回旧牌; - 配对成功时显式保持
flipped = true,并与模板层的card-open = flipped || matched一起构成双保险。
防回归:
node tests/play-test.js(106 断言)—— 逻辑 + 样式静态守卫: 3D 容器相关的规则块里不得出现opacity/filter/mask,.card-matched不得自带transform,关键帧必须含rotateY(180deg);node tests/memory-preview.js—— 用真实的play.wxss离线渲染三种牌面, 用elementFromPoint判断每张牌中心实际显示的是图案还是问号 (matchedShowingQuestion必须为 0),并检查 4×4 牌阵是否溢出。
3.13 同词相遇 · AI 复盘弹窗(云端 LLM 流式接入)
需求原文:「将每轮猜词的结果后面加一个详情按钮接入 ai 大模型,玩家点击后弹窗分析两个玩家的思考过程,简要输出玩家的想法」。
3.13.1 整体链路
往轮回顾 / 相遇之路 每一行
└─ 详情按钮 (bindtap="onShowAnalysis" data-round="{{item.round}}")
│
▼
utils/wordai.analyzeRound() ──► cloud.llm.chat.completions.create({ stream: true })
│ │
│ onDelta(累积全文) │ SSE 增量 chunk
▼ ▼
pages/wordmeet/room.js ──setData──► 弹窗正文「长出来」
云端 LLM 只支持流式(SDK 对 stream: false 直接拒绝),所以没法等全文再一次性渲染。
utils/wordai.js 用 onDelta(fullText) 回调把累积后的全文推给页面,
页面用 setData({ analysisText }) 更新,视觉上就是文字一段段长出来。
3.13.2 模块划分:纯函数与运行时分离
utils/wordai.js 把「能单测的逻辑」和「要跑在云上的逻辑」分开:
| 纯函数(Node 可直接测) | 运行时 |
|---|---|
buildMessages(input) 构造 system + user 两段 prompt |
resolveModel() 拉模型目录(带缓存) |
pickModel(models) 便宜/快的小模型优先,排除纯向量模型 |
cloud.llm.chat.completions.create() |
fallbackAnalysis(input) 大模型挂掉时的本地兜底 |
SSE 增量消费 |
appendDelta(text, chunk) / tidy(text) 累积与收尾 |
超时控制(25s) |
createAbortController() 最小可中断信号 |
模型挑选策略:复盘只要一百多字,没必要动用旗舰推理模型。
pickModel 按名字(flash|lite|mini|turbo|air|small|nano)给便宜模型加分,
把 modalities.output 不含 text 的纯向量模型排掉,同分保持目录原顺序(结果稳定)。
兜底不可省:模型目录拉不到、请求超时、额度用尽、流中断 —— 任何一种失败
都回落到 fallbackAnalysis() 生成的本地词面分析(找两个词的共有字、
字数节奏是否接近),并在弹窗底部诚实标注
「大模型暂时不可用,这是根据词面生成的简版复盘」。绝不允许白屏或一句「分析失败」。
3.13.3 三个容易踩的坑
坑 1:scroll-into-view 的值不变就不会再次触发滚动。
scroll-view 的 scroll-into-view 属性只有在值发生变化时才会重新滚动。
流式输出时正文一直变长,如果 scroll-into-view 固定写死 analysis-end,
只有第一次会滚到底,后面所有增量都停在原地。
解决:用两个锚点 id 交替。
<scroll-view class="analysis-body" scroll-y scroll-into-view="{{analysisAnchor}}">
<text class="analysis-text">{{analysisText}}</text>
<view id="analysis-end-a"></view>
<view id="analysis-end-b"></view>
</scroll-view>
this.analysisAnchorSeq = (this.analysisAnchorSeq + 1) % 2;
this.setData({ analysisText: partial,
analysisAnchor: this.analysisAnchorSeq ? 'analysis-end-b' : 'analysis-end-a' });
⚠
analysisAnchorSeq必须挂在实例上(this.),不能只放data里。 放错位置会导致undefined + 1 = NaN,NaN % 2仍是NaN, 三元判断恒为假 → 锚点永远是同一个 id → 滚动彻底失效,且不报任何错。
坑 2:关掉弹窗后请求还在跑,白烧 token。
只用「令牌」拦住迟到的 setData 是不够的 —— 回调是不写了,
但底层的 wx.request 还在流式接收,模型仍在生成、仍在计费。
cloud-sdk 的 chat.completions.create() 支持 signal 参数,
小程序端会转成 task.abort() 真正掐断请求:
// lib/miniprogram.js
init?.signal?.addEventListener("abort", () => { task.abort(); ... });
而 SDK 只用到 signal 的两个成员(aborted + addEventListener),
不需要平台提供 AbortController —— 小程序运行时不保证有这个全局对象,
所以 wordai.createAbortController() 自己实现了一个最小信号:
function createAbortController() {
const listeners = [];
const signal = {
aborted: false,
addEventListener(type, fn) { if (type === 'abort') listeners.push(fn); },
removeEventListener(type, fn) { /* ... */ },
};
return { signal, abort() { /* 置位并逐个调用监听器 */ } };
}
页面侧三处都要 abort:关闭弹窗、切换轮次、页面卸载。
abortAnalysis() {
if (this.analysisAbort) { this.analysisAbort.abort(); this.analysisAbort = null; }
}
analyzeRound 收到已中止的信号时返回 { source: 'cancelled' },
不走本地兜底(玩家都关窗了,没必要再弹一段文字),并且不进缓存
(半截文本不算结果,重新点开应该重新生成)。
坑 3:同一轮反复点「详情」会重复烧 token。
this.analysisCache[round] 按轮次缓存 { text, source },
第二次点开直接读缓存返回,不再发起请求。
3.13.4 成本与体验的取舍
| 决策 | 取值 | 理由 |
|---|---|---|
| 输出长度上限 | MAX_OUTPUT_CHARS = 220 |
复盘要「简要」,越长越没人看,也越费 token |
max_tokens |
420 | 够写三段短文,不够它发挥 |
temperature |
0.8 | 要一点发散度才能「猜」出思路,纯 0 会写得很套路 |
| 超时 | 25s | 超时回落本地兜底,不让弹窗一直转圈 |
| 缓存粒度 | 按轮次 | 一局游戏通常 5~15 轮,每轮一次调用是合理上限 |
3.13.5 防回归
node tests/wordai-test.js(104 断言)—— 覆盖 prompt 构造、模型挑选、 本地兜底、流式累积与长度截断、可中断信号的行为, 以及页面级用例:点详情→弹窗打开→流式交替锚点→关闭弹窗→请求被中断→ 不进缓存→迟到回调不再写界面。node tests/wordmeet-preview.js—— 用真实的room.wxss离线渲染房间页 + 弹窗, 自动量:详情按钮是否与词语同行、是否溢出卡片、弹窗是否居中且宽度贴合屏幕、 正文是否溢出、两个滚动锚点是否存在。
⚠ 离线预览的 headless 视口宽下限约 500px,而
.analysis-mask是position: fixed, 会铺满整个视口 → 弹窗宽度会被量成 490px。预览页里要显式收成 375px 才等于真机。
3.14 记忆翻牌的双人模式(同屏轮流)
需求原文:「记忆翻牌小游戏需要支持单人和双人一起玩,单人游戏时按照当前逻辑即可, 双人游玩每个人翻两次相同则计分,然后再次翻两次,如果不相同则不加分,该另一个玩家开始翻牌」。
3.14.1 规则对照
单人和双人共用同一张牌桌、同一套 initMemory,只是多了一个状态机:
| 单人 | 双人 | |
|---|---|---|
| 计分 | 不记分,只记用时 + 翻牌次数 | 双方各记配对数,8 对分完比总分 |
| 翻对 | 继续翻 | 当前玩家 +1 分,继续由他翻(可连击滚雪球) |
| 翻错 | 两张牌回翻 | 两张牌回翻,不加分,换另一位玩家 |
| 结束 | 8 对全配对 | 同左,弹窗显示比分与胜者(平局单独文案) |
3.14.2 状态与时序
data.mode 'solo' | 'duo' 切换即重开一局
data.players [{name:'玩家1',score:0}, {name:'玩家2',score:0}]
data.current 0 | 1 当前该谁翻(仅 duo 有意义)
data.switching false | true 翻错后、牌回翻前的空档
翻错的完整时序:
第二张牌翻开 → 图案不同
├─ locked = true 阻止下一位在上一位的牌还开着时点
├─ switching = true HUD 显示「没配上,换手中…」(中性灰)
└─ 750ms 后(与回翻共用同一个定时器)
├─ 两张牌 flipped = false
├─ current = 1 - current ← 换手
├─ switching = false
└─ locked = false
换手必须放在回翻之后,不能翻错就立刻切:下一位玩家接手时牌面已经回到背面, 不会看到半开的两张牌,也不会误点到正在翻的牌。
翻对不换手:current 原样保留 —— 这正是「翻两次相同则计分,然后再次翻两次」
的玩法核心,同一位玩家可以连着翻对一路加分。
3.14.3 实现要点
- 模式切换即重开:
onSwitchMode→setData({ mode })→initMemory()。 否则会带着上一个模式的进度(单人已配掉 5 对)进双人局。 - 分数用路径写入:
setData({ ['players[' + current + '].score']: n }), 既不重建players数组,也不整表重发cards。 - 只清分数不清名字:
initMemory里写的是players[0].score: 0,name保持不变。 - 结果浮层改为动态字段:
resultEmoji/resultTitle/resultText。 ⚠finishReaction也必须写这三个字段,否则反应大挑战的浮层会变成空白。 - 首次切到双人弹一句 toast 交代规则,省得两人对着屏幕猜。
3.14.4 界面
- 牌桌上方一行「单人 / 双人」胶囊切换,当前模式蓝底白字。
- 双人时 HUD 换成左右两个比分卡 + 中间 VS,当前该谁翻就让谁的卡片变浅蓝底 + 蓝边框。
⚠ 不要用
opacity表达非当前玩家:文字会发灰、对比度掉下来, 而且这套页面里有 3D 翻转容器,opacity在本项目是敏感属性(见 §3.12)。 - 比分卡下面一行:「轮到 玩家X 翻牌」胶囊 + 「还剩 N 对」小字; 换手空档时胶囊变灰、文案变「没配上,换手中…」。
3.14.5 防回归
node tests/play-test.js 从 48 断言扩到 106 断言,新增 58 条覆盖双人:
- 默认单人;切双人重开、玩家1 先手、比分归零;非法 mode 值被忽略
- 翻对给当前玩家加分且不换手;连续翻对仍是同一人
- 翻错不加分、
switching/locked中间态、换手发生在回翻之后 - 换手后玩家2 的配对计到玩家2 头上,玩家1 不再得分
- 全部配完的结算、平局、玩家2 获胜、翻牌总数展示
- 切回单人把牌面和比分一起清空
- 双人配对时只写
players[i].score路径,不重建整张牌桌 - 模板/样式静态守卫:模式切换、比分条、换手提示、结果浮层三个动态字段
反向验证(确认测试真能抓住规则退化):
| 注入的缺陷 | 结果 |
|---|---|
翻错不换手(patch.current = that.data.current) |
5 条 FAIL |
| 翻对也换手(模拟「每次翻完都换人」的误读) | 6 条 FAIL |
node tests/memory-preview.js 扩展成同时渲染单人与双人两块牌桌,自动量:
模式按钮是否同一行 / 是否溢出行宽、两个比分卡是否同高同基线、
「轮到谁」与「还剩几对」是否同一行、4×4 牌阵是否被挤出页面。
实测双人块:按钮总宽 144px、比分卡 120px、各项溢出均为 -16px(有余量),
matchedShowingQuestion = 0。
3.15 记忆翻牌的联机对战(各用手机 + 服务端权威 + 牌面脱敏)
需求原文:「要求可以邀请好友一起在线翻牌,而不是在同一台手机上操作」。
§3.14 做的双人是同屏轮流:一台手机、两个玩家、一个 setData 状态机。
联机版把这条链路整个换掉——两个玩家两台设备,谁都不能信任谁的客户端。
3.15.1 三个必须解决的新问题
| 问题 | 同屏双人 | 联机 |
|---|---|---|
| 牌在哪 | 客户端 shuffle() 出来的 |
必须服务端洗,否则先翻的人能看到对手牌的排列 |
| 谁决定得分/换手 | 客户端自己算 | 服务端算,否则改内存就能刷分 |
| 翻错那 1 秒的停顿 | 本地定时器 | 两边都要看到这两张牌,由谁喊「回翻」 |
结论:照搬斗地主那套「服务端权威 + 乐观锁」,客户端退化成「发指令 + 渲染」。
3.15.2 数据表与函数(cloud/memory.sql)
memory_rooms (
id, owner_id, owner_name, room_code, joiner_id, joiner_name,
status -- waiting / playing / finished
turn -- 'a' 房主 / 'b' 加入者
score_a, score_b,
deck -- 16 个 0..7 的整数(每样两张),⚠ 从不直接下发
matched -- 16 个 0/1
open_one -- 本回合已翻开、还在等配对的那一张
pending_a/b -- 翻错的一对(等 1 秒后回翻)
reveal_until -- 这对牌最早可以回翻的时刻
serial -- 乐观锁版本号
flips -- 累计翻牌次数
)
| 函数 | 作用 |
|---|---|
memory_create(name) |
建房:4 位房间号(冲突自动换号)+ 服务端洗牌 |
memory_find(code) |
按房间号找等待中的房间 |
memory_peek(id) |
房间概况,不含任何牌面——好友点分享进来时判断能否加入 |
memory_join(id, name) |
加入;同一个人重复调用幂等,房主自己调用直接返回 a |
memory_state(id) |
脱敏状态(唯一的读法) |
memory_flip(id, index, serial) |
翻一张 |
memory_settle(id, serial) |
回翻 + 换手,幂等 |
memory_reset(id) |
房主再来一局 |
memory_my_rooms() |
大厅恢复用 |
memory_selftest() |
18 条自检(洗牌构成/随机性/整局/脱敏/时序/非法操作) |
授权是这套设计的关键:
ALTER TABLE public.memory_rooms ENABLE ROW LEVEL SECURITY;
-- 不建任何策略,并且连 PUBLIC 一起 REVOKE
REVOKE ALL ON public.memory_rooms FROM PUBLIC, anon, authenticated;
REVOKE ALL ON SEQUENCE public.memory_rooms_id_seq FROM PUBLIC, anon, authenticated;
-- 只放行函数
GRANT EXECUTE ON FUNCTION public.memory_flip(bigint, integer, integer) TO anon, authenticated;
⚠ 这里比斗地主的做法更严一层:斗地主允许客户端直接 SELECT ddz_rooms(靠 RLS 限定行),
记忆翻牌的牌就存在这行里,行可见就等于牌可见,所以只能把表整个关掉,读写全部走函数。
实测确认(has_table_privilege / has_function_privilege):
| 检查 | 结果 |
|---|---|
anon 对 memory_rooms SELECT / UPDATE |
false |
anon 执行 memory_flip / memory_create |
true |
anon 执行 memory_state_internal / memory_selftest |
false |
3.15.3 「看不见的牌」怎么做到
memory_state_internal() 是唯一的出口,只放行三类位置,其余一律返回 null:
visible := (matched[i] = 1) -- 已配对,图案要一直留着
OR (open_one = i) -- 本回合自己翻开的那张
OR (pending_a = i OR pending_b = i); -- 翻错的一对,两边都要看见
于是 state.symbols 长这样:
[null, null, 3, null, ...] // 只有第 2 张是真值,其余全 null
客户端 utils/memorygame.js 拿到后做投影:null → 背面问号,0..7 → 🍎🍋🍇🍓🥕🌽🍄🌰。
三个副作用值得记一笔:
- 刷新页面不丢牌:
open_one也算「可见」,重进房间时自己刚翻开的那张还在。 - 牌序不会泄露:即使有人在控制台里打印整个
state,也只有已经亮出来的那几张。 - 重开一局换新牌:
memory_reset重新memory_shuffle(),旧牌序直接丢弃。
3.15.4 回翻与换手:谁是裁判
同屏版是「本地 750ms 定时器」。联机版不能这么做——两边各有一个定时器会互相打架。
服务端只在翻错时记下 pending_a/b 与 reveal_until = now() + 1s,自己不推进。
到点后由任意一方调 memory_settle() 完成「清 pending + 换手 + serial+1」:
房主翻错 → pending=[4,5], reveal_until = now+1s
├─ 两边轮询都能看到这两张牌亮着(symbols[4]/[5] 有值)
└─ 到点后两边都可能调 memory_settle
├─ 先到的:pending → NULL,turn 取反,serial+1
└─ 后到的:pending 已经是 NULL → **直接返回当前状态**,不报错
幂等判断放在 serial 校验之前,否则后到的一方会因为 serial 已变而被拒:
IF r.pending_a IS NULL THEN -- 对方先结算了
RETURN memory_state_internal(p_room_id, uid);
END IF;
IF p_serial IS DISTINCT FROM r.serial THEN RAISE EXCEPTION '牌桌已更新,请刷新'; END IF;
IF now() < r.reveal_until THEN -- 时间没到,再等等
RETURN memory_state_internal(p_room_id, uid);
END IF;
3.15.5 客户端时序(pages/memory/room.js)
onShow → ensureSession → peek
├─ 已在房里 → 立刻 tick()(不等第一个轮询周期)
├─ 未加入 + waiting → 「加入牌桌」页
└─ 未加入 + playing/finished → 明确告知原因
tick(900ms,结束后放慢到 3000ms)
├─ 正在提交翻牌 / 正在结算 → 直接跳过
│ (否则轮询会把乐观翻开的牌又打回背面,出现闪烁)
├─ getState → applyState(增量 setData)
└─ pending 且 revealLeft > 0 → scheduleSettle(revealLeft + 60ms)
└─ 一次性定时器到点再 settle,比干等轮询跟手
乐观翻牌:点击瞬间先把这张牌翻过来(此时还不知道图案 → 显示一个呼吸圆点),
RPC 回来后用服务端状态覆盖;失败则回滚这张牌并 tick() 重新对齐。
⚠ 占位动画只用 transform: scale + background-color 做,不用 opacity——
它在 3D 翻转卡片内部,项目里已经踩过一次 opacity 毁掉 preserve-3d 的坑(§3.12)。
3.15.6 入口与页面
| 位置 | 行为 |
|---|---|
| 游戏详情「开始游戏」 | 记忆翻牌改为进 pages/memory/lobby(与同词相遇/斗地主一致) |
| 大厅 | 创建房间(4 位房号)/ 输房号加入 / 我的进行中房间 / 先自己练两把 |
| 大厅「先自己练两把」 | 回到 pages/play/play?id=memory,单人 + 同屏双人原样保留 |
| 本机玩法页顶部 | 新增浅蓝色「和好友各用手机玩」入口;若上一页就是大厅则 navigateBack 回去,不叠页面 |
| 牌桌页 | 等人时 open-type="share" 直接发邀请;分享 path 带 ?id=,好友点开即进「加入牌桌」 |
| 结算 | 房主有「再来一局」,加入者提示「房主点再来一局后自动进入下一局」;房主重开后加入者靠轮询自动进入 |
3.15.7 踩坑与验证
| 坑 | 现象 | 做法 |
|---|---|---|
left 是 SQL 保留字 |
syntax error at or near "left" |
变量改名 left_n |
jsonb_each_text 只能喂对象 |
cannot call jsonb_each_text on a non-object |
数组用 jsonb_array_elements_text(...) WITH ORDINALITY |
集合返回函数在 ORDER BY 之后才展开 |
洗牌永远是同一副(见 §3.9) | 先在子查询里展开成 16 行再排序聚合 |
| 加入房间后卡在「加入牌桌」 | tick() 在 viewState==='join' 时直接 return,加入成功后没人再拉状态 |
onJoin 里先 setData({viewState:'loading'}) 再 tick() |
| 轮询把乐观翻牌打回背面 | 翻牌后一瞬间卡片又合上 | tick() 在 submitting/settling 时跳过 |
| 匿名令牌同一个人 | Node 端到端用两个 storage 拿到的是同一个 uid | 双人真机链路只能真机验;云端自检用 set_config('request.jwt.claim.sub') 伪造两个身份 |
验证:
- 云端
memory_selftest()—— 18/18 PASS:牌堆构成(16 张 / 0..7 各两张)、 洗牌确实随机、整局 8 对配完且房主 8 分对手 0、脱敏(新房间 0 张可见、翻一张只露一张、 回翻后重新藏起来)、翻错不立即换手、时间到才换手、非本回合/陈旧 serial/重复点同一张全部被拒、 重开清零并重新洗牌。 node tests/memory-room-test.js—— 101 断言:投影、可点判定、提示语、结算文案、 增量setData、只走 RPC 不直连表、页面静态守卫、以及一条按服务端契约走的脚本化对局。node tests/memory-preview.js—— 新增tests/_preview/memory-online.html, 用真实的room.wxss渲染联机牌桌,实测matchedShowingQuestion = 0、4 行牌阵、各项溢出 -16px、占位动画正常渲染。
反向验证(确认测试不是摆设):
| 注入的缺陷 | 结果 |
|---|---|
canTap 忽略 pending(回翻中仍可点牌) |
2 条 FAIL(B6 / G10) |
增量 setData 退回整表重建 |
3 条 FAIL(D1–D3) |
加入成功后不离开 join 界面 |
1 条 FAIL(F21) |
真机必须实测(云端自检过 ≠ 真机上过):两台设备同时翻牌的回合判定、 1 秒回翻的实际观感、弱网下 900ms 轮询的延迟、分享卡片唤起后的加入流程。
3.16 象棋的双方视角(执黑时棋盘转 180°,但字不倒)
需求原文:「小程序中下象棋的时候执黑棋的一方看到的界面是倒着的,请优化双方玩家的视角问题」
3.16.1 问题从哪来
引擎把红方摆在 rows[9](最下面一行),黑方在 rows[0];redraw() 又永远是「第 0 行画在最上面」。
红方看着正好,黑方坐在桌子对面,看到的是一屏倒过来的自己棋子 —— 这就是「倒着」。
直觉做法是给 canvas 加 transform: rotate(180deg),但那会把棋子上的「车马炮兵」和棋盘上的「楚河汉界」一起转成倒字,
等于把一个人的问题转嫁给另一个人。真正要做的只有一件事:换坐标,不转字形。
3.16.2 三个约定
| 约定 | 原因 |
|---|---|
| 只有象棋翻转 | 五子棋 / 围棋没有方位身份,棋盘 180° 旋转后与自己完全重合,翻了看不出任何差别,却会让「上一步 (7,4)」这类播报与对手对不上 |
| 180° 旋转自逆 | flipRC(flipRC(p)) === p,所以「逻辑 → 屏幕」和「屏幕 → 逻辑」共用同一个函数,少写一份就少一处写反的机会 |
| 只翻位置不翻字形 | 棋子字、河界文字由 fillText 画在屏幕坐标上,天然是正的;一旦改成 ctx.rotate,坐在下方的人就得歪头读棋 |
utils/boardview.js 只有五个小函数,纯函数无 canvas 依赖,可直接在 Node 里单测:
localSide(gameType, mode, role) // 我执哪一方:ai 恒为先手,好友模式 a=先手
needsFlip(gameType, side) // 只有 chess + 黑 → true
flipRC(r, c, rows, cols, flip) // 180° 旋转,自逆
flipIndex(p, n, flip) // 一维棋盘(五子棋/围棋)的下标旋转
sideName(gameType, side) // '红' / '黑' / '白',给文案用
3.16.3 页面里改了什么
pages/board/room.js 的 syncView() 是唯一决定视角的地方:
syncView() {
const side = view.localSide(this.gameType, this.mode, this.role);
const flip = view.needsFlip(this.gameType, side);
this.flip = flip;
this.mySide = side;
...
}
调用时机两处,都必须早于任何一次 redraw:
startAiGame()—— 人机局在开画布之前定视角(玩家恒执红,flip=false);loadRoom()—— 好友局在算出role之后、replayRoom()之前;并且把syncView()的返回值并进重绘条件, 万一视角变了但着法数没变,也要重画一次。
四处绘制跟着翻(网格线不用动,因为 180° 旋转下线条与自己完全重合):
| 位置 | 处理 |
|---|---|
| 棋子 | drawChessPiece(ctx, m, q.r, q.c, piece),q 是屏幕格 |
| 选中圈 | 同上,从 this.selectedFrom 反算出屏幕格 |
| 最后一手方框 | 同上,从 lastMove.t 反算 |
| 楚河汉界 | 翻转后「汉界」落到左边,字仍是正的 |
落点判定 locate() 走的是同一条路:先落到屏幕格,再用同一个 flipRC 翻回逻辑格。
画和点用同一个函数,就不会出现「看到的是这匹马、点下去走的是对面那匹」。
3.16.4 文案
- 头部
mySideText给「你执红 / 你执黑」,执黑时额外挂一个己方在下的小标识 —— 免得玩家以为棋盘被摆错了。 - 加入页原来是写死的「你执白/黑方后行」,改为按棋种给:象棋「你执黑后行」,其他「你执白后行」。
- 「请先点选自己的棋子(红方)」也改成按
mySide取色,黑方不会再被提示去点红子。 - 信息条的「上一步 (行,列)」统一改成 1 起算、且跟自己看到的棋盘对齐(执黑时已翻转)。 顺手修掉了象棋这边原本 0 起算、与围棋不一致的老问题。
3.16.5 验证方式
纯断言不够 ——「字到底是正着还是倒的」必须眼睛看。所以加了 tests/board-preview.js:
把 redraw() 的 canvas 调用(fillRect/moveTo/lineTo/stroke/arc/fill/fillText/strokeRect)
翻译成 SVG,红黑两块棋盘并排输出一张 HTML/PNG。跑的是页面真实的 redraw,不是另写一份绘制代码。
| 测试 | 覆盖 |
|---|---|
tests/board-view-test.js(56 断言) |
自逆性、谁该翻、双方棋子方位(将/帅/兵/卒上下对调)、河界左右镜像、选中圈与最后一手跟随、落点镜像、执黑完整走子链路(触摸 → 选中黑炮 → 落子成功) |
| 反向验证 | 注入「locate 不翻」→ 10 条 FAIL;注入「棋子不翻」(还原原始 bug)→ 6 条 FAIL |
tests/board-preview.js |
红黑视角并排图,肉眼确认字都是正的 |
真机需确认:手指落点在有 1px 视觉误差时的容差(当前 0.45 步长)、以及执黑方看到「己方在下」标识是否足够醒目。
3.17 掷骰子 / 掷硬币(纯本地随机 + 大小与正反判定)
需求原文:「再添加一个掷硬币和骰子的小游戏,骰子可以选择骰子数量,掷成功后提示大小或正反」
3.17.1 为什么这次不走服务端
这是纯随机、没有对手、也没有隐藏信息的游戏。上服务端权威反而会引入延迟:摇一次要等一个 RPC 往返才能看到点数,手感立刻就废了。所以全部在本地算,utils/dicelib.js 是唯一的规则来源。
代价也要说清楚:结果可以被改过的客户端伪造。但这游戏既没有对手也没有奖励,骗自己没意义 —— 需要权威的场景(斗地主/棋类/联机翻牌)才值得付那笔延迟。
3.17.2 大小怎么判
判定线 = 颗数 × 3.5,也就是「均值线」:
| 颗数 | 小 | 平 | 大 |
|---|---|---|---|
| 1 | 1–3 | — | 4–6 |
| 2 | 2–6 | 7 | 8–12 |
| 3 | 3–10 | — | 11–18 |
| 6 | 6–20 | 21 | 22–36 |
偶数颗时中线是整数,会出现「正好压线」(2 颗总和 7 就是最常见的那个和),这里老老实实报「平」,不偷偷把它算进大或小 —— 一旦偷偷归类,大小两边概率就不等了。
测试用穷举守住这件事:n = 1..4 时「大」与「小」的组合数必须完全相等(2 颗各 15 种、4 颗各 575 种),而「平」只在偶数颗出现。
3.17.3 硬币怎么翻
不是每帧换图,而是 CSS rotateY + 累加角度:nextCoinAngle(current, result) 把当前累计角推到「0° = 正 / 180° = 反」,并额外加至少三圈,于是 transition 每次都真的转起来。
⚠ 角度必须累加,不能直接赋 0 / 180:直接赋值时,如果上一次正好停在 0°、这次又摇出正面 → 角度没变化 → 硬币一动不动,玩家只会以为按钮坏了。测试 A36 / B21 守着这条。
⚠ 揭晓结果的延时必须 ≥ transition 时长:COIN_SPIN_MS = 1100 vs WXSS 里 .coin 的 transition: transform 1.05s。反过来的话,文字会抢在硬币落地之前出现。测试 C11 交叉校验这两个数。
⚠ 3D 容器同样禁用 opacity / filter / backdrop-filter / mask / clip-path(与 §3.12 记忆翻牌那个坑同一个根因):一旦元素自成一组,preserve-3d 被强制扁平化成 flat,两面的 backface-visibility: hidden 就会误判朝向 —— 表现为「硬币两面同时消失」或「怎么翻都翻不过来」。测试 C5–C9 逐条守着。
3.17.4 骰面用手画,不用图
点位坐标写在 dicelib.PIPS(九宫格百分比),页面只把 left / top 塞进 style,圆点自己带 transform: translate(-50%, -50%),所以对齐的是点的中心而不是左上角 —— 否则 1 点和 6 点看起来会偏心。
这和 54 张扑克牌那套结论一致:不用位图就没有加载延迟,也不用管机型缩放。
摇的过程每 90ms 换一次随机骰面(DICE_TICKS = 8),最后一下才落定真实点数 —— 手感上是「在摇」,而不是点完干等。
版面高度是一条硬约束:骰子面板的内容自然高度约 503px(换成 6 颗是 509px、硬币 418px),
而 iPhone SE 的可用高度只有约 472px。所以 pages/play/play.json 的 disableScroll 必须保持 false ——
关掉滚动会把底部「最近 N 次」直接裁掉,而且玩家没有任何办法看到。
tests/dice-test.js 的 D12 就是守这一条的(有人为了「防误触」把滚动打开时它会立刻报错)。
3.17.5 验证
| 测试 | 覆盖 |
|---|---|
tests/dice-test.js(104 断言) |
数量夹取(0 / 99 / 小数 / 非数字)/ 点数范围与 6 个面全覆盖 / 大小判定(含 n=1..4 穷举对称性)/ 点位布局与「6 点是两列各三个」/ 硬币角度累加与每次精确落面 / 页面行为(摇骰动画 9 次落定、锁按钮、历史 8 条、动画中禁切玩法与改颗数、卸载清定时器)/ 3D 样式静态守卫 |
| 反向验证 | 判定线 > 改 >= → 5 条 FAIL;硬币角度改成直接赋值 → 3 条 FAIL;给 .coin 加 opacity → 1 条 FAIL |
tests/dice-preview.js |
用真实 play.wxss 渲染 3 颗 / 6 颗 / 硬币正反四块:量出 6 颗折两行不重叠、圆点不越出骰面、颗数选项同一行不溢出;并用 elementFromPoint 确认 0° 朝前的是正面(FRONT)、180° 朝前的是反面(BACK)—— 3D 一旦被扁平化,这里会判成 NONE |
真机需确认:硬币 1.05s 翻转的实际观感;6 颗骰子折成两行在 320pt 窄屏(iPhone SE)上是否还需要再缩一档。
3.18 房间拉取守卫(utils/roomguard,防「一次失败即踢人」)
问题现象:进入联机房间游玩时,会被「自动退出」到错误屏(提示房间不存在),且重进复现。
根因(三层叠加):
- 一次失败就永久判死:五个房间页(同词相遇 / 你画我猜 / 棋类 / 斗地主 / 联机翻牌)的拉取逻辑都是
if (error || !room)→ 停轮询 + 错误屏。网络抖一次、云函数冷启动超时一次就被踢。 - RLS 静默过滤把「未登录」伪装成「房间不存在」:房间表 SELECT 策略是
owner_id = auth.uid() OR joiner_id = auth.uid() OR status = 'waiting'。 会话临时失效时auth.uid()为 NULL → 行被过滤 → 客户端拿到data: null且无 error → 被当成「房间没了」。 - 坏会话不自愈:
app.js的sessionPromise只在登录时失败才重置;游戏进行中 token 失效不会触发重建, 重进房间用的还是坏会话 → 每次进都被踢,只有杀掉小程序重开才恢复。
修复方案(2026-11-19):
- 新增
utils/roomguard.js纯函数模块: classifyFailure(error, room)→'ok' | 'fatal' | 'retry':只有带房间上下文的明确业务语义(不存在 / 不在房间 / 已被关闭 / 已失效)才算fatal;data:null无 error(RLS 静默过滤)与网络类错误一律retry;healSession():resetSession()+ensureSession()重建会话(resolveSession内部 SDK 会带过期续签,不行再静默重签微信登录);- 阈值:
SESSION_HEAL_AT = 2(连续失败 2 次重建会话)、MAX_FAIL_STREAK = 3(3 次才判死,2 秒轮询下约 6 秒容错)。 - 五个房间页接线:非致命失败 → 保持当前画面与轮询、下一轮自然重试(首次失败 toast「网络不稳,正在重连…」);判死后错误屏新增「重试」按钮(走完整进入流程,自带会话兜底);
- 联机翻牌
peek()拆出applyPeek():进入时一次性失败先自愈会话重试一次,再判死; - 斗地主
loadState拆出handleLoadFailure():轮询失败保持轮询自愈,进入失败重试一次后判死。
验证:tests/roomguard-test.js(26 断言)钉死分类规则,含「本轮已结束,请刷新」这类普通轮次提示不得误判为致命(致命词必须带房间上下文)。
四、部署与发布步骤
4.1 阶段一:发布前自检(本地)
cd "D:/mycodes/MyApp/vx/wordsMeeting/gamehub"
# 1) JS 语法检查
for f in app.js utils/cloud.js utils/wordroom.js utils/store.js \
data/games.js pages/index/index.js pages/detail/detail.js \
pages/play/play.js pages/profile/profile.js \
pages/wordmeet/lobby.js pages/wordmeet/room.js \
pages/draw/lobby.js pages/draw/room.js utils/drawroom.js data/drawwords.js; do
node --check "$f" && echo "OK $f"
done
# 2) JSON 合法性与页面文件完整性
node -e "const fs=require('fs');const app=JSON.parse(fs.readFileSync('app.json','utf8'));
const miss=[];app.pages.forEach(p=>['wxml','js','json'].forEach(e=>{if(!fs.existsSync(p+'.'+e))miss.push(p+'.'+e)}));
console.log(miss.length?'MISSING: '+miss.join(','):'PAGES OK');"
# 3) 依赖存在性
node -e "console.log(require('./package.json').dependencies)"
# 4) 回归测试 + 工程静态校验(新增,建议每次改动都跑)
node tests/board-test.js # 棋类规则回归(30 断言)
node tests/board-view-test.js # 棋类双方视角回归(56 断言:自逆性、双方绘制方位、落点镜像、执黑完整走子链路)
node tests/ddz-test.js # 斗地主回归(286 断言,含手牌一行铺满布局、洗牌随机性、拖动连选手势、自动选牌与放大预览带)
node tests/play-test.js # 记忆翻牌·本机回归(106 断言,含单人/双人规则、配对后图案保留、回翻时序、3D 翻转样式的静态守卫)
node tests/dice-test.js # 掷骰子/掷硬币回归(104 断言,含数量夹取、大小判定穷举对称性、点位布局、硬币角度累加、3D 样式守卫)
node tests/memory-room-test.js # 记忆翻牌·联机回归(101 断言,含状态投影、可点判定、增量 setData、只走 RPC 的静态守卫、脚本化对局)
node tests/wordai-test.js # 同词相遇 AI 复盘回归(104 断言,含 prompt 构造、模型挑选、本地兜底、流式累积、可中断信号、页面级中断接线)
node tests/validate.js # 静态校验(482 断言:JS/JSON/WXSS/页面/事件/禁用 API/发布包体积)
# 5) 发布包体积自查(发布前必跑,超 2MB 微信会报 errcode 80051)
node tests/ddz-pkgsize.js # 快速估算:复刻发布通道的 ignore 规则,输出各目录占比
node tests/mp-publish-verify.js # 端到端:用 WorkBuddy 内置的真实 miniprogram-ci 打包并实测体积
# 两者都会在超过 2MB 时以非 0 退出码失败,可直接接入 CI
# 6) 仿真牌桌视觉走查(可选,生成离线预览页)
node tests/ddz-preview.js # 输出 tests/_preview/ddz-table.html(默认 20 张手牌)
node tests/ddz-preview.js 20 4 14 # 可传参:手牌张数 / 拖动起点 / 拖动终点
node tests/ddz-preview.js 20 4 14 nosel # 追加 nosel = 预览「未选牌」状态
# 预览页内嵌了自动测量脚本(#measure),用 Chrome --dump-dom 可直接读出:
# · overflowsPage / lastCardRight —— 手牌是否溢出页面;
# · preview.overlapsHand —— 放大预览带是否压到了手牌行(必须为 false);
# · cornerCoveredCount —— 有几张手牌的点数角标被邻牌盖住(必须为 0);
# · drag.hitFrom / hitTo / selected —— 用**真实 DOM 矩形**跑一次拖动连选模拟。
# 注意 Chrome headless 窗口宽下限约 500px,测量要以 .page(375px) 左边缘为基准;
# 窗口高度不足 700px 时角标会落在视口外(elementFromPoint 返回 null),需 --window-size=520,1400。
node tests/memory-preview.js # 输出 memory-table.html(本机单人/双人牌桌)与 memory-online.html(联机牌桌)
node tests/dice-preview.js # 输出 dice-board.html(3 颗 / 6 颗骰子 + 硬币正反四块)
# 骰子预览的 #measure 会量出:6 颗是否折两行且不重叠、圆点是否画出骰面、
# 颗数选项是否同一行,以及 elementFromPoint 命中的硬币是哪一面(0°→FRONT、180°→BACK)。
# ⚠ 四块面板叠起来超过 1500px,--dump-dom 时窗口高度要给到 2800,否则底部面板
# 落在视口外,elementFromPoint 返回 null 会误报「硬币两面都没显示」。
# 预览页用**真实的 play.wxss** 渲染三种牌面(未翻开 / 翻开未配对 / 已配对),
# 并用 elementFromPoint 判断每张牌中心**实际显示的是图案还是问号**:
# · matchedShowingQuestion —— 已配对却仍显示问号的张数(必须为 0);
# · gridOverflows —— 4×4 牌阵是否溢出容器。
# 离线 HTML 里 <view>/<text> 是未知标签,必须重置成 display:block,
# 且 <pre> 测量容器要 display:none,否则长 JSON 会撑宽 body 让量出来的排版失真。
node tests/wordmeet-preview.js # 输出 tests/_preview/wordmeet-room.html(同词相遇房间页 + AI 复盘弹窗)
# 预览页用**真实的 room.wxss** 渲染往轮回顾与详情弹窗,自动量:
# · detailOnSameLine —— 详情按钮是否与词语同一行(与词的垂直中心比,不是与行顶比);
# · detailOverflows —— 详情按钮是否溢出卡片右边界;
# · modal.cardFitsPage / centeredX —— 弹窗是否居中且宽度贴合 375px 页面;
# · textOverflowsCard —— 复盘正文是否溢出弹窗;
# · anchors —— 两个滚动锚点是否存在。
# ⚠ .analysis-mask 是 position:fixed,headless 下会铺满 500px+ 视口,
# 预览页必须显式收成 375px,否则量出来的弹窗宽度是假的。
发布前人工确认清单
- [ ] 首页分类/标签筛选正常,卡片数据正确
- [ ] 详情页评论可发表、分享卡片标题与路径正确
- [ ] 记忆翻牌(单人 / 同屏双人 / 联机房间)、反应大挑战可玩并写入历史记录
- [ ] 掷骰子:颗数 1–6 都能选,摇完给出「大 / 小 / 平」且与点数总和一致(2 颗出 7 点必须显示「平」)
- [ ] 掷硬币:每次点击硬币都真的转起来,落地后「正 / 反」与硬币朝上那面一致
- [ ] 象棋联机:房主执红(红在下)、加入者执黑(黑在下,棋子字正立,头部有「己方在下」标识)
- [ ] 象棋执黑方点自己下方的棋子能选中,落子位置与手指一致(不会差 180°)
- [ ] 联机翻牌:两台设备建房→分享→加入→轮流翻牌→结算→房主重开,全程走一遍
- [ ] 同词相遇:创建房间 → 分享 → 好友加入 → 双方提交 → 结算,历史回看正确
- [ ] 「我的」昵称、历史记录、清空功能正常
- [ ] 清理预览期产生的测试数据(预览版与已发布版共用同一套云服务,测试房间会进入正式数据)
- [ ] 隐私保护指引已在
.wbapp_*.privacy.json声明,并与微信后台填写内容一致 - [ ]
node tests/ddz-pkgsize.js与node tests/mp-publish-verify.js均通过(包体积 < 2MB)
4.2 阶段二:注册 / 绑定小程序账号
| 方式 | 前置条件 | 适用场景 | 说明 |
|---|---|---|---|
| 试用小程序 | 无(微信扫码即可) | 快速体验、临时分享给朋友 | 扫码即建即用;有有效期(以面板显示日期为准);不支持直接转正式版 |
| 绑定已有小程序 | 已注册的小程序账号 + 管理员微信 | 长期运营 | 可发布体验版、提交正式版审核 |
注册正式小程序的步骤
- 浏览器打开 https://mp.weixin.qq.com →「立即注册」→「小程序」;
- 准备一个从未注册过公众平台账号的邮箱(一个邮箱只能注册一个账号);
- 选择主体:个人(身份证 + 手机号,免费;无法开通微信支付、部分类目受限)或企业(需营业执照);
- 邮箱激活 → 主体信息登记 → 完成注册;
- 登录后在「设置 → 基本设置」获取 AppID;
- 回到 WorkBuddy「分享」面板 → 绑定已有小程序 → 用该小程序管理员微信扫码授权。
注意:微信公众平台一个微信最多可绑定若干账号(含小程序、小游戏、公众号),绑定弹窗里出现「测试号」「已冻结」的账号都无法用于发布。
4.3 阶段三:在 WorkBuddy 内发布(全程无需手工上传代码包)
- 打开预览:点击对话中的「小游戏乐园」应用卡,进入预览面板;
- 点击「分享」:面板右上角分享图标(位于刷新和「…」的左边);
- 选择方式:试用小程序(扫码创建)或绑定已有小程序(扫码授权);
- 执行发布:分享面板按版本分行显示状态 —— 试用版 / 体验版 / 正式版;
- 取小程序码:对应版本行显示「已发布」后,悬停该行最右侧二维码图标,弹出小程序码,可「复制」或「下载」,微信扫码即可打开并发给好友;
- 提交审核(正式版):在微信公众平台提交审核,通过后发布。
面板还提供:
- 「更新」:代码改动后重新发布(改完不会自动同步线上,务必点一次);
- 「解绑」:更换绑定的小程序账号。
4.4 阶段四:版本更新流程(日常迭代)
改代码 → 本地静态校验 → 保存文件 → 预览面板点「更新」发布 → 取新码 → 通知好友
预览版与正式版共用同一个 applicationId(wbapp_ybUCXOWtc9v5IgfbOqHymv)与同一套云服务,重新注册应用会破坏 Origin 绑定导致云登录失效,务必复用既有 applicationId。
4.5 阶段五:云服务额度与数据运维
| 事项 | 入口 / 做法 |
|---|---|
| 查看资源点用量 | 应用预览 → 标题旁「云服务」;或 设置 → 数据管理 → 应用 → 云服务图标 |
| 查看套餐与 AI 积分 | https://www.workbuddy.cn/ → 右上角头像 → 个人中心 → 套餐与用量 |
| 导出数据库 | 云服务管理页 → 数据库 > 数据 → 选中表 → 导出 CSV |
| 额度用尽 | 云服务自动暂停;升级会员或等待下个周期刷新自动恢复(暂停期间数据保留 30/60 天) |
| 释放云服务名额 | 删除不再使用的应用(关联数据、文件、注册用户一并永久删除,不可恢复) |
各会员版本额度:
| 会员版本 | 可开启云服务的应用数 | 单应用每月资源点 |
|---|---|---|
| 体验版 | 10 | 5,000 |
| 标准版 | 30 | 25,000 |
| 高级版 | 50 | 50,000 |
| 旗舰版 | 99 | 150,000 |
4.6 阶段六:上线验证清单(真机 / 体验版)
预览环境无法完成真实微信登录,双人联机必须用体验版或正式版在真机上验证:
- [ ] 打开小程序即自动登录(大厅直接显示「创建房间 / 加入房间」,不出现登录按钮)
- [ ] 微信登录成功(大厅显示已登录)
- [ ] 关闭小程序后重新打开,仍是已登录状态(会话被复用,无需重新授权)
- [ ] 创建房间生成 4 位房间号,好友可用房间号加入
- [ ] 分享卡片点击后直达对应房间(
/pages/wordmeet/room?id=xxx) - [ ] 双方各自提交词语后,2 秒内互相可见
- [ ] 词语不同 → 自动进入下一轮,历史回看正确
- [ ] 词语相同 → 结算页展示共同词语与总轮数,可分享战绩
- [ ] 战绩写入「我的」历史记录
- [ ] 你画我猜:画手选题后猜手只能看到字数,画手能看到完整答案
- [ ] 画手作画、换色、撤销、清空后,猜手端在 2 秒内同步画布
- [ ] 猜手提交正确答案后自动揭晓并加分,下一局双方角色互换
- [ ] 非当前画手直接请求
draw_secrets时被 RLS 拒绝 - [ ] 退出后从大厅可恢复进行中的房间
- [ ] 非参与者访问他人房间时被 RLS 拒绝
- [ ] 斗地主:选择人数后规则文案随之变化(双人文案含「随机去掉 17 张」)
- [ ] 斗地主:创建房间生成 6 位房间号,好友可用房间号加入;房主可直接开局
- [ ] 斗地主:轮流叫分,叫 3 分者当地主并领到底牌;底牌领到后公开展示
- [ ] 斗地主:出牌后 1.5 秒内其他玩家可见上一手;管不上时服务端拒绝并提示
- [ ] 斗地主:「提示」能给出能管上的牌,「不出」后轮次正确流转
- [ ] 斗地主:非当前回合出牌 / 用过期
epoch_serial出牌均被服务端拒绝 - [ ] 斗地主:双人局实际只发 37 张牌(17+17+3),三人 54 张,四人 54 张
- [ ] 斗地主:结算页展示胜负、得分与炸弹倍数,炸弹后分数翻倍
- [ ] 斗地主:牌桌背景铺满全屏且不遮挡操作栏;背景细节清晰可见(不是一团糊);牌面为仿真扑克牌(点数 + 花色 + 中央大花色)
- [ ] 斗地主:手牌一行铺满,无需横向滑动;20 张(地主满手牌)时首尾两张都完整可见、不出血
- [ ] 斗地主:每张牌左上角的点数与花色都能读清,没被右边相邻的牌盖住
- [ ] 斗地主:选中的牌抬起且不被相邻牌遮挡
- [ ] 斗地主:按住某张牌横向拖动 → 一次连选一整段(左右方向都有效)
- [ ] 斗地主:按住已选中的牌拖动 → 整段取消选中;轻点单张仍然只切换那一张
- [ ] 斗地主:拖动选牌时页面不会跟着滚动(
catchtouchmove生效) - [ ] 斗地主:连开两局,发到的牌不一样(验证服务端洗牌随机性)
- [ ] 斗地主:对手席位显示头像色块、剩余张数与牌背堆叠,地主有皇冠标记
4.7 常见问题排查
| 现象 | 可能原因 | 处理 |
|---|---|---|
发布报 errcode 80051 / source size ... exceed max limit 2MB |
代码包超 2MB 主包上限 | 跑 node tests/ddz-pkgsize.js 与 node tests/mp-publish-verify.js;把大目录写进 project.config.json 的 packOptions.ignore(注意发布通道不读 .gitignore) |
| 绑定小程序时弹窗无可用账号 | 名下小程序均为测试号/已冻结 | 关闭弹窗,先用试用小程序;或注册正式小程序后再绑 |
| 注册提示「邮箱已注册」 | 邮箱被老账号占用 | 换新邮箱注册;或找回老账号解冻/注销(注销有 7 天冻结期) |
| 登录失败 | 微信登录开关未开 / 未绑定正式小程序 | 在应用管理的身份认证中开启微信登录;发布体验版后再试 |
| 房间创建失败 | 资源点耗尽或云服务暂停 | 查看云服务页面额度,升级或等待刷新 |
| 好友加入提示「已被加入」 | 房间已被第三人抢入 | 房主重新创建房间 |
| 云登录突然失效 | 应用被重新注册,Origin 变化 | 使用原 applicationId 重新发布,不要新建应用 |
4.8 发布失败专项排查:errcode 80051(代码包超限)
2026-11-05 实测踩坑记录,完整排查路径:
1. 拿到原始错误
WorkBuddy 的发布日志在 ~/.workbuddy/logs/renderer.log,检索:
grep -n "miniprogram:publish" ~/.workbuddy/logs/renderer.log | grep "publish failed"
输出形如:
[miniprogram:publish] publish failed applicationId=wbapp_... publishMode=experience
raw=小程序代码上传失败,请重试:upload failed: Error: {"errCode":-1,
"errMsg":"inner upload fail with errcode: 80051, errmsg: source …"}
2. 错误码含义
| 错误码 | 含义 | 硬指标 |
|---|---|---|
80051 |
source size XXX KB exceed max limit 2MB |
主包 ≤ 2MB;预览/真机调试 ≤ 4MB;整包(分包后)≤ 30MB,不可申请调大 |
3. 关键认知:发布通道只认 packOptions.ignore
WorkBuddy 的发布流程(MiniprogramPublishService)分四步:
assemble → 复制工程到临时目录,排除 node_modules / miniprogram_npm / .git
npm → packNpmManually 构建 miniprogram_npm(SDK 产物进包)
filter → 用 miniprogram-ci 的 packOptionsHelper 应用 project.config.json 的 packOptions.ignore
zip → 打包剩余全部文件上传
⚠ .gitignore 完全不参与。只在 .gitignore 里写 tests/ 是无效的,
必须在 project.config.json 的 packOptions.ignore 里显式声明:
{
"packOptions": {
"ignore": [
{ "type": "folder", "value": ".workbuddy" },
{ "type": "folder", "value": "tests" },
{ "type": "folder", "value": "cloud" },
{ "type": "folder", "value": "node_modules" },
{ "type": "suffix", "value": ".sql" },
{ "type": "suffix", "value": ".md" }
],
"include": []
}
}
规则语义与 miniprogram-ci/dist/utils/filerules.js 一致:
folder 按目录前缀匹配(value 写 tests 即匹配 tests/xxx),
file 精确匹配,suffix 按文件名后缀,prefix 按前缀,glob/regexp 走模式匹配。
4. 本次修复效果
| 修复前 | 修复后 | |
|---|---|---|
tests/(含 1.4MB 预览截图) |
1830 KB | 已排除 |
cloud/ddz.sql(云端脚本) |
49 KB | 已排除 |
miniprogram_npm(SDK) |
166 KB | 166 KB(保留,必须在包里) |
| 上传包总计 | 2519 KB ❌ | 684 KB ✅(余量 1364 KB) |
5. 长期防线
node tests/ddz-pkgsize.js—— 快速估算,秒级输出各目录占比;node tests/mp-publish-verify.js—— 端到端:调用 WorkBuddy 内置的真实miniprogram-ci走完 assemble → npm → filter 全流程,实测最终上传体积;- 两者超 2MB 均以非 0 退出码失败,已并入
tests/validate.js(现 352 断言)。
6. 其他不构成阻塞的项
project.config.json的appid仍是touristappid(游客模式):只用于本地依赖分析的占位值, 服务端上传时会注入真实 appid 与 privateKey,不影响发布;- 运行时拿 appid 走
wx.getAccountInfoSync().miniProgram.appId,真机上返回真实 appid。
五、后续规划
| 优先级 | 事项 | 说明 |
|---|---|---|
| P0 | 绑定正式小程序并做真机联机实测 | 当前唯一阻塞项;体验版发布通道已就绪(预览面板 → 分享) |
| P1 | 评论 / 游玩记录迁移到云端 | 替换 utils/store.js 实现即可,页面零改动 |
| P1 | 房间超时回收 | 增加 updated_at 过期清理任务,避免僵尸房间 |
| P1 | 棋类 AI 增强 | 象棋加两层搜索、围棋加影响力模型,当前为启发式 |
| P2 | 轮询自适应退避 | 对手已提交后停止轮询,降低资源点消耗 |
| P2 | 新增游戏时扩充目录 | 在 data/games.js 增加条目;未完成玩法 playable: false,并按 §2.3 说明恢复详情页置灰逻辑 |
| P3 | 排行榜与好友榜 | 需要云端聚合查询与用户关系 |
| P3 | 文件存储落地 | 头像、战绩截图、素材上传 |
附录 A:核心代码位置索引
| 关注点 | 文件 | 关键位置 |
|---|---|---|
| 云客户端初始化 | utils/cloud.js |
createMiniProgramWorkBuddyCloud({ endpoint, publishableKey }) |
| 默认登录(静默) | app.js |
onLaunch → ensureSession() → resolveSession()(复用会话 → wx.login → signInWithWechat) |
| 会话缓存与重试 | app.js |
ensureSession() / resetSession();失败不缓存,下次自动重试 |
| 昵称兜底 | app.js |
syncNickname(),不覆盖用户自定义昵称 |
| 房间创建(重试) | utils/wordroom.js |
createRoom(),捕获 error.code === '23505' |
| 房间加入(原子) | utils/wordroom.js |
joinRoom(),条件 status='waiting' AND joiner_id IS NULL |
| 提交词语(乐观锁) | utils/wordroom.js |
submitWord(),条件 .eq('round', room.round) |
| 轮次结算 | utils/wordroom.js |
advanceRound(),相同 → finished,不同 → round+1 |
| 微信登录 | pages/wordmeet/lobby.js |
onLogin() 为手动兜底,正常路径走 app.js 的静默登录 |
| 轮询调度 | pages/wordmeet/room.js |
startPolling() 2000ms;onHide/onUnload 停止 |
| 分享卡片 | pages/wordmeet/room.js / lobby.js / detail.js |
onShareAppMessage() |
| 成绩写入 | pages/wordmeet/room.js |
recordHistory() → store.addHistory({ gameId:'wordmeet' }) |
| 本地数据 | utils/store.js |
gh_history / gh_comments / gh_profile |
| 你画我猜数据层 | utils/drawroom.js |
beginRound / syncStrokes / submitGuess / revealRound / prepareNextRound |
| 画布与猜中判定 | pages/draw/room.js |
600×600 逻辑坐标、增量绘制;画手端比对答案并揭晓 |
| 棋类规则引擎 | utils/boardeng.js |
纯函数 createGame/applyMove/legalMoves,三棋种统一接口 |
| 棋类 AI | utils/boardai.js |
think(state),五子棋评分 / 象棋贪心 / 围棋启发式 |
| 棋类房间数据层 | utils/boardroom.js |
submitMove 以 .eq('turn', role) 乐观锁 |
| 棋类对局页 | pages/board/room.js |
Canvas 棋盘(x0/y0 原点,象棋 10 行居中)、双模式回合判定 isMyMoveNow、syncView 定视角、locate 反算落点 |
| 棋类视角换算 | utils/boardview.js |
localSide / needsFlip / flipRC(180° 自逆)/ flipIndex / sideName;纯函数,无 canvas 依赖 |
| 棋类规则回归测试 | tests/board-test.js |
30 断言:规则 + AI 自对弈稳定性 |
| 棋类视角回归测试 | tests/board-view-test.js |
56 断言:自逆性、双方绘制方位、河界镜像、选中圈与最后一手跟随、落点镜像、执黑完整走子 |
| 棋类视角离线预览 | tests/board-preview.js |
把真实 redraw() 的 canvas 调用翻译成 SVG,红黑两种视角并排出一张图 |
| 掷骰子 / 掷硬币规则 | utils/dicelib.js |
clampCount 夹取 1–6 / rollDice 可注入随机源 / diceVerdict 以「颗数 × 3.5」为中线判大小(压线算平)/ PIPS 九宫格点位 / nextCoinAngle 累加角度保证每次真转(见 §3.17) |
| 掷骰子页面接线 | pages/play/play.js |
onRollDice 每 90ms 换骰面共 8 次后落定;onFlipCoin 先推角度再等 1100ms 揭晓;rolling 期间锁按钮、锁切玩法、锁改颗数(见 §3.17.3) |
| 掷骰子回归 | tests/dice-test.js |
104 断言:大小判定穷举对称性、点位布局、硬币角度累加、页面行为、3D 样式静态守卫 |
| 掷骰子离线预览 | tests/dice-preview.js |
真实 play.wxss 渲染 3 颗 / 6 颗 / 硬币正反,量折行与溢出,并用 elementFromPoint 确认朝前的是哪一面 |
| 斗地主牌型引擎 | utils/ddzcards.js |
classify / beats / enumeratePlays / pickHint,签名 '<类型>:<点数>:<长度>' |
| 斗地主房间数据层 | utils/ddzroom.js |
createRoom / joinRoom(走 ddz_join RPC)/ playCards / passTurn / bid / takeBottom |
| 斗地主手牌布局 | utils/ddzlayout.js |
layoutHand(n):按张数算牌宽 + 重叠步进,保证一行铺满且角标可读;layoutPreview(n):放大预览带布局(≤7 张一行 / ≥8 张两行,牌数再多则压边重叠且至少露出 30rpx 角标);两者都输出可直接内联的 rpx 样式 |
| 斗地主拖动连选手势 | utils/ddzgesture.js |
hitIndex(重叠时命中上层牌)/ dragRange(锚点→闭区间)/ applyRange(选中·取消选中·移出区间自动回滚)/ layoutRects(无实测时的坐标兜底) |
| 斗地主自动选牌 | utils/ddzauto.js |
bestPlay(选区, 上一手签名) → {ok, reason, cards, sig, canBeat, changed};整组合法则原样采用,只额外告知能否压过;整组不合法才枚举子组合,优先挑能压过的那组 |
| 斗地主对局页 | pages/ddz/room.js |
applyState() 统一派生座位/回合/按钮态/手牌布局;onHandTouchStart/Move/End 实现点选与拖动连选;settleSelection() 抬手把选区收敛成「能出的那一手」;updatePreview() 生成放大预览带;refreshSelection() 用 myHand[i].selected 路径增量写回;measureHand() 实测每张牌边界;onHint() 循环提示;epochSerial 乐观锁 |
| 斗地主回归测试 | tests/ddz-test.js |
286 断言:牌型向量 + 大小比较 + 2/3/4 人布局 + 发牌随机性 + 手牌布局 + 拖动手势 + 自动选牌 + 增量 setData + 预览带结构 |
| 斗地主共享向量表 | tests/ddz-vectors.js |
42 条牌型向量,客户端与云端 ddz_classify 共用 |
| 斗地主云端脚本 | cloud/ddz.sql |
表结构 + RLS + 授权 + 14 个服务函数的可部署脚本;洗牌写法有防回归注释 |
| 斗地主视觉走查 | tests/ddz-preview.js |
WXML+WXSS → 离线 HTML(node tests/ddz-preview.js [张数] [起点] [终点] [nosel]),内嵌自动测量脚本判断手牌是否溢出、预览带是否压到手牌、手牌角标是否被邻牌盖住,并用真实 DOM 矩形模拟一次拖动连选 |
| 记忆翻牌 | pages/play/play.js / play.wxml / play.wxss |
onCardTap 路径式增量 setData(cards[i].flipped/matched);配对成功保持 flipped;回翻定时器 this.flipTimer 在 onUnload/initMemory 清理;3D 翻转容器禁用 opacity/filter(见 §3.12);单人/双人切换 onSwitchMode,双人翻对加分继续、翻错回翻后换手(见 §3.14) |
| 记忆翻牌回归测试 | tests/play-test.js |
106 断言:单人配对后图案保留 + 回翻时序 + 步数与通关 + 双人轮流/计分/换手时序 + 增量 setData + 3D 翻转样式的静态守卫 |
| 联机翻牌 · 数据层 | utils/memoryroom.js |
只调 cloud.database.rpc,从不直连 memory_rooms 表(表已 REVOKE ALL);函数名与参数即云端契约 |
| 联机翻牌 · 纯逻辑 | utils/memorygame.js |
牌面数字↔图案映射、状态投影、可点判定、提示语、增量 setData 补丁(见 §3.15.3) |
| 联机翻牌 · 牌桌页 | pages/memory/room.js |
900ms 轮询 + 乐观翻牌 + 按 reveal_left 精确排期 settle;submitting/settling 时跳过轮询防闪烁(见 §3.15.5) |
| 联机翻牌 · 云端 | cloud/memory.sql |
表 + 9 个 SECURITY DEFINER 函数 + memory_selftest()(18 条);牌序只在服务端,客户端读不到(见 §3.15.2 起) |
| 联机翻牌回归 | tests/memory-room-test.js |
101 断言:投影/可点/文案/增量 setData/只走 RPC 的静态守卫/脚本化对局 |
| 记忆翻牌视觉走查 | tests/memory-preview.js |
用真实的 play.wxss 离线渲染单人/双人两块牌桌,elementFromPoint 判断每张牌中心实际显示图案还是问号(matchedShowingQuestion 必须为 0),并量双人 HUD(模式按钮、比分卡、轮到谁)是否溢出行宽 |
| AI 复盘模块 | utils/wordai.js |
buildMessages 构造 prompt / pickModel 挑便宜小模型 / fallbackAnalysis 本地兜底 / appendDelta+tidy 流式累积收尾 / createAbortController 最小可中断信号 / analyzeRound 流式主入口 |
| AI 复盘回归测试 | tests/wordai-test.js |
104 断言:prompt 构造 + 模型挑选 + 本地兜底 + 流式累积 + 可中断信号行为 + 页面级(点详情→流式交替锚点→关弹窗→请求被中断→不进缓存→迟到回调不写界面) |
| AI 复盘视觉走查 | tests/wordmeet-preview.js |
用真实的 room.wxss 离线渲染往轮回顾 + 复盘弹窗,自动量详情按钮是否同行/溢出、弹窗是否居中贴合 375px、正文是否溢出、滚动锚点是否存在 |
| 工程静态校验 | tests/validate.js |
JS 语法 / JSON / WXSS 配对 / 页面四件套 / 事件绑定 / 禁用 API / 发布包体积守卫(499 断言) |
| 房间拉取守卫 | tests/roomguard-test.js |
26 断言:拉取失败分类(fatal/retry)、致命词必须带房间上下文、阈值常量(见 §3.18) |
| 发布包体积估算 | tests/ddz-pkgsize.js |
复刻发布通道的 assemble/filter 逻辑,秒级输出各目录占比;超 2MB 非 0 退出 |
| 发布通道端到端验证 | tests/mp-publish-verify.js |
调用 WorkBuddy 内置真实 miniprogram-ci 走完 assemble → npm → filter,实测上传体积 |
附录 B:环境修复记录(复现用)
脚手架模板 native-basic/1.0.0 从缓存解压后行尾被规范化为 CRLF,导致 manifest.json 中登记的 sha256 与磁盘文件不匹配,脚手架校验失败。
修复方法:
# 把模板文件统一转回 LF,并按原始登记值恢复 manifest 中的 sha256
node -e "
const fs=require('fs'),crypto=require('crypto');
const dir='<模板目录>/assets/templates/native-basic/1.0.0';
const manifest=JSON.parse(fs.readFileSync(dir+'/manifest.json','utf8'));
for (const f of manifest.files) {
const lf=fs.readFileSync(dir+'/'+f.path,'utf8').replace(/\r\n/g,'\n');
fs.writeFileSync(dir+'/'+f.path, lf);
f.sha256=crypto.createHash('sha256').update(lf,'utf8').digest('hex');
}
fs.writeFileSync(dir+'/manifest.json', JSON.stringify(manifest,null,2)+'\n');
"
若后续仍报哈希不匹配,检查两处模板副本:插件缓存目录
~/.workbuddy/plugins/cache/.../skill-mini-program-development/...与 WorkBuddy 安装目录resources/plugins/workbuddy-builtin/skills/mini-program-development/...。 另:工作区根目录被占用时,脚手架会在重命名阶段报EBUSY,改为在子目录中生成工程即可。