# S-40 · 总报告（城市模块库收口）

> 2026-10-27（北京时间）｜原实现主协调者：Lead（本对话）｜依据：`docs/65` 原任务书、`docs/68` 独立复核（判未通过）、`docs/69` 交付收口任务书
> 工作树：`/vol1/ai/projects/wyszz-new/frontend-rebuild-hm044-city`｜交付根：`/vol1/ai/projects/wyszz-new/frontend-rebuild-hm/tasks-out/S-40`

## 0 一句话结论

**模块技术证据齐，整体 S-40 未验收**：单入口 `buildCity`、四类建筑×tier0..4（含 hall 满级）、三画风同几何、车人三档、85 块满岛预算达标（89,336 三角形 / 10 draw call / 3 材质 / 128.1ms 构建（Node 9 组最坏；C4 浏览器 177.8ms）），55 项原测试 55/55 通过，装配示例 14 行可实跑、dispose 生命周期闭环；**但独立 U1 与 UX 各提出 1 条候选 P0（C 夜景过暗 / 阶梯模式缩放构图弹飞）及多条 P1，均待机主裁量，故整体 S-40 不能判"已验收/通过"**。
**本轮收口补齐了 docs/68 指出的 3 个不达标项**（示例、生命周期证据、口径/数值）。
> ⚠️ **本文件为收口终稿**：C4 截图 30 张 + 性能表已交付并经 Lead 独立核验（`Lead/C4核验结果.txt`，33 项全过）；**独立 U1 已交付**（2026-10-27 22:00 定稿，1 P0 / 6 P1 / 7 P2）、**独立 UX 已交付**（2026-10-27 22:07:51 定稿，1 P0 / 4 P1 / 6 P2）。**P0/P1 均为机主裁量项，未裁量前不填 0、不宣称通过/不通过**（逐项见 `处理决定表.md`）。**S-31 接线未做**（待 S-40 验收 + 0.3.5 机主定版）；真机/微信运行仍未验证。
>
> **时间线（分列，不混写）**：源码/HTML/PNG **取证轮 = 2026-10-27 21:38:12**（`metrics.generatedAt`）→ C4 冻结声明 21:47 → 性能表**文档勘误** 21:55:12（仅 (e-2) 贴图口径，不改图/HTML/shot）→ U1 定稿 22:00 → UX 定稿 22:07:51（此后未再改内容；`UX/独立UX自检.md` sha256 `d1708604…`、`UX/量测记录.txt` sha256 `632b73be…`）。

## 1 交付物索引（全部在本目录）

| # | 交付物 | 路径 | 状态 |
|---|---|---|---|
| 1 | 迁移契约（唯一入口/坐标系/tier/预算/禁项/示例） | `hm044-city/src/render/city/CITY_API.md` | ✅ 本轮同步（§1 导出、§2.3 示例、§7 预算、§7.5 生命周期） |
| 2 | 迁移就绪清单（给 S-31 逐条打勾） | `迁移就绪清单.md` | ✅ 本轮补 dispose 结束路径与实时口径 |
| 3 | 模块库源码 | `hm044-city/src/render/city/**`（19 个 `.ts`） | ✅ 实现本轮 0 改动 |
| 4 | 四套 Node 测试（55 项） | `hm044-city/test/city-*.test.mjs` | ✅ 55/55（日志 `Lead/测试复跑.log`） |
| 5 | 装配示例运行日志（14 行可执行 + tsc） | `Lead/装配示例运行日志.txt` | ✅ |
| 6 | dispose 生命周期实测 | `Lead/dispose生命周期证据.txt` | ✅ |
| 7 | 预算实测（9 组） | `Lead/预算实测.txt` / `.json` | ✅ |
| 8 | 口径同步（旧→新+来源） | `Lead/口径同步.md` | ✅ |
| 9 | 修复回执（对账 docs/68 + 复核方 21:07 复验） | `Lead/修复回执.md` | ✅ |
| 10 | C4 正式截图（30 张 + 覆盖矩阵 18 项） | `截图/**`、`C4/截图清单.md`、`C4/覆盖矩阵.md` | ✅ 已交付·Lead 核验通过 |
| 11 | 性能表（三口径 + 四门槛 + 采集校准） | `性能表.md` | ✅ 已交付·Lead 核验通过 |
| 12 | 独立 U1 玩家锐评（1 P0 / 6 P1 / 7 P2） | `U1/玩家视角锐评.md` | ✅ 已交付（22:00 定稿，sha256 `a17858c3…`） |
| 13 | 处理决定表（U1+UX 逐项，机主裁量=待裁量/执行=未执行） | `处理决定表.md` | ✅ 已生成（待机主裁量） |
| 14 | 独立 UX 自检（44px/遮挡/误触/返回） | `UX/独立UX自检.md`（`d1708604…`）+ `UX/量测记录.txt`（`632b73be…`） | ✅ 已交付（22:07:51 定稿，1 P0 / 4 P1 / 6 P2） |

## 2 契约与能力（摘要，详见 CITY_API.md）

- **唯一入口**：`buildCity(ctx: CityBuildCtx): CityBuildResult`；`ctx` 六个必填（`blocks/hallTier/style/traffic/ped/seed`）+ 可选扩展（`night/shadows/pitch/ground`）。
- **四类建筑 × tier0..4**：住宅/商业/市政厅/公园为主线，另有地标/工业两条内容线；hall 有 0..4 全档 + 满级形态（广场+大台阶+门廊柱列+钟塔+旗杆）。
- **三画风 A/B/C = 同一份几何**：实测同档下三角形/draw call/材质完全相等，高档三画风**未量化 position 字节 SHA256 一致**；差异只在 palette（16 色全异）、glow 强度（昼 0/0.12/0.55，夜 0.62/0.9/1.3）、光照/雾/天空。
- **车人三档**：车 0/14/30、人 0/28/60；关档不建 InstancedMesh（0 实例）；位置=时间纯函数，无累积误差；运行时 `setTraffic/setPed` 只重建实例。
- **pickables**：85 块 → 69 个不可见代理（0 draw call / 0 三角形），`raycast` 命中后 `userData.blockId` 直接给抽屉。
- **资源生命周期**：实例自有资源 `city.dispose()`；进程共享材质 `disposeCityMaterials()`（最后使用者调用）。

## 3 本轮实测数字（来源：可复跑脚本，不手写）

### 3.1 预算（full85 / hallTier=4 / seed=42，Node i5-14400）

| 车人档 | 三角形 | draw call | 材质 | 实例 | 构建 ms |
|---:|---:|---:|---:|---:|---:|
| 关/关 | 84,500 | 7 | 3 | 245 | 54.6 ~ 128.1 |
| 低/低 | 86,744 | 10 | 3 | 287 | 同上 |
| 高/高 | 89,336 | 10 | 3 | 335 | 同上 |

预算（docs/65，未降级）：≤150k 三角形 / ≤70 draw call / ≤12 材质 / ≤300ms 桌面构建 → **全部通过**（余量：三角形 40%、draw call 86%、构建 60%）。
口径：`city.stats` = 构建快照；实时实例数用 `city.density`；浏览器整帧（含阴影/demo 环境）见 `性能表.md`。

### 3.2 三画风同几何证据

- 同一车人档下 A/B/C 三角形、draw call、材质数**完全相等**（`预算实测.txt` 表 3）；
- 高档三画风未量化 `position` 字节 SHA256：A/B/C 均 `245468f0cd16…`（完全一致）；
- 90 组单元级（6 内容线 × tier0..4 × 变体0..2 × 3 画风）：三角形数与顶点位置多重集签名逐位一致（`test/city-style.test.mjs` 8/8）。

### 3.3 测试

`node --test test/city-contract.test.mjs test/city-migration.test.mjs test/city-layout.test.mjs test/city-style.test.mjs` → **55 tests / 55 pass / 0 fail / exit 0**（`Lead/测试复跑.log`）。
其中本轮补充的「实际释放证据」以脚本形式交付（`Lead/校验-资源生命周期.mjs`），避免改动原测试断言。

## 4 截图与性能（C4 已交付，Lead 独立核验通过）

**核验记录**：`Lead/C4核验结果.txt`（33 项全过，脚本 `Lead/核验C4交付.mjs` 只读复跑）。稳定快照：`metrics.generatedAt = 2026-10-27 21:38:12（北京时间）`、`shot.mjs sha256 = a7fee7a5…`、`HTML sha256 = 22b148da…`。

### 4.1 截图（30 张，`tasks-out/S-40/截图/`）

| 组 | 张数 | 内容 |
|---|---:|---|
| 五机位 × 三画风 | 15 | 01–15：A/B 昼、C 夜；全景/俯视/街区近景/市政厅广场/滨水码头 |
| 车流三档 | 3 | 16–18：关/低/高（B·全景） |
| 行人三档 | 3 | 19–21：关/低/高（B·街区近景） |
| 满岛 85 块正交俯视 | 1 | 22（车高人高） |
| 市政厅 tier4 满级特写 | 1 | 23 |
| 逐类逐档阶梯 | 6 | 25–30：住宅/商业/市政厅/公园/地标/工业码头，各 T0..T4 五座 + T0..T4 标注芯片 |
| 俯视·关阴影（参照，非验收） | 1 | 24，命名已标“参照非验收” |

> **22 号图 HUD 口径歧义（2026-10-27 22:15 登记，不改图）**：HUD「三角形 86,744」是**构建快照**（构建档=车低人低），不是该图显示档（车高人高）的构建快照 89,336；「实例数 335」是**实时值**。HUD 标签未标来源 ⇒ P2 级文案待完善项，详见 `C4/HUD口径说明.md` 与 `C4/截图说明.md` §7；若修标签重出图必须整轮新快照 + U1/UX 重绑。

覆盖矩阵 18 项全 ✅、0 ❌（`C4/覆盖矩阵.md`）；30 张逐张 SHA 与实际文件、`C4/metrics.json`、`C4/快照sha256.txt` **三方一致**（Lead 复核 0 孤儿 / 0 缺失 / 0 不符）。

### 4.2 三方 sha 绑定

| 对象 | sha256 | 说明 |
|---|---|---|
| 19 个 `src/render/city/*.ts` | 逐文件 + 合并 `35164273…` | 与当前源码逐文件一致（Lead 复算 19/19） |
| `dist/city-demo.html` | `22b148da…`（670,472 B） | 重跑构建复算一致（确定性构建） |
| `shot.mjs`（取证脚本） | `a7fee7a5…` | v3 封存快照隔离；v1 `26a8f20e`（外网漏报）、v2 `34290f1f`（字串过滤漏真页错误）均留失败证明 |
| 30 张截图 | 逐张 sha | 与上述同一快照绑定 |

### 4.3 性能表三口径（`性能表.md`）

- **(a) 构建快照** `city.stats`：车人 0/1/2 = **84,500 / 86,744 / 89,336** 三角形；draw call **7/10/10**；材质 **3**；实例快照 245/287/335 —— 与 Lead Node 侧完全一致。
- **(b) 实时实例** `city.density` + 场景图遍历：车 0/14/30、人 0/28/60、道具 245 ⇒ 合计 **245/287/335**，三画风逐档一致（证明 `stats` 快照 ≠ 实时数，实时必须读 `density`）。
- **(c) 整帧 `renderer.info`**：renderCalls **21~25**、renderTriangles **151k~159k**；附「关阴影实测 = 主 pass」与「差值 = 阴影 pass」拆解（城市 solid/glow/water 各 1、道具 4、车 2、人 1、demo 岛 2、水 2、天 1）。
- **(d) FPS**：swiftshader CPU 软渲染（≈6~11 fps 主场景），**只做相对比较**，不作为真机性能。
- **(e) 四门槛全 PASS**：三角形 89,336 ≤ 150,000；draw call 10 ≤ 70；材质 3 ≤ 12；**buildMs 177.8 ms ≤ 300**（构建快照，浏览器并发环境）。
- **贴图分列（按场景，2026-10-27 21:55:12 勘误）**：城市模块贴图 **0**（静态扫描断言）；**普通满岛** Canvas 0 / `renderer.info.memory.textures` **2**；**阶梯模式每张** Canvas **5**（T0..T4 标注芯片）/ renderer 纹理 **7**。原写法「6 个 CanvasTexture」是误把"6 类阶梯"当纹理数，已在 `性能表.md` (e-2) 更正并留版本记录 `C4/性能表版本.txt`（新 sha `c1b054b5…`）。
- **采集口径与校准**：真实页（新采集器）外网请求 0 / 请求失败 0 / pageerror 0 / console.error 0；校准页 mock 200 + console.error + pageerror 三探针全 PASS；真实页读数**在进入校准页前冻结成快照**（`frozenReal`），不使用消息子串过滤（复核方已证明子串过滤会漏报真实页错误）。旧采集器漏报证据留档于 `续接调度/外网请求漏报失败证明.log`。

### 4.4 旧问题闭环

- **「四角细长斜线」**：根因 = 观景轮 T3 的 A 字支架在透视俯视约 8.7° 下的外推视差（非坐标 bug；Node 实测单元 bbox 2.1×2.1×H15.2、InstancedMesh maxScale=1.00）；修法 = 俯视改**正交相机**，结论与旧图留档 `C4/截图说明.md` §2。
- **俯视平行斜向条带**：已确认为高楼投影（真实阴影），非穿模/非细线 artifact，留档 §6；另出 24 号关阴影参照图（非验收）。

## 5 独立 U1 锐评（已交付，2026-10-27 22:00 定稿；sha256 `a17858c3…`；机主裁量见 `处理决定表.md`）

- **执行**：独立成员 `u1-reviewer`（fresh，未参与实现），只写 `tasks-out/S-40/U1/**`；报告 `U1/玩家视角锐评.md`（273 行 / 34.6 KB / sha256 `a17858c3…`，定稿 2026-10-27 22:00 北京时间）+ 16 张证据裁剪图 + 33 文件输入快照。
- **快照绑定**：`metrics.generatedAt=2026/10/27 21:38:12`、`shot.mjs a7fee7a5…`、`HTML 22b148da…`；30 图 sha 30/30 一致；性能表绑定**勘误后**版本 `c1b054b5…`（21:55:12），旧版 `b5ce88b3…` 作废留痕。
- **一句话总评**：「远看挺能打、拉近就露怯」——白天 A/B 认楼与天际线成立、车走车道人走人行道；C 夜景黑到不可读、满岛俯视读不出中心区/主次路网、"滨水码头"没有码头、车人档位默认视角无感；点楼→抽屉契约成立但有 3 个接线坑。
- **清单**：**P0 1 条**（C 夜景过暗：俯视平均亮度 4.1%、96.7% 像素 <8% 灰度）；**P1 6 条**（满岛俯视可读性 / 车人档位无感 / 无码头形态 / 高等级住宅 vs 商业 / 三画风实测=两变量 / 接线 3 坑，其中实测 `pickables=69≠85`）；**P2 7 条**（阶梯等级感、地标跳变、取证机位、夜景偏艳、A/B 区分度、轻微穿模、Q6 次要坑）。
- **本轮 Lead 处理**：P1-6 的 3 个文档坑已修进 `CITY_API.md §6`（69 条口径 + 勿递归 raycast + `visible=false` 仍可命中 + 代理高度 ×1.05/×1.12 + hall 无法挂高亮）；P0/P1/P2 其余项**只登记不裁量**，逐项见 `处理决定表.md`（未裁量项不填 0、不宣称通过/不通过）。

## 6 未验证项（如实列出）

1. **真机 / 微信运行**：本轮只做 Node + 桌面 chromium(swiftshader) 验证，手机帧率/内存未测。
2. **S-31 真实游戏接线**：未接线、未跑游戏内点击→抽屉→购地链路（契约与 host shim 测试已覆盖，真实链路未验证）。
3. **六边形 60° 地块映射**：模块假设正交网格（`rot` 只按 90° 取整使用）；六边形岛映射方案由 S-31 决定。
4. **GPU 显存释放**：Node 只能证明 CPU 侧对象与 dispose 事件；GPU 侧依赖 three 标准 dispose 机制，真机显存未测。
5. **U1 分级**：已交付（1 P0 / 6 P1 / 7 P2，`U1/玩家视角锐评.md` sha256 `a17858c3…`）；P0/P1 由机主裁量，本轮**不填 0、不宣称通过/不通过**（逐项见 `处理决定表.md`）。
6. **UX 自检**：已交付（`UX/独立UX自检.md` 定稿 sha256 `d1708604…`，22:07:51；`UX/量测记录.txt` sha256 `632b73be…`；`UX/正式证据/` 9 件含清单 `753e45b4…`）。结论：**16/16 可见按钮 <44×44（最小 31.5×26 px）**；**P0 1 条**（阶梯模式滚轮/双指缩放把固定构图弹飞且无 UI 复位）、**P1 4 条**（44px 全不达标 / 阶梯下车流·行人虚假可点 / 无复位·无隐藏·无键盘 / 俯视 HUD 盖 2/85 块）、**P2 6 条**（面板拖拽死区、5 组重复 id 无障碍、间距 5–6px、HUD 数字格式、375 窄屏、tip 文案）。**是否放行由机主裁量**（`处理决定表.md` §4，未裁量不填 0）。
7. **浏览器整帧预算**：整帧 renderer 读数含阴影/demo 环境，与模块口径分列；是否作为 S-31 验收口径由机主定。

## 7 边界自证（本轮未越界）

- 本轮 Lead 写入：`CITY_API.md`（文档）、`tasks-out/S-40/Lead/**`、`tasks-out/S-40/{进度,迁移就绪清单,总报告,处理决定表}`；**实现代码与测试 0 改动**。
- C4 只写：`tools/city-demo/**`、`tasks-out/S-40/截图/**`、`性能表.md`、`C4/**`；中间产物在 `C4/runtime/`，未写 `/tmp` 新证据。
- U1/UX 只写各自目录（`U1/**`、`UX/**`），未改代码/截图/demo；C4 冻结期只改文档（性能表勘误、HUD 口径说明、控件/交互清单）。
- 未写：`hm035`、其它工作树、`src/app|ui|game`、`world.ts`、`camera.ts`、package.json；未新增依赖、未联网取资源、未接线、未打包游戏、未出码。

## 8 遗留与下一步

1. **机主裁量**：`处理决定表.md` —— U1 的 1 项 P0 / 6 项 P1 / 7 项 P2 + UX 结果逐项勾选（改/不改/延期）；未裁量前不填 0、不宣称通过。
2. **UX 自检结果**：已交付并回填 `处理决定表.md` §4（`UX/独立UX自检.md` 定稿 sha256 `d1708604…`，22:07:51）；44px 命中/阶梯复位/HUD 遮挡等 P0/P1 同样**待机主裁量**，本报告不代判、不填 0。
3. **S-31 接线**：按 `迁移就绪清单.md` 接线（0.3.5 定版后）；接线时若发现契约缺口，回 S-40 改契约，不在游戏里改城市模块；本次已补 pickables=69、勿递归 raycast、visible=false 仍可命中 3 个坑。
4. **真机性能/内存**：建议 S-31 接线后由机主验（城市层单独 10 draw call，阴影 pass 另算；swiftshader FPS 不作真机依据）。
5. **本轮冻结时间线（分列）**：① 源码/HTML/PNG **取证轮 21:38:12**（`metrics.generatedAt`；shots mtime 21:35–21:38）；② C4 冻结声明 21:47（此后 shot.mjs / demo-main.ts / dist HTML / 30 张 PNG / sha 表未再改）；③ 性能表**文档勘误** 21:55:12（仅 (e-2) 贴图口径，图/HTML/shot 未动，`C4/性能表版本.txt` 留痕）；④ U1 定稿 22:00；⑤ UX 定稿 22:07:51（之后仅文档事实更正，评级未动）。Lead 侧证据脚本可随时复跑（`Lead/校验-装配示例.mjs`、`校验-资源生命周期.mjs`、`预算实测.mjs`、`核验C4交付.mjs`）。
6. **HUD 口径歧义（待机主裁量的 P2 改进，不改冻结图）**：22 号正式图 HUD「三角形 86,744」是**构建快照**（构建档=车低人低），不是高档实时值 89,336；「实例数 335」是实时值。HUD 标签未标来源，属文案待完善项（`C4/截图说明.md` §HUD 口径歧义 / `续接调度/截图HUD快照歧义.json`）；如需修标签重出图，须整轮新快照 + U1/UX 重绑，不得悄悄替换。
