Merge branch 'master' of http://82.157.175.59:3000/GenarrativeAI/Genarrative

docs/technical/MATCH3D_RUNTIME_3D_GEOMETRY_EXPERIMENT_2026-05-02.md

@@ -0,0 +1,74 @@
+# 抓大鹅运行态 3D 几何体实验 2026-05-02
+
+## 1. 实验目标
+
+本轮只验证抓大鹅运行态把可消除物从 2D 纯色几何图案切换为 3D 几何体后的可读性、点击手感和堆叠碰撞观感。
+
+3D 表现层必须满足：
+
+1. 圆形图案映射为球体。
+2. 方形图案映射为方块。
+3. 三角形、菱形、五角星、六边形、胶囊、心形、梯形、平行四边形等现有视觉键映射为近似 3D 几何体。
+4. 物体在圆形空间内保持边界约束，并使用物理模拟产生轻微碰撞、堆叠、晃动效果。
+5. 点击、备选栏、消除、胜负判定仍使用当前后端权威快照与前端即时反馈协议，不把规则真相迁到前端。
+
+## 2. 回退要求
+
+这是一次可取消实验，不替换现有 2D 方案。
+
+1. 现有 `Match3DVisualIcon`、`Match3DToken` 和托盘 2D 图案渲染代码必须保留。
+2. 新增 3D 表现层只作为运行态棋盘的可选渲染分支。
+3. 当浏览器不支持 WebGL、3D 依赖加载失败或实验开关关闭时，运行态必须自动回到现有 2D 图案表现。
+4. 托盘继续使用当前 2D 图标，便于玩家识别已选物品，也便于实验失败时快速回滚。
+
+## 3. 工程落点
+
+本轮只改前端表现层：
+
+```text
+src/components/match3d-runtime/Match3DPhysicsBoard.tsx
+src/components/match3d-runtime/Match3DRuntimeShell.tsx
+src/components/match3d-runtime/Match3DRuntimeShell.test.tsx
+src/components/match3d-runtime/match3dRuntimePresentation.ts
+src/components/match3d-runtime/match3dVisualAssets.tsx
+```
+
+新增依赖：
+
+```text
+three
+cannon-es
+@types/three
+```
+
+3D 棋盘默认启用；需要快速回到当前 2D demo 表现时，在运行态 URL 上追加任一参数：
+
+```text
+?match3dRender=2d
+?match3d3d=off
+```
+
+3D 分支只读取后端快照中的物品坐标、层级、可点击状态和视觉键。物理碰撞、轻微堆叠和几何体姿态只作为前端表现层，不改变消除规则、备选栏规则、胜负判定或最终权威快照。
+
+`match3dVisualAssets.tsx` 保留 2D 纯色几何图案映射，运行态托盘继续使用该 2D 图标；`match3dRuntimePresentation.ts` 收口显示层坐标和状态兼容，避免异常旧坐标把 2D 或 3D 物体推到圆形边界外。
+
+## 4. 验收口径
+
+1. `/match3d` 能打开并默认看到 3D 几何体棋盘。
+2. 3D 几何体保持在圆形区域内，不被圆形边界裁切到不可点。
+3. 物体进入场景后有轻微物理碰撞和堆叠稳定过程。
+4. 点击 3D 物体后仍执行原有乐观入槽、后端确认、三消反馈和结算。
+5. 单元测试仍覆盖 2D 回退图案，确保回退路径没有被删除。
+6. 390px 移动端与桌面端均不能出现横向溢出，顶部状态、圆形棋盘和 7 格备选栏都要完整可见。
+
+## 5. 锅型容器优化
+
+2026-05-02 追加一轮 3D 表现优化，把运行态圆形空间明确解释为一口有固定深度和确定边界的锅。
+
+编码口径：
+
+1. 相机改为俯视角，玩家优先看到锅内物体的平面分布、遮挡关系和向上堆叠。
+2. 3D 场景里的圆形区域拆成锅底、锅壁和锅沿三层视觉结构，锅壁有固定高度，锅沿明确标出边界。
+3. 物理世界使用同一个锅内半径作为水平活动边界，所有可消除物体的初始位置和运行中位置都必须被约束在圆形锅内。
+4. 物体受到重力后只允许在锅内碰撞、滑动、翻滚和向上堆叠，不能因为碰撞或初始坐标散落到圆形区域外。
+5. 该优化仍只属于前端 3D 表现层，不改变后端运行态坐标、点击权威判定、备选栏、消除和胜负规则。

docs/technical/README.md

@@ -66,6 +66,7 @@
 - [MATCH3D_SPACETIME_CLIENT_AND_API_FACADE_2026-04-30.md](./MATCH3D_SPACETIME_CLIENT_AND_API_FACADE_2026-04-30.md)：记录抓大鹅 B4+B5 已落地的 SpacetimeDB bindings、`spacetime-client` facade、`api-server` HTTP 路由、shared contract 对齐和验收命令。
 - [MATCH3D_CREATION_ENTRY_COMING_SOON_2026-05-01.md](./MATCH3D_CREATION_ENTRY_COMING_SOON_2026-05-01.md)：记录抓大鹅创作页入口重新开放、首屏与弹层分流一致，以及公开广场失败不污染创作错误态的边界。
 - [MATCH3D_Q1_INTEGRATION_ACCEPTANCE_2026-05-01.md](./MATCH3D_Q1_INTEGRATION_ACCEPTANCE_2026-05-01.md)：记录抓大鹅 Match3D 第一至第三波完成度复核、Q1 主链集成落点、定向验收命令和遗留风险。
+- [MATCH3D_RUNTIME_3D_GEOMETRY_EXPERIMENT_2026-05-02.md](./MATCH3D_RUNTIME_3D_GEOMETRY_EXPERIMENT_2026-05-02.md)：记录抓大鹅运行态 3D 几何体与物理碰撞实验的前端表现层边界、2D 回退要求和验收口径。
 - [PLATFORM_MOBILE_BOTTOM_DOCK_VIEWPORT_FIX_2026-04-30.md](./PLATFORM_MOBILE_BOTTOM_DOCK_VIEWPORT_FIX_2026-04-30.md)：记录平台首页底部 dock 在手机浏览器地址栏展开时脱离可见区域的根因，以及 `100dvh`、固定底部锚点和安全区占位的修复口径。
 - [SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md](./SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md)：记录 SpacetimeDB private 表迁移 JSON 导出/导入 procedure、迁移操作员授权、HTTP 413 分片导入、Jenkins 自动迁移回灌和导入脚本参数。
 - [JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md](./JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md)：记录 `Genarrative-Database-Export` / `Genarrative-Database-Import` 两条 SCM-backed 数据库迁移流水线参数、默认 dry-run、token 边界和 `CHUNK_SIZE` 413 规避参数。