← 返回首页
项目文档

小程序项目档案

项目信息、云端脚本、关键代码位置索引

小程序项目档案 · 小游戏乐园(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 架构铁律(违反 = 设计错误,不是风格问题)

  1. 服务端权威分界:联机游戏(同词相遇 / 你画我猜 / 棋类好友局 / 斗地主 / 联机翻牌)的对局逻辑、洗牌、判定都在云端;客户端只发指令 + 轮询渲染。纯随机单机游戏不要上云(骰子/硬币/反应),多一个 RPC 往返就毁手感。
  2. 藏着的信息连表都不能给:当秘密本身是行字段(联机翻牌的 deck 牌序、你画我猜的答案)时,RLS 行级隔离无效——做法是 REVOKE ALL ... FROM PUBLIC, anon, authenticated 且不建任何策略,读写全走 SECURITY DEFINER 函数,读接口脱敏(未翻开位置返回 null)。
  3. PostgreSQL 新建函数默认授权 PUBLIC:只 REVOKE anon/authenticated 收不住,必须连 PUBLIC 一起 REVOKE。
  4. 双端同构:客户端纯函数与云端函数返回同一签名(如斗地主牌型签名),改规则必须两端同改,用 tests/ddz-vectors.js 共享向量表跑 parity。
  5. 数据归属靠 RLS:每张表有 owner_id/user_id,用 auth.uid() 判归属;房间成员判断用 EXISTS 子查询。
  6. 并发用乐观锁:round / turn / epoch_serial / serial 比对不一致直接拒绝并提示刷新;幂等判断(如翻牌结算)要放在 serial 校验之前。
  7. 交互逻辑抽纯函数:布局、手势、AI、判定等易错逻辑放 utils/ 纯函数(可在 Node 单测),页面只取坐标、喂数据、渲染。
  8. 云端 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 发布红线

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);提审被驳回后,把驳回意见原样带回,逐条整改并更新本表