小程序项目档案 · 小游戏乐园(gamehub)
维护规则:每轮开发交付前更新本档案(读旧档 → 改动 → 写回)。 版本:v1.0(2026-11-19 建档)
一、项目概况
| 项 | 内容 |
|---|---|
| 项目名 | 小游戏乐园(gamehub) |
| 项目路径 | D:\mycodes\MyApp\vx\wordsMeeting\gamehub |
| 主体类型 | 待定(发布通道已打通,正式账号绑定由发布面板扫码完成) |
| 环境说明 | 微信 AppID 当前为 touristappid 测试占位值,正式 AppID 由 WorkBuddy 发布流程注入,不需要也不会写进代码;WorkBuddy 应用 ID 与云服务环境配置见《架构与部署手册》文档头 |
| 当前阶段 | 功能开发基本完成 → 体验版发布就绪,待真机联机实测 |
二、技术栈
| 层 | 选型 | 备注 |
|---|---|---|
| 框架 | 微信原生小程序(WXML/WXSS/JS,CommonJS) | 无第三方 UI 库、无构建步骤 |
| 云服务 | WorkBuddy 托管 Serverless(PostgreSQL + 微信登录认证 + LLM) | SDK @tencent-ai/workbuddy-cloud-sdk,npm 构建 miniprogram_npm 进包 |
| 云端脚本 | cloud/ddz.sql、cloud/memory.sql |
表 + RLS + SECURITY DEFINER 函数的可部署版本,改云端必须同步此文件 |
| 测试 | 本地 Node 断言脚本(tests/,累计约 1300 条) |
无框架依赖,直接 node tests/xxx.js 运行 |
三、页面清单与进度
| 页面路径 | 功能 | 状态 | 备注 |
|---|---|---|---|
| pages/index/index | 首页:分类/标签筛选 + 游戏列表 | 已完成 | 目录 7 款全可玩,无占位角标 |
| pages/detail/detail | 游戏详情 + 评论 + 分享 | 已完成 | 评论/昵称为本机存储 |
| pages/play/play | 单机游戏容器:记忆翻牌(单人/同屏双人)、反应大挑战、骰子与硬币 | 已完成 | disableScroll 必须为 false |
| pages/memory/lobby | 联机翻牌大厅 | 已完成 | 含「先自己练两把」入口 |
| pages/memory/room | 联机翻牌牌桌 | 已完成 | 900ms 轮询 + 乐观翻牌 |
| pages/wordmeet/lobby | 同词相遇大厅 | 已完成 | 登录状态三态 |
| pages/wordmeet/room | 同词相遇房间 + AI 复盘弹窗 | 已完成 | 流式 + 缓存 + 可中断 |
| pages/draw/lobby | 你画我猜大厅 | 已完成 | |
| pages/draw/room | 你画我猜房间(Canvas) | 已完成 | 600×600 逻辑坐标 |
| pages/board/lobby | 棋类对战大厅(三棋种选人机/好友) | 已完成 | |
| pages/board/room | 棋类对战棋盘 | 已完成 | 象棋执黑视角翻转 |
| pages/ddz/lobby | 斗地主大厅(2/3/4 人) | 已完成 | |
| pages/ddz/room | 斗地主仿真牌桌 | 已完成 | 拖动连选 + 放大预览带 |
| pages/profile/profile | 昵称、历史记录、清空 | 已完成 |
四、已用组件与接口
| 类别 | 清单 | 注意事项 |
|---|---|---|
| 微信 API | wx.login、wx.getStorageSync/setStorageSync、wx.getAccountInfoSync、分享 onShareAppMessage、button open-type="share" |
登录链路唯一收敛在 app.js,其他页面不得直接调 wx.login(validate.js 强制) |
| 云 SDK | auth.signInWithWechat、auth.getSession、database(表 CRUD + rpc)、llm.chat.completions.create(仅支持流式) |
LLM 必须 stream: true,增量在 choices[0].delta.content |
| 原生组件 | canvas(棋盘/画板)、scroll-view enhanced(横向 chips / 流式弹窗滚动) |
scroll-into-view 值不变不触发,流式滚动需双锚点交替 |
| 基础库版本 | 未固定最低版本要求 | 如需下探基础库,先以官方文档核实所用 API 的版本门槛 |
五、测试与质量门禁(改动后必跑)
| 改动范围 | 必跑测试 | 断言数 |
|---|---|---|
| 任何 JS/JSON/WXSS 改动 | node tests/validate.js |
499 |
| 棋类规则 / 视角 / 页面 | board-test + board-view-test(+ board-preview 出图人工看字向) |
30 + 56 |
| 斗地主(含布局、手势、自动选牌) | ddz-test(+ ddz-pkgsize、ddz-preview) |
286 |
| 记忆翻牌单机 | play-test(+ memory-preview) |
106 |
| 联机翻牌 | memory-room-test |
101 |
| 同词相遇 AI 复盘 | wordai-test(+ wordmeet-preview) |
104 |
| 骰子 / 硬币 | dice-test(+ dice-preview) |
104 |
| 5 个联机房间页 / roomguard 守卫 | roomguard-test(+ 对应游戏测试) |
26 |
| 发布前 | ddz-pkgsize + mp-publish-verify(端到端真实打包) |
超 2MB 非 0 退出 |
六、Agent 协作守则(注意事项)
新会话 / 新 Agent 接手时先读这一节。改代码前先确认踩线没有,改完按 §五跑测试。
6.1 架构铁律(违反 = 设计错误,不是风格问题)
- 服务端权威分界:联机游戏(同词相遇 / 你画我猜 / 棋类好友局 / 斗地主 / 联机翻牌)的对局逻辑、洗牌、判定都在云端;客户端只发指令 + 轮询渲染。纯随机单机游戏不要上云(骰子/硬币/反应),多一个 RPC 往返就毁手感。
- 藏着的信息连表都不能给:当秘密本身是行字段(联机翻牌的
deck牌序、你画我猜的答案)时,RLS 行级隔离无效——做法是REVOKE ALL ... FROM PUBLIC, anon, authenticated且不建任何策略,读写全走 SECURITY DEFINER 函数,读接口脱敏(未翻开位置返回null)。 - PostgreSQL 新建函数默认授权 PUBLIC:只 REVOKE
anon/authenticated收不住,必须连PUBLIC一起 REVOKE。 - 双端同构:客户端纯函数与云端函数返回同一签名(如斗地主牌型签名),改规则必须两端同改,用
tests/ddz-vectors.js共享向量表跑 parity。 - 数据归属靠 RLS:每张表有
owner_id/user_id,用auth.uid()判归属;房间成员判断用EXISTS子查询。 - 并发用乐观锁:
round/turn/epoch_serial/serial比对不一致直接拒绝并提示刷新;幂等判断(如翻牌结算)要放在 serial 校验之前。 - 交互逻辑抽纯函数:布局、手势、AI、判定等易错逻辑放
utils/纯函数(可在 Node 单测),页面只取坐标、喂数据、渲染。 - 云端 SQL 必须落本地版本(
cloud/*.sql),不要只留在控制台;用「函数体归一化 md5」比对线上与本地防漂移。
6.2 高频坑索引(详情见架构手册对应小节)
| 坑 | 一句话守则 | 手册 |
|---|---|---|
| 3D 翻转容器 | preserve-3d 及其 3D 子元素上禁用 opacity/filter/backdrop-filter/mask/clip-path,会强制扁平化 |
§3.12 |
| 过渡动画 | 翻牌/抛硬币角度必须累加(目标+圈数×360),揭晓延时 ≥ transition 时长 | §3.17 |
| 重叠元素选中态 | 不加 z-index,只「抬起」不放大;放大预览放独立固定卡槽 + 绝对定位 |
§3.11 |
| setData | 手势/轮询场景只写路径差集(list[i].field);手势进行中挂起轮询结果 |
§3.11 |
| 定时器 | 挂实例字段(this.xxx),onUnload/重初始化时 clearTimeout |
§3.12 |
| 轮询 vs 乐观 UI | 提交中(submitting/settling)跳过 tick,否则乐观状态被打回 |
§3.15 |
| 视角翻转 | 换坐标不转字形:fillText 永远画屏幕坐标;180° 自逆,画与点共用同一换算函数 |
§3.16 |
| 洗牌 SQL | SELECT unnest(arr) ORDER BY random() 不随机,必须 FROM unnest(arr) AS c ORDER BY ... 先展开 |
§3.4 |
| SQL 保留字 / jsonb | left/right 不能做变量名;数组遍历用 jsonb_array_elements_text WITH ORDINALITY |
§3.15 |
| 流式滚动 | scroll-into-view 双锚点交替;纯计数状态挂 this.(放 data 里 NaN 静默失效) |
§3.13 |
| LLM 中断 | signal 只需 aborted + addEventListener 两个成员,自写最小 shim;取消的结果不进缓存 |
§3.13 |
| Node 端测 SDK | 别用 utils/cloud.js(依赖 wx.request),直接 createWorkBuddyCloud + anonymousTokenProvider |
§3.13 |
| 房间拉取失败 | 失败 ≠ 房间没了:会话临时失效时 RLS 把行静默过滤(data:null 无 error),必须走 utils/roomguard 分类 + 会话自愈,连续 3 次失败才判死;错误屏带「重试」按钮 |
§3.18 |
6.3 发布红线
- 主包 ≤ 2MB,不可申请调大;发布通道只读
project.config.json的packOptions.ignore,完全不读.gitignore——新增开发目录(如预览产物)必须显式加进 ignore; appid=touristappid是占位值,发布时服务端注入真实 appid,不要手动改;- 预览版与正式版共用同一云服务,提审前清理预览期测试数据(测试房间会进正式数据);
- 云登录与 Origin 绑定:必须复用既有 WorkBuddy 应用(见《架构手册》头部应用 ID),重新注册应用会破坏登录。
6.4 文档同步义务
| 你改了什么 | 必须同步 |
|---|---|
| 游戏规则 / 新增游戏 | 《业务需求文档》§3 需求卡 + §5 变更记录 + data/games.js |
| 技术方案 / 数据表 / 云函数 | 《架构与部署手册》对应小节 + cloud/*.sql 本地版本 |
| 新增页面 / 接口 / 依赖 | 本档案 §三 / §四 |
| 新踩的坑 | 手册对应小节 + 本档案 §6.2 索引 |
七、待办与已知问题
| 优先级 | 事项 | 说明 |
|---|---|---|
| P0 | 真机联机实测 | 双人房间、分享唤起、触摸容差、弱网轮询(清单见手册 §4.6) |
| P1 | 评论/历史/昵称迁云 | 只换 utils/store.js 实现 |
| P1 | 房间超时回收 | 防 waiting 僵尸房间 |
| P2 | 轮询自适应退避 | 降资源点消耗 |
| P2 | pickModel 向量模型过滤加固 |
真实模型目录无 modalities 字段,现有过滤未生效,需按前缀/能力字段过滤 |
| — | 骰子页窄屏高度 | 内容约 503px > iPhone SE 可用 472px,靠页面滚动兜底(disableScroll:false 有测试守卫) |
八、提审节点记录
| 时间 | 类型 | 结果 | 备注 |
|---|---|---|---|
| (尚未提审) | — | — | 2026-11-19 完成体验版发布前打包验证(761 KB);提审被驳回后,把驳回意见原样带回,逐条整改并更新本表 |