# S-19 总报告 · 0.3.0「全景经营入口」

> 工作树：`/vol1/ai/projects/wyszz-new/frontend-rebuild-hm03/`（自 hm023 = 0.2.4 整树复制）
> 回滚锚点：`/vol1/ai/projects/wyszz-new/frontend-rebuild-hm023/`（0.2.4，全程只读）
> 契约：`contract-0.2-R3-FROZEN-v1.1.tar.gz`（只读，sha256 `cb155cdd…93012`）
> 报告生成：2026-10-20 PDT

## 1. 目标与范围

把三条经营线（建筑升级 / 设施 / 宣传）、开业、城区行政做成**可玩 UI 入口**，修掉 F-8
（购地候选预览不可见/不可点），并把 N1/N2/N3 三个体验项做进 0.3.0；**不改任何默认经济数字**，
只把“以后要改数”的路径铺好（M5）。基线要求：M1–M4 + 全量回归全绿 + 四包交付。

本轮完成：**M1 ✅ M2 ✅ M3 ✅ M4 ✅ M5 ✅ N1 ✅ N2 ✅ N3 ✅**；M6 按优先级未做（不影响基线）。

## 2. 环境与起点

| 项 | 值 |
| --- | --- |
| 起点 | hm023（0.2.4）整树复制，132 MB；删除 `dist/`、`evidence/` |
| 开工指纹 | hm03 文件 **158 条**（排除 node_modules/dist/evidence）；`hm03-开工备份.tgz` 388,943 B / sha256 `79b57dba…54dc7c` |
| 回滚锚点 | hm023 四包 sha 记录在 `回滚锚点-hm023-0.2.4.sha256`；hm023 全树指纹 `8781212c…76c31`；hm023 版本保持 0.2.4 |
| 工具链 | Node v24（`/mnt/ssd/apps/nodejs_v24/bin`）、esbuild、puppeteer-core headless Chromium |
| 版本 | `0.3.0`（package.json、build-web/build-wechat、内部包水印、报告版本字段全部同步） |

## 3. 改动总览（按交付项）

| 项 | 改动 | 关键文件 |
| --- | --- | --- |
| M1 / F-8 | 候选标记默认 `visible=false` 且不进拾取；购地模式开才显示/可点；报价卡、候选购买恢复；相机 `frameRadius` 仍含候选，开关购地不跳镜头 | `render/landlayer.ts`、`render/world.ts`、`app/app.ts` |
| M2 建筑列表/卡片 | 街区栏右侧 80px「建筑 ›」入口；列表 4 行（名称、开业状态、L/F/A、该楼金币每分、门槛）；点行 → 卡片：三线升级（等级/设施/宣传）+ 开业 + 城区入口；世界画面点三栋楼也能开对应卡片；窄屏自适应三档字号（普通/紧凑/紧） | `ui/hud-layout.ts`、`ui/hud.ts`、`game/session.ts`、`app/app.ts` |
| M3 开业 | 卡片「开业」按钮显示 `2×B` 费用与门槛；未达区等级禁用；成功后产速立即计入核心与 HUD；保证金币不足提示 | `core/actions.ts`（既有路径）、`game/session.ts`、`ui/hud.ts` |
| M4 城区 | 城区面板：D、全城增益 +6%/级、下一级费用 `ceil(2100×1.45^(D−1))`、4 栋楼开业门槛（已解锁/未解锁/已开业）、升级按钮；250ms 同按钮防误触 | `core/rates.ts`（只读调用）、`ui/hud-layout.ts`、`app/app.ts` |
| M5 经济预留 | **0 处数字改动**；新增只读 `buildingMilli`（逐楼贡献，不参与判定）；内部包「数值总览」只读页；`经济参数地图.md`、`改数流程.md`；单点公式审计 | `core/rates.ts`、`ui/debug-panel.ts`、本目录文档 |
| N1 一键购买 | 购地模式内 68×49 按钮；模态确认框「将购买 N 块 · 共 X 金币 / 余额 Y · 买后剩 Z」；N = 按核心候选自然序连续可负担块数（上限 78 次扩建）；逐块走核心 `BUY_TILE`，批量结束只发一次结果提示；无撤销/退款/自动卖地 | `app/app.ts`、`game/session.ts`、`ui/hud-layout.ts` |
| N2 缩放+双指平移 | `CAM.zoomMax 1.45 → 3.0`；双指拖拽平移，pan 限制在岛内 `panMax=0.95·R·(1−1/zoom)`；单指旋转/惯性/俯仰不变；手势按“手势起点累计位移”锁定缩放/平移，避免两指事件逐点到达时抖动；报告打开/采样中禁平移；买地/后台/重载不回弹 | `render/camera.ts`、`app/input.ts`、`app/app.ts` |
| N3 列表+特写 | 列表行点击 → 相机中心对准该楼并放大到 zoom 3；「回全岛」复位（zoom 1、pan 0、默认视角）；列表数据全部来自 core，前端 0 算术；0.3.2 再做列/图标开关与已购地清单 | `app/app.ts`、`render/camera.ts`、`ui/hud-layout.ts` |

## 4. 关键设计裁决（本轮定稿）

1. **候选标记默认隐藏**：F-8 的根因是候选 mesh 不可拾取；修法不是“常显”，而是“购地模式才显示/可点”，
   且 `pickables` 始终包含候选 mesh。相机 `frameRadius` 仍按候选算，开关购地不改变取景（A07 断言）。
2. **N1 只走核心事务**：批量 = 逐块 `BUY_TILE`，计划用 `quoteTile + coreBuyTile` 模拟；顺序严格 = `candidates()` 自然序；
   批量结束只 `refreshView` 一次、只弹一条 toast；**不做撤销/退款/自动卖地**（与需求一致）。
3. **N2 手势锁定**：触摸事件里两指 move 是分开到达的，逐事件判“间距 vs 质心”会把同向拖动误判成缩放；
   改为**手势内累计位移定型**（至少收齐两指各一次 move），定型后整段手势不再换模式。
4. **N3 相机特写**：点行 → `focusOn(buildingCenter, 3)`；「回全岛」= `resetFocus()`（zoom 1、pan 0、默认俯仰）；
   列表数据由 `session.buildingRows()` 统一给出，UI 只排版。
5. **互斥关系**：经营面板与报价卡/街区抽屉/居民卡/报告互斥；报告打开或采样中，建筑入口拒绝并提示「报告打开中」。
6. **250ms 防误触**：同一升级/开业/城区按钮 250ms 内重复点击忽略一次；不同按钮互不影响（避免“连点升两级”）。

## 5. 测试与数字

| 测试 | 结果 | 说明 |
| --- | --- | --- |
| 全量回归 `npm run regress` | **39/39 步 PASS**（572.7s，742 条 PASS 断言） | 类型检查/构建/契约 32 组 9,769 case/属性 193,500 步/隔离/正式包扫描/烟雾/HUD 矩阵/买地/微信/S-10/S-12/S-12b/S-19 全绿 |
| S-19 端到端 `test/t-s19.mjs` | **65/65 PASS**，pageerror **0** | F-8/M2/M3/M4/N1/N2/N3 + 版本/指纹；含 320/360/390/414/430 窄屏矩阵 |
| 布局矩阵 `test:s19-hud-layout` | 288 组合 / **65,664 断言 / 违反 0** | WIDTHS 320–1024 × HEIGHTS 568–932 × safeTop 0/24/47 × safeBottom 0/34 |
| 相机纯函数 `test:s19-node` | **25/25 PASS** | panLimit/clampPan/worldPerPixel/zoom clamp/focus/reset/无惯性/拖拽俯仰限制 |
| S-19 指纹变异 `test:fp-s19` | **14/14 PASS** | 4 个变异锚点（saveW 86→85、提示行 h 40→39、panel pad 8→9、pan 系数 0.95→0.94）正式包全部 HALT |
| 购地旧回归 `test/t-land.mjs` | **61 PASS / 0 FAIL** | 默认候选隐藏 + 开购地后可见（L01d/L01e）均覆盖 |
| 类型检查 `tsc --noEmit` | **0 error** | 正式/内部构建前置 |
| 正式包扫描 `scan:formal` | **PASS** | 正式 web/微信 0 调试残留；负例与内部包如期命中 |

### N1 关键数字（可复核）

- 新游戏：余额 60.0 金币；一键计划 **2 块 / 共 35 金币 / 买后剩 25.0**（首块 15、次块 20，顺序 = 候选自然序）。
- 批量 2 块后的存档与“逐块购买 2 次（同一 `session.buyTile` 事务）”**逐字节一致：532 B**。
- 差 1 金币：计划 0 块、按钮禁用、点击提示「金币不足，还差 1 金币」，不弹确认、不扣钱。
- 离线挂起：按钮禁用 + 提示「离线结算中」，计划拒绝。
- 满岛：一次买 78 块（85/85），总价与独立逐块模拟一致；再点提示「全岛已满，没有可购买的地块」。
- 写档失败：交易不中断（内存照常成交、无弹窗），存档错误被会话吞掉。

### N2 关键数字

- 新游戏 fitR ≈ **8.92**；`panMax` = 0 / **4.237** / **5.649**（zoom 1/2/3）；zoom 3 时相机距离 ≈ 21.1。
- 5 屏 × 3 态截图 15 张（默认/最大放大/平移后）；买地、切后台、重载后镜头均不回弹。
- 双指平移不会触发买地/开业/升级/领奖/街区栏滑动/报告采样；报告打开与采样中平移禁用。

## 6. 窄屏与截图（证据目录）

`tasks-out/S-19/evidence/`：

- F-8 / 购地底栏 5 屏：`s19-f8-{320x568,360x640,390x844,414x896,430x932}.png`
- N2 缩放+平移 5 屏 × 3 态 15 张：`s19-n2-<屏>-{1默认,2最大放大,3平移后}.png`
- 经营列表/卡片：`s19-n3-list.png`、`s19-biz-card.png`
- 早期冒烟：`smoke-default.png`、`smoke-focus.png`、`smoke-card.png`

320×568 + 大安全区：经营面板走 `BIZ_TIGHT` 档（pad 4 / 行高 36 / 按钮 40），列表与卡片均无溢出；
购地提示行 + 一键购买按钮不与升级/存档按钮相交（矩阵与 e2e 双覆盖）。

## 7. 指纹变更

| 组 | 键数 | 内容 | 变异锚点 |
| --- | --- | --- | --- |
| 既有 S02/S10/S12/S12Int | 不变 | 底栏/街区/报告/内部接口几何 | 原有锚点保持 |
| **新增 S19（fp6）** | **6**：`bottom`/`buyhint`/`confirm`/`bizpanel`/`camera`/`rates` | 购地底栏几何、提示行+一键按钮、确认框、经营面板三态排版、相机 panLimit/worldPerPixel、逐楼产速 | **4 个**（saveW、hint h、panel pad、pan 系数）|

FP 变更统计：**新增 1 组 6 个键、4 个变异锚点**；既有指纹期望值 0 处改动（仅版本号相关文案随 0.3.0 更新）。
正式包任一 S19 指纹失败 ⇒ 拒绝启动；内部包仅告警。

## 8. 交付件（四包 + 校验）

四包由 `npm run build` 产出，独立 agent B 重算 MANIFEST sha256 并打包校验：

| 包 | 大小 | 文件 | zip sha256（完整值见清单） |
| --- | --- | --- | --- |
| 微信-正式 | 209,135 B | 4 | `c842d9fae4c9b8c08f8cada44cf523af97a93022cf00b220a662802a5a0b2f68` |
| 微信-内部 | 222,000 B | 4 | `a06769a33b9f9cc3e21f1c40eed5ff8546cc9d1f32230cc47777f18d631bb1e6` |
| 网页-正式 | 207,268 B | 3 | `0c483605ba02aead45fe65018b3e87f5c8174f7aff09856964acbf45faba1e02` |
| 网页-内部 | 219,335 B | 3 | `3c3d202fdacbfbde7644e319f9fa5993dbbdd006722fbe85c3b30d56514690be` |

- dist 原始文件：微信正式 `game.js` 757,601 B sha `d3936422…`；微信内部 `game.js` 793,598 B sha `57b70f5f…`；
  网页正式 `main-8fdbb90b97.js` 752,994 B sha `8fdbb90b…`；网页内部 `main-d70e796381.js` 786,904 B sha `d70e7963…`。
- `MANIFEST.json` 重算：**4/4 目录、10/10 文件全部一致**；`unzip -t` 4/4 PASS；解包 `diff -r` 与 dist 4/4 一致。
- `dist-交付件sha256.txt`：`sha256sum -c` **18/18 OK**（4 zip + dist 14 文件）。
- 校验报告：`agents/B/交付件校验.md`。

## 9. 未验证 / 风险（如实列出）

1. **真机微信未跑**：本轮只有微信替身（Worker 无 DOM + 模拟 wx）与 puppeteer 触摸合成；未开微信开发者工具、未装真机。
2. **双指手势手感**：仅 CDP 合成触摸（同向/反向双指），真实手指抖动/多指时序未验证；逻辑上已做手势锁定与 UI 多指吞掉。
3. **GPU/性能**：headless Chromium 的 draw calls/三角数可用，但真机 GPU 帧率未测；zoom 3 下未见裁切/空洞，真机待验。
4. **正式包安装**：四包只做了文件级校验与网页内部包 e2e；微信正式包未在开发者工具里导入运行。
5. **经济数字**：本轮 0 改动；`经济参数地图.md` 的审计是静态检索 + 单测口径，未做全量属性测试（0.3.1 可补）。
6. **M6 未做**：按优先级（M1>…>M6）在时间不足时放弃，不影响基线。

## 10. 完成度清单（逐项）

| 项 | 状态 | 说明 |
| --- | --- | --- |
| M1 / F-8 候选预览与购买 | ✅ 完成 | 默认隐藏、开购地可见可点、报价卡购买、镜头不跳 |
| M2 建筑列表 + 卡片（三线） | ✅ 完成 | 入口、4 行列表、三线升级、开业、城区入口 |
| M3 开业 | ✅ 完成 | 门槛校验、2×B 费用、产速立即生效、不足提示 |
| M4 城区行政 | ✅ 完成 | D/增益/下一价/四门槛、升级、250ms 防误触 |
| M5 经济参数预留 | ✅ 完成 | 0 改数；地图/流程文档；只读总览；`buildingMilli` 审计 |
| N1 一键购买 | ✅ 完成 | 确认框、自然序、逐字节一致、6 类边界 |
| N2 缩放 + 双指平移（一期） | ✅ 完成 | zoomMax 3.0、岛内夹取、手势锁定、报告禁用、不回弹；5×3 截图 |
| N3 列表 + 相机特写 | ✅ 完成 | 4 行、点行 zoom 3、回全岛、数据全来自 core |
| N3 二期（列/图标开关、已购地清单） | ⏭ 未做（0.3.2） | 按计划推迟，非本轮基线 |
| M6（最低优先级） | ⏭ 未做 | 时间不足按优先级放弃 |

## 11. 回滚与后续

- **回滚**：hm023 保持 0.2.4 不动，四包 sha 在 `回滚锚点-hm023-0.2.4.sha256`；hm03 开工备份 `hm03-开工备份.tgz`。
  N2 若真机不达标，按预案把 `camera.ts` 的 `zoomMax` 与 `input.ts` 的双指分支回退到 1.45/无平移，并在进度里记「N2 回退 + 原因」。
- **后续（0.3.1/0.3.2）**：0.3.2 做 N3 二期（列/图标开关、已购地清单）；真机双指手感与微信正式包导入验证；
  真要调数时按 `改数流程.md` 单点改、全量回归、重算指纹后再发版。

## 附：文件变更清单（脚本生成）

见 `文件变更清单.txt`：新增 **7**、修改 **24**、删除 **0**（hm023 → hm03，排除 node_modules/dist/evidence）。
