# S-20 / 0.3.1「相机手感修复包」总报告

- 版本：**0.3.1**（npm `wyszz-frontend-rebuild-hm03@0.3.1`；微信工程名 `wyszz-island-0.3.1[-internal]`）
- 任务代号：S-20；范围：**只改相机/手势手感**（经济数值、契约、存档 schema、调试事件列表、UI 布局与文案、一键购买、建筑入口一律未动）
- 工作树：`/vol1/ai/projects/wyszz-new/frontend-rebuild-hm031`（由 0.3.0 交付树 `frontend-rebuild-hm03` 整树复制后开工）
- 只读锚点：`frontend-rebuild-hm03`（0.3.0，已交付）、`frontend-rebuild-hm023`（0.2.4）—— 本轮全程未改，终检见 §9
- 报告时间：2026-10-21（北京时间）

## 1. 结论摘要

| 项 | 结果 |
| --- | --- |
| 双指「要么缩放、要么平移」的误判 | **已修**：取消整段模式锁，同段手势同时按间距比缩放 + 按重心位移平移，各自死区 0.5px |
| 掉帧时画面跳变 | **已修**：`dt` 夹在 ≤1/30 s，缩放/平移/俯仰/取景统一 `dt*14` 一阶平滑 |
| 取景动画期间拖动「拖一点跳一下」 | **已修**：`panBy()` 的位移换算与边界夹取统一用**当前** zoom（0.3.0 换算用 `zoom`、夹取用 `tZoom`） |
| 放大后松手还在漂 | **已修**：惯性指数 0.04→0.02（快速衰减），且放大 ≥2× 直接禁用旋转惯性 |
| 回不到默认视角 / 俯仰回不去 | **已修**：世界区双击（≤300ms、≤10px）= 回全岛；新增「回全岛」按钮（≥40px，自动避让顶栏/底栏/街区栏，浮层在时隐藏）；`resetFocus()` 含默认俯仰 |
| 双指中一指落在 HUD | 保持 0.3.0「吞掉该指」行为，**新增计数** `stats.swallowed` / `stats.hudPinch` 并接入内部只读读数 |
| 内部调试面板相机读数 | 新增只读 3 行（zoom / pan.x,pan.z / target / yaw / pitch / fps / pinch / pan / swallowed / HUD 双指），正式包零残留 |
| 内部包「手势：新/旧」A/B 开关 | **已实现**（调试面板第 14 个按钮，默认「新」）；正式包该分支被编译期剔除（只有一个 `true &&` 之外无旧逻辑） |
| `zoomMax` | 保持 **3.0**（未改） |
| 新增测试 | Node 32 断言、按钮矩阵 480 用例/8640 断言/违反 0、端到端 57/57、指纹变异 14/14；原 39 步回归**一条不删、强度不降** |

## 2. 根因对比表（0.3.0 现象 → 代码根因 → 0.3.1 改法）

| # | 玩家反馈（0.3.0） | 代码根因（0.3.0） | 0.3.1 改法 | 关键文件 |
| --- | --- | --- | --- | --- |
| 1 | 双指想放大，结果整屏在平移；或想平移，结果在缩放 | `PointerMove` 在本次手势第 2 个 move 后按 `\|ΣΔ间距\| > \|Δ重心x\|+\|Δ重心y\|` **一次性锁定** `pinchMode='zoom'\|'pan'`，之后整段手势只做一种 | 删除模式锁：缩放用「两指间距比」逐帧 `zoomBy(d/dPrev)`，平移用「两指重心位移」逐帧 `panBy(Δcx,Δcy)`，两者各有 0.5px 死区、同帧可同时生效 | `src/app/input.ts` |
| 2 | 一卡一卡，掉帧时镜头「跳一大步」 | `update(dt)` 不夹 `dt`；缩放 `dt*10`、平移 `dt*12`、取景 `dt*4` 三套系数；掉到 20fps 时一帧积分 50ms | `CAM_SMOOTH.dtMax = 1/30`（`dt` 夹取），缩放/平移/俯仰统一 `dt*14`，取景 `dt*14` | `src/render/camera.ts` |
| 3 | 取景动画（选建筑特写/回全岛）期间拖一点就跳/到边不动 | `panBy()` 用 `this.zoom` 算 `worldPerPixel`，却用 `this.tZoom` 夹取 `clampPan`；动画期两者不等 ⇒ 位移比例与边界不一致 | 换算与夹取统一用 `Math.max(0.001, this.zoom)` | `src/render/camera.ts` |
| 4 | 松手后镜头还在慢慢漂（放大后尤其明显） | 惯性恒为 `vYaw *= 0.04^dt`，无缩放条件；放大后同样的角速度造成更大画面位移 | `inertiaDecay = 0.02`（每 1 s 衰减到 2%）；`tZoom ≥ 2` 时松手直接 `vYaw = 0` | `src/render/camera.ts` |
| 5 | 找不到「回到全岛」的路；俯仰回不到默认 | 只有 `resetFocus()` 且只清 `tPan/tZoom`，`tPitch` 保持玩家扭到的角度；无按钮、无双击 | `resetFocus()` 增加 `tPitch = CAM.pitch0`、`vYaw = 0`；新增世界区双击（≤300ms、≤10px、两击皆无可交互物）；新增「回全岛」按钮（见 §3.3） | `src/app/input.ts`、`src/render/camera.ts`、`src/app/app.ts`、`src/ui/hud.ts`、`src/ui/hud-layout.ts` |
| 6 | 双指中一指压在 HUD 上时行为说不清、测试也数不出来 | 只有抬起时 `swallowed++`，落指那一刻不计数，也没有专门读数 | 保持「吞掉该指」不放行 HUD 手势；落指即 `swallowed++ / hudPinch++`，内部面板可见 | `src/app/input.ts`、`src/ui/debug-panel.ts` |
| 7 | 手感问题只能靠肉眼争论 | 调试面板只有 fps/draw call 等 | 面板加 3 行**只读**相机读数（zoom / pan / target / yaw / pitch / fps / pinch / pan / swallowed / HUD 双指）；正式包无任何残留（`S20-K03/K04` 扫描 5 个标记全 0 命中） | `src/ui/debug-panel.ts`、`src/app/app.ts` |
| 8 | 新旧手感无法同机对比 | — | 内部包调试面板第 14 按钮「手势：新/旧」（默认新）；旧逻辑 `legacyPinchMove()` 仅 `__INTERNAL__ && legacyPinch` 可达，正式包构建时被常量折叠 + 无用代码剔除（正式包 `pinch-legacy-v030` 命中 0） | `src/app/input.ts` |

### 2.1 为什么「双击」不会吃掉买地/升级/领奖

- 双击只在**两击都落在「无可交互物」的世界点**（空地/道路/树/云/天空/街区）时成立：`worldHarmlessAt()` 用无副作用的 `pickAt()` 判定，候选地、市政厅、三栋楼、居民一律算「有交互」，此时第一击照常派发、第二击也照常派发，**不吞任何真实操作**。
- 这样保留了冻结契约里的既有语义：`test/t-land.mjs` L03 的 250 ms 两步购买、`test/t-gameplay.mjs` 的「连续 10 次快点居民 10 次都发奖」原样通过（本轮回归未见这两步任何变化）。
- 已知取舍（如实记录）：在**同一可交互物**上 300 ms 内快速点两下仍是两次真实操作（例如连点居民两次领两次奖），不会触发回全岛——这是为了不削弱经济/契约语义而做的保守选择。

## 3. 改动清单

> 脚本生成（`/tmp/s20/gen-changes.mjs`：逐文件字节比较 `hm03` ↔ `hm031`，跳过 `node_modules/ dist/ evidence/`）。完整清单见 `文件变更清单.txt`（同目录）。

### 3.1 统计

| 类型 | 数量 |
| --- | --- |
| 新增文件 | **7** |
| 修改文件 | **20** |
| 删除文件 | **0**（原有测试、原有断言、原有产物一个未删） |

### 3.2 新增（7）

| 文件 | 作用 |
| --- | --- |
| `src/game/fingerprints-s20.ts` | 0.3.1 启动指纹三组（tune / camhome / behavior），正式包不通过即拒绝启动 |
| `tests/s20-camera.test.ts` + `tools/test-s20-node.mjs` | Node 纯逻辑：相机平滑/夹取/惯性/复位 + 双指控制器（同时缩放平移、死区、双击、HUD 指） |
| `tests/s20-hud-layout.test.ts` + `tools/test-s20-hud-layout.mjs` | 「回全岛」按钮窄屏矩阵（5 屏 × 安全区 × 购地模式 × 浮层遮挡） |
| `test/t-s20-camera.mjs` | 端到端（真实 CDP 触摸/鼠标）：A–K 共 57 条断言 |
| `test/t-fp-s20.mjs` | 指纹变异锚点：4 处改坏 ⇒ 正式包 HALT / 内部包红字继续 |
| （`package.json` 新增 4 个 script、`tools/regress.mjs` 末尾追加 4 步，属修改） | |

### 3.3 修改（20，按职责分组）

**相机与输入（手感本体）**

| 文件 | 改什么 | 旧→新 |
| --- | --- | --- |
| `src/app/input.ts` | 双指取消模式锁；新增死区累计；双击识别；HUD 指计数；旧逻辑移出类体 | 见 §5.1 读数 |
| `src/render/camera.ts` | 新增 `CAM_SMOOTH`；`update()` 夹 dt + 统一 14；`panBy()` 统一 zoom；`resetFocus()` 加俯仰/清惯性 | 见 §5.1 读数 |
| `src/app/app.ts` | `onWorldTap` 返回「有无副作用」；`worldHarmlessAt()`；`resetCameraHome()`（双击/按钮同一路径）；每帧 `syncCameraHome()`；`cam-home` 动作；`fingerprintS20` 自检；调试 API：`cam20/camHome/gestureMode/setGestureMode/camStep/zoomBy/worldHarmless/fingerprintS20` | 只读读数与测试钩子，无玩法改动 |
| `src/ui/hud-layout.ts` | 追加 `layoutCamHome()` 与常量（`CAM_HOME_MIN=40/CAM_HOME_SIZE=44/CAM_HOME_GAP=8`）；既有函数**零改动** | 追加 34 行，无删除 |
| `src/ui/hud.ts` | 新增 `camHome` 图层/命中区/遮挡让位/绘制；`layoutInfo.camHome` | 追加，既有排版结果不变 |
| `src/ui/debug-panel.ts` | 3 行只读相机读数；第 14 按钮「手势：新/旧」；面板高度 9→12 行；banner 0.3.1 | 只有内部包有该文件内容 |

**版本号（0.3.0 → 0.3.1，逐处）**

| 文件 | 旧 | 新 |
| --- | --- | --- |
| `package.json` | `"version": "0.3.0"` | `"version": "0.3.1"` |
| `tools/build-web.mjs` / `tools/build-wechat.mjs` | `const VERSION = '0.3.0'` | `const VERSION = '0.3.1'` |
| `src/ui/debug-panel.ts` | `内部测试包 0.3.0` | `内部测试包 0.3.1` |
| `test/t-land.mjs`（L15a×2） | `内部测试包 0.3.0` | `内部测试包 0.3.1` |
| `test/t-s12.mjs`、`test/wechat-s12.mjs` | `包版本 0.3.0` | `包版本 0.3.1` |
| `test/t-s19.mjs`（S19-I01） | `=== '0.3.0'` | `=== '0.3.1'` |
| `tests/s12-layout.test.ts`、`tests/s12b-layout.test.ts`、`tests/s12-node.test.ts`、`tests/s12b-node.test.ts` | `version: '0.3.0'` 及 `包版本 0.3.0` / `MANIFEST v0.3.0` | 同步 0.3.1 |
| `test/t-wechat-project-config.mjs` | `wyszz-island-0.3.0`、`我要当岛主 0.3.0 ·`、W13/W18/W19 断言串 | 同步 0.3.1（断言强度不变：仍逐字节比对 + 四包 version/channel 校验） |

> 未动：`package-lock.json`（其中的 `emoji-regex ^10.3.0` 不是项目版本）、历史注释里「0.3.0 新增模块」之类的**历史说明**（保留原意，不改写历史）。

**测试入口**

| 文件 | 旧 | 新 |
| --- | --- | --- |
| `package.json` scripts | — | 新增 `test:s20-node` / `test:s20-hud-layout` / `test:s20` / `test:fp-s20` |
| `tools/regress.mjs` | 39 步 | 43 步（末尾追加 s20-hud-layout / s20-node / s20-e2e / fp-s20，**原步骤编号与内容未改**） |
| `test/wechat-s08.mjs` | WS06a 断言「按钮 13 个」 | 「按钮 **14** 个」并**新增**两条断言（`手势: 新` 必须在、`手势: 旧` 必须不在）——调试面板新增 S-20 A/B 开关，强度只增不减 |

### 3.4 删除（0）

无。所有旧测试、断言、证据与 0.3.0 产物都保留。

## 4. 新增测试与强度

| 测试 | 内容 | 结果 |
| --- | --- | --- |
| `S-20 Node`（`tools/test-s20-node.mjs`） | 双指同时缩放+平移（0.3.0 只动一个）、平移连续单调、死区 <0.5px 不生效、同段手势无模式锁、双击窗口/位移/副作用判据、HUD 指吞掉与计数、平滑 k=dt·14、dt 夹 1/30、panBy 统一 zoom、惯性收敛与 ≥2× 停、resetFocus 俯仰 | **32 断言全通过** |
| `S-20 按钮矩阵`（`tools/test-s20-hud-layout.mjs`） | 5 屏（320×568/360×640/390×844/414×896/430×932）+ 600/768/1024 宽屏 × 安全区（0/24/47、0/34）× 购地模式开/关 ×（有/无街区栏、报价卡/角色卡/确认框/报告遮挡）× 显示/隐藏 | **480 用例 / 8640 断言 / 违反 0** |
| `S-20 端到端`（`test/t-s20-camera.mjs`） | A 同缩同移、B 连续单调、C 无模式锁、D 双击回全岛（数值/交互副作用/不误触）、E 按钮（可见/≥40px/不压栏/点击复位/不改数据）、F 放大后点居民仍领奖、G HUD 指、H 平滑与掉帧、I 新旧手势 A/B、J 5 屏×3 状态截图、K 版本/指纹/正式包零残留 | **57/57 通过**；pageerror **0** |
| `S-20 指纹变异`（`test/t-fp-s20.mjs`） | 4 个锚点各改坏 1 字节/1 数字（tau 14→12、inertiaDecay 0.02→0.03、死区 0.5→0.4、按钮 44→40） | **14/14 通过**：正式包全部 `[boot] HALTED` + `localStorage` 零读写、帧循环未启动；内部包红字「程序完整性自检未通过」继续运行 |

> 旧断言强度：原 39 步内容**未删除、未放宽**；本轮新增步骤都追加在末尾（`tools/regress.mjs` 只加 21 行、零删除）。

## 5. 手感前后对比（读数 + 截图）

### 5.1 同一合成手势/同一帧输入下的 0.3.0 vs 0.3.1 读数

> 数据来源：`/tmp/s20/cmp/harness.mjs`——把 `hm03` 与 `hm031` 的 `camera.ts`/`input.ts` 分别打包到 Node，喂**完全相同的合成事件序列**（同一 390×844 视口、同一起点）。

| 场景 | 0.3.0 | 0.3.1 | 说明 |
| --- | --- | --- | --- |
| 双指同段「间距变大 + 重心右移」8 步（zoom 2 起） | zoom Δ1.00，**pan Δ0.000**，pinch 15 / pans **0** | zoom Δ1.00，**pan Δ0.584**，pinch 16 / pans **16** | 旧版整段被锁成缩放，平移完全丢失 |
| 只有重心平移（间距恒定）6 步 | pan Δ1.168，pinch 0 / pans 11 | pan Δ1.168，pinch 12 / pans 12 | 平移量与旧版一致（未因新逻辑变灵敏/变钝）；pinch 计数含缩放因子往返（净 zoom 不变，见 e2e `S20-B01`） |
| 空世界点双击（间隔 120ms、位移 3.6px） | taps 2，double **0** | taps **1**，double **1** | 新版识别双击并且吞掉第二击 |
| HUD 一指落下（另指在世界） | zoom 不变、UI 动作 0、swallowed **1**、hudPinch 无 | zoom 不变、UI 动作 0、swallowed **2**、hudPinch **1** | 行为不变，只是「落指」也计入读数 |
| 缩放一帧 `dt=1/60`（目标 3） | 3 → **1.3333** | 3 → **1.4667** | 新系数 `dt*14`（更跟手） |
| 缩放一帧 `dt=1/30` | 3 → **1.6667** | 3 → **1.9333** | |
| **掉帧一帧 `dt=0.2`** | 3 → **3.0000（一帧冲到底）** | 3 → **1.9333** | 旧版掉帧即「跳到底」，新版按 33ms 积分 |
| 惯性 yaw 轨迹（zoom=1，6 帧） | `-0.0428, -0.0631, -0.0823, -0.1005, -0.1178, -0.1342` | `-0.0428, -0.0629, -0.0816, -0.0992, -0.1157, -0.1312` | 衰减更快（0.04→0.02） |
| **放大 3× 松手是否继续漂** | **继续漂**（`zoom3Stop=false`） | **立即停**（`zoom3Stop=true`） | ≥2× 禁用惯性 |
| 取景动画期（当前 zoom=1、目标 tZoom=3）拖 120px | pan → **(-4.628, 3.240)**（远超当时允许的 0） | pan → **(0, 0)** | 旧版换算/夹取用两个不同 zoom ⇒ 拖到岛外/回弹 |
| `resetFocus()` 后俯仰 | **45.84°** | **34.00°**（= `CAM.pitch0`） | 回全岛包含默认俯仰 |
| `zoomMax` | 3.0 | 3.0 | 未改 |

### 5.2 端到端实测（真实浏览器触摸/鼠标，内部包 0.3.1）

| 断言 | 实测 |
| --- | --- |
| A01/A02 双指同缩同移 | zoom 2.00→3.00 且 pan (0,0)→(-0.52,0.36)；同段 pinch 16 次 + pan 16 次 |
| B01 纯平移连续单调 | pan 单方向累计到 (-0.95,0.67)，夹在 panMax 4.241 内，zoom 仍 2.00 |
| C01 无模式锁 | 同段手势先纯平移（pan Δ0.682）再纯缩放（2.00→2.83）都生效 |
| D01/D02/D03 双击回全岛 | zoom 3.00→1.00、pan→(0,0)、pitch 34.0°；`doubleTaps=1`、只派发 1 次点击；金币/地块/访客/等级不变 |
| E01–E05 「回全岛」按钮 | 44px 可见、不压顶栏/底栏/街区栏/提示行；点击后 zoom 2.40→1.00、pan→0、按钮消失；不改经营数据 |
| F01/F02 放大后点居民 | 3× 鼠标点击居民 #0 访客 0→1；回 1× 触摸点击居民 #0 访客 1→2 |
| G01–G03 HUD 指 | hudPinch 0→1、swallowed 0→2；zoom/pan 不变；无面板/卡片/模态被打开 |
| H01/H02 平滑与掉帧 | 一帧 k=0.2333=dt·14；`dt=0.2` 与 `dt=1/30` 结果完全相同（1.9333） |
| I01–I03 新旧 A/B | 旧逻辑同段手势只动一个（zoom Δ0.000 / pan Δ0.871）；切回新逻辑两轴都动（zoom Δ0.600 / pan Δ0.796） |
| J01–J05 5 屏 × 3 状态 | 默认隐藏；最大缩放+平移时 44px 可见且不越界/不压栏；点按回全岛；经营面板打开时隐藏 |
| K01–K04 版本/指纹/零残留 | 版本 0.3.1、`fingerprintOk=true`、S-20 三组指纹 OK；正式包 web/wechat 中 `内部测试包`/`手势: 旧`/`数值总览`/`pinch-legacy-v030`/`window.__wyszzDebug` 命中 **0** |
| Z99 pageerror | **0** |

### 5.3 截图（5 屏 × 3 状态，共 15 张）

目录：`evidence/`（`s20-<宽>x<高>-{1-default,2-zoom3,3-panned}.png`）

| 屏幕 | 状态 1 默认视角 | 状态 2 最大缩放 3× + 平移 | 状态 3 平移态 |
| --- | --- | --- | --- |
| 320×568 | ![320-default](evidence/s20-320x568-1-default.png) | ![320-zoom3](evidence/s20-320x568-2-zoom3.png) | ![320-panned](evidence/s20-320x568-3-panned.png) |
| 360×640 | ![360-default](evidence/s20-360x640-1-default.png) | ![360-zoom3](evidence/s20-360x640-2-zoom3.png) | ![360-panned](evidence/s20-360x640-3-panned.png) |
| 390×844 | ![390-default](evidence/s20-390x844-1-default.png) | ![390-zoom3](evidence/s20-390x844-2-zoom3.png) | ![390-panned](evidence/s20-390x844-3-panned.png) |
| 414×896 | ![414-default](evidence/s20-414x896-1-default.png) | ![414-zoom3](evidence/s20-414x896-2-zoom3.png) | ![414-panned](evidence/s20-414x896-3-panned.png) |
| 430×932 | ![430-default](evidence/s20-430x932-1-default.png) | ![430-zoom3](evidence/s20-430x932-2-zoom3.png) | ![430-panned](evidence/s20-430x932-3-panned.png) |

> 状态 2/3 中右上角可见「回全岛」按钮（44×44）。状态 1 默认视角下按钮不出现（不干扰画面）。

## 6. 版本与交付包

| 项 | 值 |
| --- | --- |
| `package.json` version | 0.3.1 |
| 构建 VERSION | 0.3.1（`tools/build-web.mjs` / `tools/build-wechat.mjs`） |
| MANIFEST version（四包） | 0.3.1（channel：release / internal） |
| 微信工程名 | `wyszz-island-0.3.1`（正式）/ `wyszz-island-0.3.1-internal`（内部） |
| 调试面板 banner | 内部测试包 0.3.1 |
| 四包 | 网页-正式包 209,248 B / 网页-内部包 222,170 B / 微信-正式包 211,243 B / 微信-内部包 224,794 B（sha256 见 `dist-交付件sha256.txt`，18/18 `sha256sum -c` 通过） |
| 构建体积 | 正式网页 `main-acb573d581.js` 741.4 KiB（gzip 204.3 KiB）；正式微信 `game.js` 745.9 KiB（gzip 206.0 KiB，sha256 `a1046cf3263f13d8…`）；内部网页 `main-6c45a439fc.js` 776.7 KiB（gzip 217.0 KiB）；内部微信 `game.js` 783.3 KiB（gzip 219.4 KiB，sha256 `9d36b5f4d021ab3f…`） |
| 交付哈希清单 | `dist-交付件sha256.txt`：18 条（4 zip + 14 个 dist 文件），绝对路径，`sha256sum -c` **18/18 OK** |
| 正式包调试词扫描 | `scan:formal` PASS（正式包 0 命中、负例与内部包如期 FAIL） |
| 正式包内部标记/旧逻辑残留 | 0（`S20-K03/K04` 五个标记） |
| 微信包的调试接口挂载点 | 微信小游戏**没有 `window`**，内部包把调试接口挂在游戏全局对象上（产物里是 `Vr.__wyszzDebug`）。所以微信包按 `__wyszzDebug` 扫描：正式包 **0 命中**、内部包 **1 命中**（语义与网页包「正式零残留、内部有读数」完全一致；网页包才是字面 `window.__wyszzDebug`） |

## 7. 全量回归（43 步）

**结论：43/43 全部 PASS**（`--fail-fast` 未启用、`--skip` 为空；总耗时 630.6 s）。

- summary.json：`/vol1/ai/projects/wyszz-new/frontend-rebuild-hm031/evidence/regress-20261021-030931/summary.json`（`ok:true`、`totalMs:630560`、`skipped:[]`）
- 逐步骤日志：同目录 `NN-<id>.log`（43 个）
- 过程记录：第一次跑批为 **42/43**，唯一失败项 `wechat-s08 WS06a` 是**测试期望数字未随 S-20 更新**（调试面板按钮 13→14：新增内部包「手势：新/旧」A/B 开关）。按「只增不减」原则把断言从 13→14、并**新增**两条断言（`手势: 新` 必须在、`手势: 旧` 必须不在）后单步 13/13，再整轮重跑得 43/43。这两次记录都留在证据里（`regress-20261021-025800` 为第一次，`regress-20261021-030931` 为最终）。

| # | 步骤 | 结果 | 关键数字 |
| --- | --- | --- | --- |
| 01 | 类型检查 | PASS | tsc 静默通过 |
| 02 | 构建(core+内部包+正式包) | PASS | 正式 web `main-acb573d581.js` 741.4 KiB / gzip 204.3 KiB；正式微信 `game.js` 745.9 KiB / gzip 206.0 KiB / sha256 `a1046cf3263f13d8…`；内部 web `main-6c45a439fc.js` 776.7 KiB / gzip 217.0 KiB；内部微信 `game.js` 783.3 KiB / gzip 219.4 KiB / sha256 `9d36b5f4d021ab3f…` |
| 03 | 契约样例(fixtures) | PASS | 32/32 |
| 04 | 会话回放(replay) | PASS | 32/32 |
| 05 | 核心护栏(core-guards) | PASS | 19/19 |
| 06 | 玩法(gameplay) | PASS | 30/30 |
| 07 | UI(ui) | PASS | 30/30 |
| 08 | 视觉(visual) | PASS | 18/18 |
| 09 | 浏览器测试(全量) | PASS | 81/81 |
| 10 | 微信替身测试 | PASS | 38/38 |
| 11 | 隔离检查(项目专用) | PASS | 0 违规 / 1 白名单 |
| 12 | 隔离检查负例 | PASS | 6/6 |
| 13 | 微信工程配置(B1) | PASS | 19/19 |
| 14 | **契约样例全量(contract)** | PASS | **32 组 / 9769 case / 差异 0** |
| 15 | **属性测试与确定性(property)** | PASS | **3000 序列 / 193500 步 / 违反 0 / 确定性差异 0** |
| 16 | 正式包调试词扫描 | PASS | 正式包 PASS / 负例 FAIL / 内部包命中 |
| 17 | 正式包烟雾测试 | PASS | 11/11 |
| 18 | HUD 窄屏矩阵(S-08.1) | PASS | 3240 用例 / 178434 断言 / 违反 0 |
| 19 | S-08 Node(几何/R4/重试) | PASS | 16/16 |
| 20 | 买地端到端(S-08.7) | PASS | 61/61 |
| 21 | 微信包买地/调试面板(S-08) | PASS | 13/13（含 WS06a 14 按钮） |
| 22 | 指纹失败：正式包拒绝/内部包继续 | PASS | 12/12 |
| 23 | 街区面板/角色卡窄屏矩阵(S-10.5) | PASS | 165888 用例 / 10393520 断言 / 违反 0 |
| 24 | S-10 Node(漫步/外观档位/街区接线) | PASS | 18/18 |
| 25 | 街区升级/居民/角色卡 端到端(S-10.5) | PASS | 46/46 |
| 26 | 新增模块指纹自检(S-10.4) | PASS | 11/11 |
| 27 | S-12 Node(统计纯函数/采样器/报告/排版) | PASS | 32/32 |
| 28 | 真机报告窄屏矩阵(S-12.3) | PASS | 27072 用例 / 622602 断言 / 违反 0 |
| 29 | 失败飘字/调试刷新/真机报告 端到端 | PASS | 30/30 |
| 30 | 微信替身：真机报告/缺接口(S-12.4) | PASS | 15/15 |
| 31 | S-12 新增模块指纹自检 | PASS | 21/21 |
| 32 | S-12b Node(对比度/托盘/间距/飘字) | PASS | 26/26 |
| 33 | 报告间距+飘字落点窄屏矩阵(S-12b) | PASS | 648 用例 / 1738668 断言 / 违反 0 |
| 34 | 托盘让位/飘字底板 端到端(S-12b) | PASS | 69/69 |
| 35 | 微信替身：报告间距/飘字底板(S-12b) | PASS | 8/8 |
| 36 | S-19 经营面板/购地窄屏矩阵 | PASS | 288 组合 / 65664 断言 / 违反 0 |
| 37 | S-19 Node(相机平移边界/缩放/复位) | PASS | 25 断言 |
| 38 | S-19 指纹变异锚点 | PASS | 14/14 |
| 39 | S-19 端到端(F-8/M1-M4/N1-N3) | PASS | 65/65 |
| 40 | **S-20 回全岛按钮窄屏矩阵（新）** | PASS | **480 用例 / 8640 断言 / 违反 0** |
| 41 | **S-20 Node（新）** | PASS | **32 断言** |
| 42 | **S-20 端到端（新）** | PASS | **57/57**、pageerror 0 |
| 43 | **S-20 指纹变异锚点（新）** | PASS | **14/14** |

> 冻结契约相关三步（14/15/16）与上一版完全一致：契约 32 组 9769 case 差异 0、属性 193500 步 0 违反、正式包扫描 PASS。

## 8. 未验证项（如实记录）

| 项 | 状态 | 原因 / 说明 |
| --- | --- | --- |
| **真机手感**（双指同时缩放+平移的跟手程度、惯性收敛快慢、双击灵敏度） | **未验证** | 只能在机主的真实手机上判断；本轮只做了合成事件 + 无头 Chromium 量化读数，不能替代手感结论 |
| **真机帧率**（0.3.1 在目标机型上的 FPS/掉帧） | **未验证** | 无头 Chromium 为 SwiftShader 软件渲染，FPS 读数不代表手机；`dt` 夹取只保证掉帧时**不跳变**，不保证不卡 |
| 微信真机（`wx.onTouch*` 双指事件序列与浏览器 `pointer` 的差异） | **未验证** | 微信替身测试 `wechat-s12` 等只覆盖适配层逻辑；双指同时缩放+平移在真机微信上的事件合并/顺序需机主实测 |
| 手感「新旧」A/B 的主观偏好 | **未验证** | 内部包已提供开关，等机主对比后给结论 |
| 宽屏（平板/桌面）双击与按钮手感 | **部分验证** | 按钮矩阵覆盖到 1024 宽；双击在 390×844 实测，宽屏未单独实测（逻辑与屏幕尺寸无关） |

## 9. 回滚方法

1. **整包回滚（推荐）**：直接用 0.3.0 交付件（`tasks-out/S-19/叫我大岛主-0.3.0-*.zip`）覆盖安装；`hm03` 树保持只读未动，可随时重新构建 0.3.0。
2. **源码回滚**：`frontend-rebuild-hm03` 是 0.3.0 的完整可构建树（本轮只读，终检见 §9.1），需要 0.3.0 产物时在 `hm03` 里 `npm ci && npm run build` 即可。
3. **基线对比/急退**：S-20 开工时的整树备份 `tasks-out/S-20/hm031-开工备份.tgz`（= 0.3.0 源码，184 项，sha256 `c8eac001…1824bf`）可解出直接构建。
4. **更早版本**：`frontend-rebuild-hm023`（0.2.4）连同 `tasks-out/S-18/叫我大岛主-0.2.4-*.zip` 亦保持只读，终检通过。

### 9.1 只读终检（0.3.0 / 0.2.4 未被改动）

本轮开工前先把 0.3.0（`hm03`）与 0.2.4（`hm023`）记为只读锚点；收尾时逐项复核，**两棵树一个字节没动**。

| 校验对象 | 参照锚点 | 命令 | 结果 |
| --- | --- | --- | --- |
| hm03（0.3.0）dist 14 个文件 | `tasks-out/S-19/dist-交付件sha256.txt` | `sha256sum -c` | **14/14 OK**（同文件内 4 个 0.3.0 zip 也全 OK） |
| hm03（0.3.0）源码全树 | S-20 开工备份 `hm031-开工备份.tgz`（复制自 hm03） | `diff -r --exclude=node_modules --exclude=dist --exclude=evidence` | **无任何差异**（源码/测试/工具/文档逐字节一致） |
| hm023（0.2.4）四包 zip | `tasks-out/S-19/回滚锚点-hm023-0.2.4.sha256`（相对 `tasks-out/S-18/`） | `sha256sum -c` | **4/4 OK** |
| hm023（0.2.4）dist 12 个文件 | 同上（相对 `hm023/dist/`） | `sha256sum -c` | **12/12 OK** |
| hm023（0.2.4）源码全树 | 同上「hm023 全树」行 | 排序后逐文件 sha256 再取总哈希 | `8781212ca6a6cc8f1a9ba2eade1f33361d220b0c39f16ac746142a363d076c31`，**与锚点完全一致** |
| hm03（0.3.0）源码全树当前值（仅记录） | — | 同上 | `7e1d2f1d06b42aa6fc8f02abccc23cb01fa34c4f762aa14bc46ba0a982ba01e4` |

> 只读终检在 S-20 收尾阶段执行，全程只读（`sha256sum` / `diff` / `tar -x` 到 `/tmp/s20/base`），未写入 `frontend-rebuild-hm03` 与 `frontend-rebuild-hm023`。

### 9.2 独立核验（交付核验手二次复核，非本报告作者自证）

| 组 | 内容 | 结果 |
| --- | --- | --- |
| V1 | `sha256sum -c dist-交付件sha256.txt` | **18/18 OK**，清单构成 = 4 zip + 14 dist 文件，dist 路径全部真实存在、四目录文件数恰好 14 |
| V2 | 四包解包后与 dist 逐文件 sha256 比对 | **4/4 包完全一致**（3/3/4/4 文件，无多余文件、无 `__MACOSX`）；字节数 209248/222170/211243/224794 全中 |
| V3 | 版本/工程名/入口引用 | **PASS**：四包 MANIFEST 均 `0.3.1`（channel 2 release + 2 internal）；微信工程名 `wyszz-island-0.3.1[-internal]`、`compileType=game`、`appid=touristappid`；`index.html` 引用与实际 js 文件名一致 |
| V4 | 正式包零残留 / 内部包有读数 | **PASS（语义）**：正式包 10/10 项 0 命中（网页+微信 × 5 标记）；内部包 `内部测试包`/`手势: 旧`/`数值总览`/`pinch-legacy-v030` 均 ≥1。唯一字面差异：微信包没有 `window`，「`window.__wyszzDebug`」在微信内部包里按字面为 0，需按微信全局对象扫描 `__wyszzDebug`（内部 1 / 正式 0）——已在 §6 记录原因，属平台差异而非缺陷 |
| V5 | 只读锚点 | **PASS**：hm03 dist 14/14 + 4 zip 全 OK、源码全树 `diff -r` 无输出；hm023 四包 4/4、dist 12/12、全树总哈希 `8781212c…d076c31` 一致（158 文件） |
| V6 | 回归关键数字抽检（自己从日志读） | **PASS**：`14-contract.log:40` = `合计: 32 组, case=9769, 差异=0`；`15-property.log` = `"stepsTotal": 193500 / "violations": 0 / "determinismDiffs": 0 / "sequences": 3000`；`42-s20-e2e.log` 末行 `57/57`；`43-fp-s20.log` 末行 `14/14`；`summary.json` `ok:true / totalMs:630560 / 43 步 / skipped:[]` |
| V7 | 截图齐全 | **PASS 15/15**：5 屏 × 3 状态，文件名与 PNG 文件头（`89504e47`）、IHDR 尺寸全部吻合，大小 79,983–146,094 B |

> 核验手全程只读、只写 `/tmp/s20-verify/`；其抽检的 5 个关键数字与本报告 §7 全部吻合。

## 10. 审计痕迹（旧→新语义逐项）

| # | 项 | 0.3.0（旧语义） | 0.3.1（新语义） | 旧断言/契约是否仍成立 |
| --- | --- | --- | --- | --- |
| 1 | 双指手势判定 | 第 2 个 move 后按 `\|ΣΔ间距\| > \|Δ重心x\|+\|Δ重心y\|` **整段锁定**成缩放或平移 | 同段手势双通道并行：间距比 → `zoomBy`，重心位移 → `panBy`；各自死区 0.5px，互不锁定 | N2 旧用例（先缩放后平移）仍通过：`s19-e2e 65/65`、`S20-I01/I02` 量化对照 |
| 2 | 缩放平滑 | `dt*10`（`Math.min(1, dt*10)`） | `dt*14` | 视觉更快跟手；无旧断言锁定该常数 |
| 3 | 平移平滑 | `dt*12` | `dt*14` | 同上 |
| 4 | 取景（fitDist）平滑 | `dt*4` | `dt*14` | 选建筑特写/回全岛的动画仍在 ~1 帧内起步 |
| 5 | `dt` 上限 | 无（掉 50ms 就积分 50ms） | `min(dt, 1/30)` | 掉帧不再一次跳到底（`S20-H02`：0.2 s 一帧 ⇒ 与 1/30 完全相同） |
| 6 | `panBy()` 一致性 | 换算用当前 `zoom`、夹取用目标 `tZoom`（动画期不一致） | 换算与夹取都用当前 `zoom` | 平移边界仍满足 `panLimit`（`s19-node 25 断言`、`S20-B01`） |
| 7 | 旋转惯性衰减 | 恒定 `pow(0.04, dt)` | `pow(0.02, dt)`，且 `tZoom ≥ 2` 时松手直接清零 | 单指旋转灵敏度/系数未改（`S-20 Node` 断言 `k=π·1.15/max(300,viewH)`） |
| 8 | `resetFocus()` | 只清 `tPan/tZoom`，俯仰停在玩家扭到的角度 | 追加 `tPitch = CAM.pitch0`、`vYaw = 0` | `S19-G04`（关面板回全岛）仍通过 |
| 9 | 双击回全岛 | 无 | 世界区两击间隔 ≤300ms、位移 ≤10px、**两击皆无可交互物** ⇒ 回全岛并吞掉第二击 | `t-land` L03（250ms 两步购买 250ms 成交）、`t-gameplay` 连点居民 10 次 10 次发奖**均原样通过**（gameplay 30/30、land-e2e 61/61） |
| 10 | 点击阈值 | 触摸 10px / 鼠标 8px / 600ms | **未改** | 全部旧点击类用例原样通过 |
| 11 | 双指中一指落在 HUD | 整条手势被 UI 吞掉，但只有「抬起」那一刻 `swallowed++` | 行为不变（不放行 HUD 手势）；**落指即** `swallowed++`、`hudPinch++`，内部读数可见 | s10/s12b/s19 中所有 HUD 吞噬类断言仍通过（`s10-e2e 46/46` 等） |
| 12 | 调试面板按钮 | 13 个（8 + 4 加币 + 数值总览） | **14 个**（+ S-20「手势：新/旧」A/B 开关，默认「新」） | `wechat-s08` WS06a 同步 13→14，并**新增**「`手势: 新` 必须在、`手势: 旧` 必须不在」两条断言（强度只增不减） |
| 13 | 版本字符串 | 0.3.0 | 0.3.1（13 处逐字替换，见 §3.3；`package-lock.json` 未动） | 各版本断言同步更新，W11/W12 仍逐字节比对，W19 仍校验四包 version+channel |
| 14 | `zoomMax` | 3.0 | **3.0（未改）** | `s19-node`/`S-20 Node` 均断言上限 3.0 |
| 15 | 被 S-19 指纹锁定的两条解析式 | `panLimit`、`worldPerPixel` | **表达式一字未改**（只新增常数与调用点） | `fingerprintS19` 仍 all OK（`s19-e2e`、`fp-s19 14/14`） |
| 16 | 依赖 | — | **未新增任何依赖**（`dependencies`/`devDependencies`/`package-lock.json` 三者与 0.3.0 完全一致，已 diff 验证） | — |

## 11. 证据索引

| 文件 | 内容 |
| --- | --- |
| `tasks-out/S-20/进度.md` | 逐步进度日志（含卡点/降级记录，若有） |
| `tasks-out/S-20/文件变更清单.txt` | 0.3.0→0.3.1 逐文件变更（脚本生成） |
| `tasks-out/S-20/evidence/s20-results.json` + `s20-*.png` | 端到端 57 条断言明细 + 15 张截图 |
| `tasks-out/S-20/dist-交付件sha256.txt` | 四包 + dist 全部文件 sha256（18/18 可 `sha256sum -c`） |
| `tasks-out/S-20/交付直链.md` | 登记后的下载直链（总监复核后登记） |
| `evidence/s20-camera.json` / `s20-hud-layout-matrix.json` / `browser-results-fp-s20.json`（工作树内） | Node 断言、按钮矩阵、指纹变异明细 |
| `evidence/regress-<时间戳>/`（工作树内） | 43 步逐步骤日志 + `summary.json`（最终 `regress-20261021-030931` 43/43；首次 `regress-20261021-025800` 42/43 也保留） |
| `tasks-out/S-20/S-20-证据包.zip` | 15 张截图 + 4 份明细 JSON + 两轮回归日志（43×2 步）+ 进度日志，共 115 项 |
| `tasks-out/S-20/总报告.md` | 本报告 |
