# S-21（0.3.2）实施总报告

- 任务：**S-21** ／ 版本 **0.3.2**（基线 `frontend-rebuild-hm031` = 0.3.1 真机通过）
- 工作副本：`/vol1/ai/projects/wyszz-new/frontend-rebuild-hm032`（整树复制自 hm031，删 dist/evidence；开工 sha256 清单与备份见 §9）
- 时间：2026-10-21（北京时间）
- 角色：实施工程师（Lead）+ 1 个只读机械校验子代理（四包打包/扫描/只读基线复核）

## 1. 结论摘要

四项需求全部落地，且**未动契约、未动任何经济默认数值、未动存档 schema、未新增调试事件、未改建筑开业门槛**：

| # | 需求 | 结果 |
|---|---|---|
| ① | 相机 360°：近正俯视 + 能看到岛底 | 俯仰 **16°~62° → −25°~88°**；yaw 无界（连转 5 圈不回绕）；最低俯仰下**读像素证明岩锥/晶体真的画出来**；默认视角俯仰/雾/取景与 0.3.1 逐字同式（手感零回退） |
| ② | 「一键购买」→「点一次买一块、按固定顺序」 | 按钮文案 **买下一块**；点一次只买核心 `candidates()` 第一块（走同一条 `BUY_TILE` 事务）；**长按 ≥600ms** 才弹旧批量确认；连点 4 次 = 精确 +4 块、余额逐块核心价累减、绝不自动买光 |
| ③ | 建筑/居民楼/城区可发现性 + 目标提示 | 街区栏 **88×40「建筑」明确按钮**；建筑列表按「未开业且差得最少」排序；卡内含「需区 Lv N（当前 M）／开业费 2×B = X／区升级费（区 Lv M→M+1）」+「去升区」直达城区；街区栏上方「下个目标」提示条（数字全部来自核心）；3 栋未开业楼加楼顶光点；每会话首次点未开业楼提示一次 |
| ④ | 云：漂移 + 遮岛时半透明 + 造型重做 | 12 朵（+2 高空）、底部 3~4 扁平球的 6~8 球分层造型、逐朵独立材质；时间驱动**绝对函数漂移**（可复现、无累积）；遮岛云 alpha **0.24**、清晰 **0.92**、软边连续过渡（τ=0.12s）；云**移出拾取表**（俯视点楼/点地永不点空） |

## 2. 关键数值与证据（可复核）

### 2.1 相机（F-21）
- `src/render/camera.ts`：`pitchMin=-25°`、`pitchMax=88°`、`underMinDist=11`、`lowPitchGate=6°`；`panPitchScale()`（16°..62° 恒 1.0 / 最低 0.55 / 最高 0.75）；`fogForPitch()`（默认 1.3/3.1 不变，低俯仰把 far 推到 5.5×）；`apply()` 低俯仰距离下限。
- 实测（内部包 `cam21()`）：默认 `pitch 34° / distance 63.2575 / fog near 82.2348 far 196.0983`；`setCamera(…,3.0rad)` → 夹到 **88.00°**、`setCamera(…,-1.2rad)` → 夹到 **-25.00°**。
- 岛底证据：最低俯仰下岛心下方 5 个采样点亮度 `[44,33,33,210,212]`（320×568 等五屏一致）⇒ 岩锥为深色实体，不是天空。
- 证据：`test/t-s21-camera.mjs` **13/13 PASS**；截图 `evidence/s21-cam-<屏>-{default,top,low,under}.png`（20 张）。

### 2.2 点一次买一块（F-18）
- `src/game/session.ts` `buyNext()`：`candidates()[0]` → `quote()` → `buyTile()`（与生产完全同一条核心事务）；返回 `priceCoins/shortfallCoins/full/coinsMilliAfter`。
- `src/app/app.ts`：`'buy-all'` 区域 `pressMs >= 600 ? openBulkConfirm() : buyOneTile()`；toast「买下一块 · X 金币 · 剩 Y」；不可买时「全岛已满／离线结算中／金币不足，还差 X」。
- 实测：`69/69`（`test/t-s19.mjs`，其中 C15a-d 专门覆盖本项）；`12/12`（`test/t-s21.mjs` D08）。

### 2.3 可发现性（F-19）
- 入口：`bizEntryRect()` = 88×40，命中区实测 `hudRegion(中心)='bld-open'`、按钮左外侧=`blk-toggle`（不误吞）。
- 列表顺序：`bizListOrder=[1,2,3,0]`（未开业差得最少优先、市政厅最后），行文案与核心 `openState` 逐字一致。
- 卡片三行：`需区 Lv 2（当前 1）`、`开业费 2×B = 80 金币 · 区等级不足`、`区升级费 2,100 金币（区 Lv 1→2）`、按钮 `去升区` ⇒ 点击后 `mode='district'` + 镜头聚焦市政厅 + `tapLog.tag='ui:bld-distbtn'`。
- 目标提示：默认页文案 `下个目标：区 Lv2（还差 2,040 金币）→ 居民楼 80`（窄屏用紧凑同义文案，仍保留单位）；购地/列表/报价卡/抽屉/报告忙碌时隐藏，购地时显示且不与提示行重叠。
- UI 全链路：加币 → 去升区（花 2,100）→ 居民楼开业 ⇒ `open=true`、`milliPerMin=16960`、该楼光点消失（另 2 栋仍在）。
- 证据：`tests/s21-hud-layout.test.ts` **30 组合 / 1104 断言 / 0 违反**；`test/t-s21.mjs` **12/12 PASS**；截图 `evidence/s21-ui-*.png`（17 张）。

### 2.4 云（F-22）
- `src/render/cloud-alpha.ts`（纯函数）：`CLOUD_ALPHA_OCCLUDED=0.24`、`CLEAR=0.92`、软边 0.92↔1.08、τ=0.12s；`smoothCloudAlpha` 每帧 k=dt/τ（dt 夹 ≤0.1s）。
- `src/render/world.ts`：3 套云几何变体（底部 3~4 扁平球 + 中部 2 + 顶部 1~2 = 6~8 球）；12 朵各克隆材质（`transparent`、`depthWrite=false`、`renderOrder=1`）；漂移为 t 的绝对函数（主向 + 侧向谐波）；`pick()` 整体剔除 `TAG_CLOUD`。
- 实测：12 朵、三角形 **6880**（0.3.1 为 4720 ⇒ 1.46×，预算 1.5× = 7080）、材质 **7→19**；默认视角清晰 11 朵/软边 1 朵；顶视 2 朵压岛 alpha **0.241/0.242**；渐隐 40 帧单调、最大单帧变化 0.081（无跳变）、26 帧（0.43s）收敛；同 t 不同 dt 位置逐字相同、600s 无 NaN、折算每帧最大位移 0.0043；网格 3268 点 + 12 朵云心拾取「云」**0 次**。
- 证据：`test/t-s21-cloud.mjs` **8/8 PASS**；截图 `evidence/s21-cloud-*.png`（14 张，含三帧渐隐）。

## 3. 契约与硬约束核对

| 约束 | 结果 |
|---|---|
| 不动契约 | `contract-0.2-R3-FROZEN-v1.1.tar.gz` sha256 `cb155cdd…593012`（394,966 B）**未改**；全量契约回归见 §6 |
| 不动经济默认数值 | 未改 `land_config_v3.json`（sha256 `2b0a1c1f…daf54e`）、未改任何 b0/B/费率/门槛；只读展示层新增文字 |
| 不动存档 schema | 存档键/schema 3 未动；新增只是展示与排序 |
| 不新增调试事件 | 未加 `DEBUG_*` 事件；新增的都是 `window.__wyszzDebug` **只读查询/测试钩子**（内部包才有），正式包零残留（见 §7） |
| 不改建筑开业门槛 | 开业条件仍由核心 `openBuilding` 判定；卡内数字全部来自 `BuildingRow` 只读演算 |
| 不回退 S-20 手感 | 默认俯仰/距离/雾/平滑/惯性/双击回全岛断言全部保留并通过（`t-s20-camera` 57/57、`s20-node`、`s20-hud-layout` 矩阵均 PASS） |
| 测试只加不删 | 旧断言零删除；仅 3 处「资源上限/材质数」按文档化 old→new 调整（见 §4） |

## 4. 测试变更（old → new，含原因）

1. `test/t-visual.mjs` T12b：世界材质断言 `7 → 19`。原因：S-21 让 12 朵云各自持有独立材质以支持逐朵透明度（5 基础 + hitMat + matDiamond + 12 = 19）；绘制/三角形预算断言全部保留。
2. `test/t-land.mjs` L10a：同上 `7 → 19`；draw calls/三角形/programs 上限不变。
3. `test/t-fp-s19.mjs`：`bizpanel` 指纹锚点因未开业卡片新增「去升区」按钮而重锚（`fnv=6482e48d` → `fnv=77a51dd2:…`），其余 5 组逐字不变；锚点原文注释留痕。
4. 新增测试（只加）：`tests/s21-camera.test.ts`、`tests/s21-hud-layout.test.ts`、`test/t-s21-camera.mjs`、`test/t-s21-cloud.mjs`、`test/t-s21.mjs`、`tools/test-s21-node.mjs`、`tools/test-s21-hud-layout.mjs`，并追加到 `tools/regress.mjs` 末尾（不改动、不降低上面任何一步）。

## 5. 源码变更清单

见 `变更清单-源码差异.md`：**新增 9 / 修改 25 / 删除 0**（172 → 181 文件；排除 node_modules/dist/evidence/tasks-out）。
核心新增：`src/game/fingerprints-s21.ts`、`src/render/cloud-alpha.ts`、5 个 S-21 测试 + 2 个 Node 包装脚本。
核心修改：`src/render/camera.ts`、`src/render/world.ts`、`src/app/app.ts`、`src/app/input.ts`、`src/game/session.ts`、`src/ui/hud-layout.ts`、`src/ui/hud.ts`、`src/game/fingerprints-s19.ts`（重锚）、版本串 9 处、`tools/regress.mjs`。

## 6. 回归结果

### 6.1 全量回归（`npm run regress`，48 步，2026-10-21 15:32 CST，日志 `hm032/evidence/regress-20261021-073157/`）

| # | 步骤 | 结果 |
|---|---|---|
| 1 | 类型检查 tsc | PASS（无输出） |
| 2 | 构建（core+内部包+正式包） | PASS（web `main-b5c4ff437f.js` 755.8KiB；wechat `game.js` 760.4KiB sha256 `969f36f399c567f4…`） |
| 3 | 契约样例 fixtures | PASS 32/32 |
| 4 | 会话回放 replay | PASS 32/32 |
| 5 | 核心护栏 core-guards | PASS 19/19 |
| 6 | 玩法 gameplay | PASS 30/30 |
| 7 | UI | PASS 30/30 |
| 8 | 视觉 visual | PASS 18/18 |
| 9 | 浏览器测试（全量） | 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 | PASS 16/16 |
| 20 | 买地端到端(S-08.7) | PASS **61/61** |
| 21 | 微信包买地/调试面板(S-08) | PASS 13/13 |
| 22 | 指纹失败：正式包拒绝/内部包继续 | PASS 12/12 |
| 23 | 街区面板/角色卡窄屏矩阵(S-10.5) | PASS 165888 用例 / 10393520 断言 / 违反 0 |
| 24 | S-10 Node | PASS 18/18 · 14/14 |
| 25 | 街区升级/居民/角色卡 端到端 | 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 | 报告间距+飘字落点窄屏矩阵 | PASS 648 用例 / 1738668 断言 / 违反 0 |
| 34 | 托盘让位/飘字底板 端到端(S-12b) | PASS 69/69 |
| 35 | 微信替身：报告间距/飘字底板 | PASS 8/8 |
| 36 | S-19 经营面板/购地窄屏矩阵 | PASS 288 组合 / 66816 断言 / 违反 0 |
| 37 | S-19 Node | PASS |
| 38 | S-19 指纹变异锚点 | PASS |
| 39 | S-19 端到端 | PASS **69/69** |
| 40 | S-20 回全岛按钮窄屏矩阵 | PASS 480 用例 / 8640 断言 / 违反 0 |
| 41 | S-20 Node（平滑/惯性/双指/双击） | PASS 32 断言 |
| 42 | S-20 端到端（双指/双击/回全岛/手势读数） | PASS **57/57** |
| 43 | S-20 指纹变异锚点 | PASS 14/14 |
| 44 | S-21 Node（俯仰限位/低俯仰距离/pan 收紧/雾/云 alpha/指纹） | PASS 66 断言 |
| 45 | S-21 HUD 窄屏矩阵（建筑入口/目标提示/未开业卡片） | PASS 30 组合 / 1104 断言 / 违反 0 |
| 46 | S-21 相机视角端到端 | PASS **13/13** |
| 47 | S-21 云端到端 | PASS **8/8** |
| 48 | S-21 端到端（一键买/可发现性/开业全链路） | PASS **12/12** |

**合计：执行 48 步，通过 48 步，失败 0，跳过 0；总耗时 701.3s；结论 PASS（全量回归通过）。**

> 说明：本任务期间共跑 3 次全量回归；第 1 次 45/48（3 步因**测试自身**未适配新结构挂掉：S-19 旧矩阵缺新字段、S-21 矩阵内边距口径、S-21 D04 断言依赖相机动画中间态），第 2 次 47/48（云端到端 C03 阈值把「相机俯仰动画期间目标值变化」误当 alpha 跳变），均为测试修正，**无产品 bug**；第 3 次全 PASS。三次失败日志全部保留在 `evidence/regress-*`。

## 7. 四份交付包

### 7.1 打包与独立校验（`/tmp/s21-pkg/pack.mjs` + `verify.mjs`，**PASS 44/44**）

| 包 | 字节 | sha256 |
|---|---|---|
| `叫我大岛主-0.3.2-网页-正式包.zip` | 213,392 | `3316f1b9736c33e0f614edf1627b4e6980ef3bb7c18fbf10b9c7d474573cec68` |
| `叫我大岛主-0.3.2-网页-内部包.zip` | 226,761 | `cb7e4a31f2cd2aa583ee38a6212b6467a0017af5937147c7044b38f783f3cabb` |
| `叫我大岛主-0.3.2-微信-正式包.zip` | 215,314 | `ff3fbe2a4e7e89dfff509569e9bb4b4d0319a1cfe7b604c4786854bbdcfd5154` |
| `叫我大岛主-0.3.2-微信-内部包.zip` | 229,588 | `44579cd6a6eac84c7c3fd3293c1497eadc520e14c8ee091ec5def871ba58d012` |

- `dist-交付件sha256.txt`：2,865 B，18 条（4 包 + 14 个 dist 文件），sha256 `9120e7cb4b5c8ccd1114c87130ee5628f9e7033b1b307350c2d2e6a6ea19fbe6`；**真实 `sha256sum -c` 18/18 OK（exit 0）**
- 正式包零残留：`dist/web`、`dist/wechat` 的 `__wyszzDebug`=0、调试词字面量=0、正则=0、BigInt 标识符=0、BigInt 字面量=0；内部包对照 `__wyszzDebug`=1（字面量 15 / 正则 13）
- MANIFEST：四目录 `version=0.3.2`、channel 正确、工程名 `wyszz-island-0.3.2` / `wyszz-island-0.3.2-internal`；zip ↔ dist 逐文件一致（3/3/3/4 条目）
- 结论：`evidence/pack-结论.json`、`evidence/verify-结论.json`（均 PASS）

## 8. 出码（微信预览码）

### 8.1 回执

- 出码：**正式 ✅ / 内部 ✅**（VM 微信开发者工具 CLI `2.02.2608080`；`√ Using AppID: wx1c0ae0869ea1424f`；`√ preview`；TOTAL 正式 840.5 KB / 内部 887.3 KB ≈ game.js ×1.10）
- 正式码图：`/vol1/ai/projects/wyszz-new/frontend-rebuild-hm/tasks-out/S-21/出码/qr-formal.png`（PNG 940×940，42,351 B，sha256 `e83ac6d83f482ca7…`）
- 内部码图：`/vol1/ai/projects/wyszz-new/frontend-rebuild-hm/tasks-out/S-21/出码/qr-internal.png`（PNG 940×940，43,026 B，sha256 `159b911235207420…`）
- 生成时间：**15:47 CST**（两枚，VM 落盘时间）；推算过期 **≈16:12 CST**（25 分钟，未实测）
- 包 sha 核对：formal `ff3fbe2a` / internal `44579cd6`（与交付清单逐字一致）；`game.js` 未改（formal `969f36f3…`、internal `1d830fb3…`，zip 内与 dist 内一致）
- 只改 VM 副本：`project.config.json` appid `touristappid` → `wx1c0ae0869ea1424f`（formal `3f5b67ca…`→`55cf3a4f…`、internal `ebfeee1f…`→`c9104cd6…`），并按 SOP 重算 MANIFEST 中该项 bytes/sha256
- 未验证：真机扫码进入/运行、25 分钟有效期、上传审核






## 9. 只读基线（hm031 / hm03 / hm023）

- 开工记录：`只读基线-三棵树.sha256`（495 条，2026-10-21 14:25）
- 收工复核：`evidence/只读基线-复核.json` + 脚本 `evidence/只读基线-复核脚本.mjs`
  - 树 A `frontend-rebuild-hm031`：172/172 文件一致，聚合 `02ad923c…0895` ✔
  - 树 B `frontend-rebuild-hm03`：165/165，聚合 `2dcf8c0c…7b76` ✔
  - 树 C `frontend-rebuild-hm023`：158/158，聚合 `2b5cba13…9408` ✔
  - 总聚合 `aab15ebc…71ab` ✔；契约包与 `land_config_v3.json` 单列复核 ✔

## 10. 已知限制 / 未验证（诚实清单）

- **未在真机验证**：所有结论来自 SwiftShader 无头 Chromium + Node 纯逻辑；真机手感/帧率/发热需机主实测。
- 真机 25 分钟出码有效期未实测（按微信规则推算）。
- 微信开发者工具模拟器无 3D（工具自带 `--use-gl=disabled`），故「云/岛底观感」只能在 Web 版无头截图里看，模拟器画面为空属已知限制。
- 窄屏（320×568）下「下个目标」超长文案会用紧凑同义文案（保留单位，省略「开业」二字）；极极端数字才省略号截断。
- 云遮挡判定是屏幕空间软边近似（0.92↔1.08 倍岛半径），不是逐三角形精确遮挡；极端机位可能有 1 帧误差。
- 出码仅验证「码图生成成功 + 包 sha 一致」，未验证扫码进入/运行。

## 11. 回滚方法

- 本包整体回滚：用基线 `frontend-rebuild-hm031`（0.3.1 真机通过）作为锚点，直接以 hm031 出包即可；hm032 为独立副本，互不影响。
- 只回滚某一项：见 `变更清单-源码差异.md` 按文件恢复（清单给出每文件旧/新 sha256，可与 `hm032开工sha256.txt` 对账）。
- 开工备份：`hm032-开工备份.tgz`（sha256 `3150648b…3bb1`），解包即回到「刚复制完、尚未改任何源码」的状态。

## 12. 附件

- 测试结果 JSON：`evidence/s21-*.json`、`evidence/s19-results.json`、`evidence/regress-<时间戳>/`
- 截图：`evidence/s21-cam-*.png`、`s21-ui-*.png`、`s21-cloud-*.png`
- 打包/扫描：`evidence/pack-结论.json`、`evidence/verify-结论.json`、`dist-交付件sha256.txt`
- 出码：`出码/qr-formal.png`、`出码/qr-internal.png`
- 只读基线：`只读基线-三棵树.sha256`、`hm032开工sha256.txt`、`hm032-开工备份.tgz`
