← 返回首页
项目文档

架构与部署手册

技术架构、云端数据模型、联机同步方案与完整发布流程

小游戏乐园(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=总轮数,越小越好)                       │

关键机制:

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 新建函数默认授予 PUBLIC EXECUTE,只 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 安全与合规

3.9 容量与成本模型

云服务按资源点计费(与 AI 积分是两套独立口径),计费项包括:数据库 CPU 使用量、数据库容量、服务调用次数、访问频率超额部分、文件存储读写/容量/流量、短信验证码条数、云函数算力等。

对当前项目的用量估算口径:

场景 主要消耗项 说明
单人玩记忆翻牌/反应 几乎为 0 全本地,仅本地 storage
双人同词相遇一轮 数据库读写 + 2 次轮询请求 每 2 秒 1 次 getRoom,是主要消耗来源
好友规模 房间数 × 轮数 × 轮询频率 轮询频率若从 2s 降到 4s 可减半消耗

优化选项(未实施):轮询自适应退避(对手已提交后停止轮询)、只在页面可见时轮询(当前已用 onHide 停轮询)。

3.10 已知技术债

  1. 评论、游玩记录、昵称仍为本地存储,换设备即丢失;
  2. 房间不做超时回收,长期不玩的房间会一直占用 waiting 状态;
  3. 轮询固定 2 秒(联机翻牌 900ms),未做自适应退避;
  4. project.config.json 中 appid 仍为 touristappid(游客模式),绑定正式小程序后需由发布流程写入;
  5. 测试全部为本地 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:

拖动抬手时 settleSelection() 把选区收敛成算出来的那一手,于是「出牌」按钮出的就是预览里那一手。

③ 放大展示且不压住旁边的牌 —— 结构性解决,不是靠调 z-index:


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):

防回归:


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 防回归

⚠ 离线预览的 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 实现要点

3.14.4 界面

3.14.5 防回归

node tests/play-test.js 从 48 断言扩到 106 断言,新增 58 条覆盖双人:

反向验证(确认测试真能抓住规则退化):

注入的缺陷 结果
翻错不换手(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 → 🍎🍋🍇🍓🥕🌽🍄🌰。

三个副作用值得记一笔:

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') 伪造两个身份

验证:

反向验证(确认测试不是摆设):

注入的缺陷 结果
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:

四处绘制跟着翻(网格线不用动,因为 180° 旋转下线条与自己完全重合):

位置 处理
棋子 drawChessPiece(ctx, m, q.r, q.c, piece),q 是屏幕格
选中圈 同上,从 this.selectedFrom 反算出屏幕格
最后一手方框 同上,从 lastMove.t 反算
楚河汉界 翻转后「汉界」落到左边,字仍是正的

落点判定 locate() 走的是同一条路:先落到屏幕格,再用同一个 flipRC 翻回逻辑格。 画和点用同一个函数,就不会出现「看到的是这匹马、点下去走的是对面那匹」。

3.16.4 文案

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,防「一次失败即踢人」)

问题现象:进入联机房间游玩时,会被「自动退出」到错误屏(提示房间不存在),且重进复现。

根因(三层叠加):

  1. 一次失败就永久判死:五个房间页(同词相遇 / 你画我猜 / 棋类 / 斗地主 / 联机翻牌)的拉取逻辑都是 if (error || !room) → 停轮询 + 错误屏。网络抖一次、云函数冷启动超时一次就被踢。
  2. RLS 静默过滤把「未登录」伪装成「房间不存在」:房间表 SELECT 策略是 owner_id = auth.uid() OR joiner_id = auth.uid() OR status = 'waiting'。 会话临时失效时 auth.uid() 为 NULL → 行被过滤 → 客户端拿到 data: null 且无 error → 被当成「房间没了」。
  3. 坏会话不自愈:app.js 的 sessionPromise 只在登录时失败才重置;游戏进行中 token 失效不会触发重建, 重进房间用的还是坏会话 → 每次进都被踢,只有杀掉小程序重开才恢复。

修复方案(2026-11-19):

验证: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,否则量出来的弹窗宽度是假的。

发布前人工确认清单

4.2 阶段二:注册 / 绑定小程序账号

方式 前置条件 适用场景 说明
试用小程序 无(微信扫码即可) 快速体验、临时分享给朋友 扫码即建即用;有有效期(以面板显示日期为准);不支持直接转正式版
绑定已有小程序 已注册的小程序账号 + 管理员微信 长期运营 可发布体验版、提交正式版审核

注册正式小程序的步骤

  1. 浏览器打开 https://mp.weixin.qq.com →「立即注册」→「小程序」;
  2. 准备一个从未注册过公众平台账号的邮箱(一个邮箱只能注册一个账号);
  3. 选择主体:个人(身份证 + 手机号,免费;无法开通微信支付、部分类目受限)或企业(需营业执照);
  4. 邮箱激活 → 主体信息登记 → 完成注册;
  5. 登录后在「设置 → 基本设置」获取 AppID;
  6. 回到 WorkBuddy「分享」面板 → 绑定已有小程序 → 用该小程序管理员微信扫码授权。

注意:微信公众平台一个微信最多可绑定若干账号(含小程序、小游戏、公众号),绑定弹窗里出现「测试号」「已冻结」的账号都无法用于发布。

4.3 阶段三:在 WorkBuddy 内发布(全程无需手工上传代码包)

  1. 打开预览:点击对话中的「小游戏乐园」应用卡,进入预览面板;
  2. 点击「分享」:面板右上角分享图标(位于刷新和「…」的左边);
  3. 选择方式:试用小程序(扫码创建)或绑定已有小程序(扫码授权);
  4. 执行发布:分享面板按版本分行显示状态 —— 试用版 / 体验版 / 正式版;
  5. 取小程序码:对应版本行显示「已发布」后,悬停该行最右侧二维码图标,弹出小程序码,可「复制」或「下载」,微信扫码即可打开并发给好友;
  6. 提交审核(正式版):在微信公众平台提交审核,通过后发布。

面板还提供:

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.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. 长期防线

6. 其他不构成阻塞的项


五、后续规划

优先级 事项 说明
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,改为在子目录中生成工程即可。

附录 C:官方参考