# S-29 交付模块清单（给 0.4.1 接入用）

> 生成：2026-10-23（北京时间）｜工作树：`frontend-rebuild-hm041-city2`
> 读取顺序：本文件 → `说明.md`（内容与规则）→ `微信复刻审计.md`（预算与接入方案）。
> 所有路径相对工作树 `src/`；接入 0.4.1 时**整目录拷贝**即可，不依赖本工作树的任何临时文件。

## 1. 文件 → 导出 → 依赖 → 预算

| # | 文件 | 导出 | 依赖（同包） | 单单元预算（三角 / 网格 / 材质） | 建议接入位置 |
|---|---|---|---|---|---|
| 0 | `render/city/content.ts` | `BuildingClass` `ContentUnit` `BuildUnitOpts` `BuildUnit` `TierSpec` `CLASS_HEIGHT` `CLASS_NAME` `TIER_NAME` `footprintFor` `heightRange` `MAX_UNIT_W` `BLOCK_CELL` `UNIT_FLOOR_H` `paletteFor` `shapeFor` `hash2` `pickVariant` `unitRng` `facadeWindows` `makeUnit` `auditUnit` `addStats` `CONTENT_BUDGET` | three, `../geom`, `./materials`, `./layout`, `./contract` | —（契约/工具层） | 与内容线同目录，**先拷** |
| 1 | `render/city/tier-residential.ts` | `buildResidential` `RESIDENTIAL_TIERS` | content, geom | 348~1,388 / 2 / 2 | 城市扩展：住宅地块 |
| 2 | `render/city/tier-commercial.ts` | `buildCommercial` `COMMERCIAL_TIERS` `COMMERCIAL_VARIANT_LABEL`（+ 立面工具库，`commercial.ts` 复用） | content, geom | 420~1,728 / 2 / 2 | 城市扩展：商业地块 |
| 3 | `render/city/commercial.ts` | `buildCommercialStreet` `buildCommercialDistrict` `COMMERCIAL_DISTRICT={cells:[3,3]}` | tier-commercial, content | 步行街 1,924~2,560 / 2 / 2；商业区 ≤2,920 / 2 / 2 | 城市扩展：步行街 / 3×3 商业区（**不进单地块循环**） |
| 4 | `render/city/hall.ts` | `buildHall` `HALL_TIERS` | content, geom | 900~1,920 / 2 / 2 | 城市中心：市政厅固定 1 座 |
| 5 | `render/city/park.ts` | `buildPark` `PARK_TIERS` `PARK_TREE_SPEC` `PARK_HEIGHT` | content, geom | 528~2,580 / 1~2 / 1~2 | 城市扩展：绿地/公园地块（行道树实例化用 `PARK_TREE_SPEC`） |
| 6 | `render/city/landmark.ts` | `buildLandmark` `LANDMARK_TIERS` | content, geom | 548~1,188 / 2 / 2 | 城市地标位（中心 + 四角） |
| 7 | `render/city/industry.ts` | `buildIndustry` `INDUSTRY_TIERS` | content, geom | 408~932 / 2 / 2 | 滨海/外圈：工业码头 |
| 8 | `render/city/blocks.ts` | `planCity` `planStats` `blockAt` `fitToIsland` `BLOCK_PRESETS` `BLOCK_PITCH` `ROAD_W` `ROAD_MAIN_W` `ZONE_*` `CONTENT_CLASSES` `unitGridPitch` `buildUnitFor` `buildCityContent` `buildCityContent(plan,style)` | 全部内容线 + content + geom + materials + layout | 全城 85 块：几何 73,156（A 63,240 / C 72,076）/ 6 网格 / 3 材质；浏览器含阴影 132,842 / 12 call；key 模式 100,610 / 13 call | **街区布局层**：游戏里按城市等级选 plan 规模，再 `buildCityContent` |
| 9 | `city-demo/content-main.ts` + `city-demo/content.template.html` | 预览页入口（`window.__content` API） | 全部内容线 + blocks + island 无关 | 单文件 620 KiB | 只作预览/验收，不进游戏包 |
| 10 | `tools/build-city-content.mjs` | 单文件打包（esbuild → 内联，外链扫描） | esbuild | — | 构建脚本 |
| 11 | `tools/city-content-shot.mjs` | 99 张截图 + metrics.json | puppeteer-core + chromium | — | 取证脚本 |
| 12 | `test/city-content.test.mjs` | 契约/六线/布局/预算/纪律/预览页/截图断言 | node:test + esbuild | — | 回归测试 |

## 2. 冻结契约的扩展（只增，不破坏 S-26）

`render/city/contract.ts` 只加了：

```ts
export interface CityContentStats { units; triangles; meshes; materials; instanced?; byClass? }
// CityStats 里新增可选字段：
readonly content?: CityContentStats;
```
S-26 的 `CityApi` / `TowerBuild` / `PropsBuild` / `TrafficBuild` **一个字都没改**，老调用（`buildTowers(scene,tier)` 等）继续可用。

## 3. 0.4.1 接入建议（三步）

1. **拷文件**：`src/render/city/` 下 12 个新文件 + 新增 `contract.ts` 的两个可选字段（或整份覆盖 contract.ts，向后兼容）。
2. **接城市等级**：游戏里「城区/地块」有等级，推荐 `L1→T0 … L5+→T4`；`planCity({cols,rows})` 按城市规模选 `BLOCK_PRESETS`（小城 33 / 中城 49 / 满城 85），地块 `tier` 由分区 + 建筑等级共同决定，升级时**只重建该地块**（单元级 group 可单独 dispose，不重跑整城）。
3. **渲染策略**：`buildCityContent(plan, style, { shadows })`；满城建议 `shadowMode:'key'`（若 0.4.1 已加）或全局关闭内容库投影，把阴影留给岛/车流；切风格复用同一 plan（只换 palette/造型），切换成本 = 一次重建（当前 0.1~0.6 s）。

## 4. 注意事项（接入时容易踩）

- **单地块 vs 组合体**：`buildCommercialDistrict` 是 3×3 组合体（9.6×9.6），不要塞进 blocks 的单地块循环；`buildCommercialStreet` 足迹 2.92 属「地块级」，按 `footprintFor()` 严格校验需豁免。
- **高度契约**：各线档位总高必须落在 `CLASS_HEIGHT[cls][tier] ±12%`；改动造型时跑 `/tmp/s29/verify.mjs` 或 `node --test test/city-content.test.mjs`。
- **空 glow**：`makeUnit` 对「glow 三角形为 0」的单元不再 build（避免空 MeshBuilder 抛错）；新模块没有自发光就别传 glow builder。
- **确定性**：内容库禁用 `Math.random` / `Date.now`（静态扫描会红），随机一律 `hash2/pickVariant/unitRng`。
- **无贴图**：不要新增 `Texture` / `map`；发光一律走共享 `mats.glow`（emissive 顶点色，`materials.ts` 里的 onBeforeCompile）。
- **公园档高**：`park.ts` 在 `CLASS_HEIGHT.park` 容差内取 2.02/2.27/2.55（相邻比 ≥1.12），如要严格用曲线需同步改测试判据。
- **商业区朝向**：步行街沿 z、商场在 +x 格朝 -x、广告牌在 +z 格；换朝向整体旋转 group 即可。

## 5. 可复现命令

```bash
export PATH=/mnt/ssd/apps/nodejs_v24/bin:$PATH
cd /vol1/ai/projects/wyszz-new/frontend-rebuild-hm041-city2
npx tsc --noEmit -p tsconfig.json          # 0 错
node tools/build-city-content.mjs           # 单文件预览页（620 KiB）
node tools/city-content-shot.mjs --url file:///vol1/ai/projects/wyszz-new/frontend-rebuild-hm/tasks-out/S-29/demo/city-content.html --out /vol1/ai/projects/wyszz-new/frontend-rebuild-hm/tasks-out/S-29/evidence --w 1280 --h 800
node --test test/city-content.test.mjs      # 全绿
```
