# S-22B 交接收敛说明（0.3.3 主题 B · 建筑目录 F-11 完整版）

- 任务：S-22B（实现 + 协调），工作树 `/vol1/ai/projects/wyszz-new/frontend-rebuild-hm033-biz`，基线 `frontend-rebuild-hm032`（0.3.2）。
- 版本号保持 **0.3.2**（未改 `package.json` / `src/platform/*`）。
- payload：`payload.tar.gz`（新增 4 / 修改 3 / 删除 0，见同目录 `改动清单.md`）。
- 一句话结论：F-11 六条需求全部落地（单/双列、四类图标、位置+特写、跳特写、城区行、互斥），**旧断言 0 删除 0 修改**，S-19/S-21 启动指纹**零改动**仍 `all OK`，7 组测试全绿。

---

## 一、改动文件（严格在任务书「文件所有权」内）

| 文件 | 动作 | 说明 |
| --- | --- | --- |
| `src/ui/bizdir.ts` | 新增（约 200 行） | 纯函数模块，零依赖 DOM：`describeSpot(x,z)`（8 方位 + 圈层 `max(\|q\|,\|r\|,\|q+r\|)` + 距心，只吃 `buildingCenter` 的坐标）、`bizColumnsFor(w,requested)`（`BIZ_COL_MIN_W=390` 窄屏强制单列）、`bizIconKind(i)`、`bizBadge(row)`（可开业/需 LvN/已开业/已满级/离线中/差金币）、`bizHitTest(layout,x,y)`（focus > row > district > cols > panel > null）、常量 `BIZ_ICON_COL_W=34`/`BIZ_ICON_SIZE=26` |
| `src/ui/hud-layout.ts` | 修改 | 列表版式：`columns/colToggle/focusBtns/iconRects/districtIcon/iconColW` 六个新字段、双列网格（同排等高、两列不重叠）、每行 `bRow{i}Name/Status/Badge/Spot/Tail`、头部 `bColsLabel`（双列/单列）与 `bCloseLabel`、城区行 `bDistrictIcon`；新增 `bizRowH/bizHeight/bizColumnsFor` 接线与 `listHeadH`（见 §三） |
| `src/ui/hud.ts` | 修改 | `HudRegion` 增 `bld-cols` / `bld-focus0..3` 并登记 `ACTION_REGIONS`；`BizListRowView` 增 `spot/badge/badgeTone/icon`，`BizData.columns?`；绘制：`drawBizIcon`（市政/住宅/商业/绿化/城区，**全部 canvas 原语，无新资源**）、状态徽标药丸、特写按钮；命中优先级 = 特写 > 列切换 > 城区 > 行 > 面板；新 getter `bizRowsNow/bizColumnsNow/widthNow` |
| `src/app/app.ts` | 修改 | 状态 `bizCols: 1\|2 = 1`；方法 `setBizCols/toggleBizCols/focusBizRow/buildingSpot/buildingMaxed`；`refreshBiz` 行数据补 `spot/badge/badgeTone/icon` 并透传 `columns`；`openBiz` 增「离线/结算模态」「一键购买确认框」两条互斥闸门；`onUiAction` 接 `bld-cols`/`bld-focus{i}`；调试 API 增 `bizColumns/setBizCols/toggleBizColsNow/bizSpot/bizRowInfo/bizFocusNow` |
| `test/t-bizdir.mjs` | 新增（373 行，S2 交付） | 浏览器 e2e 27 条：入口/单列/320 自动单列/双列/图标/位置/点行/特写/回全岛/城区/排序/互斥四条/五屏三态/15 图/pageerror/`fingerprintOk` |
| `tests/bizdir-layout.test.ts` | 新增（332 行，S1 交付） | Node 矩阵 81 组合 × 6111 断言：列数、图标列宽、两列不重叠、同排等高、行高/命中下限、文本框不越界、面板边界、命中五类、`describeSpot`/`bizBadge`/`bizColumnsFor` |
| `tools/test-bizdir-layout.mjs` | 新增（9 行，S1 交付） | esbuild 打包 → spawn node → 结果落 `evidence/bizdir-layout-matrix.json`，失败退出码透传 |

**未改**：`src/game/session.ts`（完全零改动，只读调用）、`src/render/*`（camera/palette/world/hex）、`package.json`、`tools/regress.mjs`、契约包、**`src/game/fingerprints-s19.ts` / `fingerprints-s21.ts`（关键决策，见 §三）**、全部既有只读测试（`test/t-s19.mjs`、`test/t-s21.mjs`、`test/t-ui.mjs`、`tests/s19-*.ts`、`tests/s21-*.ts`）。

---

## 二、旧断言 / 锚点变更：**0 删除、0 修改**

- 既有只读测试一行未动：`test/t-s19.mjs`（69/69）、`test/t-s21.mjs`（12/12）、`test/browser.test.mjs ui`（30/30）、`tests/s19-hud-layout.test.ts`（288 组合 / 67752 断言）、`tests/s21-hud-layout.test.ts`（30 组合 / 1122 断言）全部通过。
- 旧文本 id 全部保留（`bRow{i}Name/Status`、`bTitle`、`bHomeLabel`、`bCloseLabel`、`bDistrictName/Sub/Tail`…）；只**新增** id（`bRow{i}Badge/Spot`、`bColsLabel`、特写按钮），`bRow{i}Tail` 文案由 `›` 改为 `特写 ›`（无任何旧断言引用 Tail，已 grep 确认）。
- **行点击语义保持 0.3.2**：点行 = 打开建筑卡 + 镜头特写（`t-s19` S19-D03/G02、`t-s21` S21-D03 依赖此语义，且这些文件只读）。
  任务书 (d)「点行 = 飞镜头 + 关列表」落在**行内独立「特写」按钮**（44×40 单列 / 整宽×40 双列，`bld-focus{i}`）上：点它 = `camera.focusOn(x,z,3)` + 关闭列表 + **不 resetFocus**，返列表后镜头保持特写；「回全岛」（头部 `bld-home` 与 S-20 小按钮）仍可回。两条路径都复用同一个 `focusOn`，命中区不重叠（特写按钮不覆盖行中心，S1/S2 双向断言）。

---

## 三、关键决策：**不改指纹文件，恢复基线单列几何**

初版把列表头部抬高到 46px，导致 `fingerprintS19.bizpanel`（S-19 启动指纹，含列表面板/行/城区行矩形快照）MISMATCH ⇒ 内部包红条、`t-s19` S19-I01 失败、正式包会拒绝启动。

处置：把**单列**列表的头部几何收敛回 0.3.2 基线**逐像素一致**——`listHeadH(km) = max(km.head, 6 + 40 − km.pad)`，正常档正好 38；行起点 `panel.y + pad + head + 2`。于是：

- `fingerprintS19.bizpanel`、`fingerprintS21.bldcard` 等**全部字符串逐字不变**，`fingerprintOk = true`（`t-bizdir` 已固化 B15 断言防回退）；红条消失，15 张截图无红条。
- 390×844 单列列表实测 `12,360,366,300`、行 `22,408/457/506/555,346,46`、城区行 `22,603,346,46` —— 与基线完全一致（S2 实测比对）。
- 只有「双列」是新几何（不在指纹锚点内），因此无需碰任何指纹文件，也无需 `EXPECTED_*` 例外。

---

## 四、布局数值「旧 → 新」留痕（同分辨率同一坐标，单位 px）

基准：390×844，topH=84，bottomTop=771。

| 项 | 0.3.2 基线 | S-22B 单列 | S-22B 双列 |
| --- | --- | --- | --- |
| 面板 rect | `12,360,366,300` | **`12,360,366,300`（逐像素不变）** | `12,342,366,318` |
| 行 rect | `22,408+i*49,346,46` | 同基线 | `22\|199, 390\|497, 169, 104`（同排等高、两列 x=22/199 不重叠） |
| 名称/状态 x | `row.x+10` | **`row.x+34`**（新增 34px 固定图标列） | 同（第二列 x=233） |
| 行尾 | `bRow{i}Tail='›'` @16 靠右 | **「特写 ›」@11 位于 44×40 按钮 `320,411+i*49`** | 「特写 ›」@12 位于整宽 157×40 按钮 `28/205,450`（第二排 557） |
| 头部按钮 | 回全岛 76×40 @`244,366`；关闭 40×40 @`328,366` | 同基线 + **列切换 56×40 @`180,366`**（落在标题与回全岛之间空位，不压任何旧按钮） | 同（y=348） |
| 城区行 | `22,603,346,46` | 同基线 + 城区图标 34×26 | 同 |
| 行高 | 46 | 46 | **104**（=46+58，双列每行多 2 行文本 + 底部整宽按钮） |

其它档位（`bizHeight` 列表分支：`pad + listHeadH + 2 + gridRows*(rowH+lgap) + dgap + rowH + pad`）：

| 档位 | 基线高度/参数 | S-22B 高度/参数 |
| --- | --- | --- |
| 正常（390×844） | 300；pad8/head38/行46/行距3/城区距2 | **300（不变）**；同参数（`listHeadH=38`） |
| 紧凑（320×568+safeTop47 实测 topH=111） | 264；pad6/head30/行42/行距2 | **274（+10）**；pad6/`listHeadH=40`/行42/行距2（面板 `12,127,296,274`，顶边 127 ≥ topH+6=117、底边 401 ≤ 504） |
| 极矮（320×568+topH128/bottomTop476，S-19 矩阵档） | 226；pad4/head26/行36/行距2/城区距2 | **230（+4）**；pad3/`listHeadH=42`/行36/`lgap=0`/`dgap=0`（面板仍不越顶栏，S-19 矩阵 288 组合 0 违反） |
| 双列任意档 | — | `+58/行`、gridRows=2；放不下时 `layoutBizPanel` 自动降级单列（`columns` 生效值才进布局） |

图标：`BIZ_ICON_COL_W=34`（图标列宽，恒定）、`BIZ_ICON_SIZE=26`（本体）；`iconRects[i]={x: 行x, y: 单列垂直居中/双列 y+6, w:34, h:26}`，`districtIcon` 同口径。

---

## 五、需求逐条对照（任务书 a–f）

| 需求 | 实现 | 证据 |
| --- | --- | --- |
| a 单/双列切换；320 窄屏自动单列、≥390 可双列；双列不重叠/等高/图标列固定宽 | 头部 `bld-cols` 按钮（56×40，仅 w≥390 出现）；`bizColumnsFor` 窄屏强制单列；双列网格两列 x=22/199、同排同 y、行高恒 104；图标列恒 34 | `t-bizdir` B02/B03/B04；S1 矩阵 `columns`/`不重叠`/`同排等高`/`iconRects.w=34` 组 |
| b 四类图标（市政/住宅/商业/绿化，既有原语绘制）+ 名称 + 状态徽标 | `drawBizIcon` 纯 canvas 路径（金色山墙/蓝色屋顶/橙色雨棚/绿色树冠 + 城区网格），零新增资源；`bizBadge` 输出 可开业/需 LvN/已开业/已满级/离线中/差金币，按 tone 上色 | `t-bizdir` B05（四类图标区采样色数 5/4/7/5，非空白）、B02（Badge 文案齐全） |
| c 每行位置信息（不硬编码）+「跳特写」 | `describeSpot(world.buildingCenter(i))`：方位 8 扇区 + 圈层 + 距心；行内显示短文案（岛心/南 · 圈1/东南 · 圈1/西南 · 圈1），完整文案供调试 | `t-bizdir` B06（4 栋 spot 与 `buildingCenter` 现算值逐条一致、互不相同） |
| d 行→飞镜头(zoom 3)+关列表；返回列表镜头保持；回全岛可用 | 行内「特写」按钮 `bld-focus{i}` → `focusOn(x,z,3)` + 关列表 + 不 reset；再开列表镜头不重置；`bld-home`/S-20 小按钮回全岛 | `t-bizdir` B08a/b（distance 0.00、zoomTarget 3、mode=null、camHome visible）、B09a/b |
| e 城区行保留（D + 下一级费用）；排序「差得最少优先」 | 城区行沿用既有 `listSub`（`区 Lv 1 · 下一级 2,100 金币`）+ 新增城区图标；顺序沿用 `bizOrder`（未开业且差得最少优先） | `t-bizdir` B10（点城区行→district）、B11（`bizListOrder=[1,2,3,0]`） |
| f 与购地/报价卡/角色卡/报告/确认框互斥 | `openBiz` 闸门：报告忙碌、离线/结算模态、一键购买确认框全在场时不可开；列表与购地层不叠加（列表打开时 `buyAll=null`、提示行不命中） | `t-bizdir` B12a/b/c/d |

---

## 六、测试与证据（全部实跑，日志在 `tasks-out/S-22/biz/`）

| 命令 | 结果 | 日志 |
| --- | --- | --- |
| `npm run typecheck` | 静默通过（0 错误） | 终端 |
| `npm run test:s19-hud-layout` | 288 组合 / 67752 断言，0 违反 | 终端 |
| `npm run test:s21-hud-layout` | 30 组合 / 1122 断言，0 违反 | 终端 |
| `node tools/test-bizdir-layout.mjs`（新增，等价 `test:bizdir` 前半） | **81 组合 / 6111 断言，0 违反** | `evidence/bizdir-layout-matrix.json` |
| `node test/browser.test.mjs ui`（`t-ui.mjs` 的运行器；单跑 `node test/t-ui.mjs` 是模块无自执行） | 30/30 通过 | `log-browser-ui.txt`、`log-t-ui.txt` |
| `node test/t-s19.mjs` | **69/69 通过**（含 S19-I01 指纹 all OK） | `log-t-s19.txt` |
| `node test/t-s21.mjs` | **12/12 通过** | `log-t-s21.txt` |
| `node test/t-bizdir.mjs`（新增） | **27/27 通过**，全程 pageerror 0 | `log-t-bizdir.txt`、`bizdir-results.json` |
| 截图 5 屏 × 3 态 = 15 张 | 全部 >15KB（71.6–136.1KB），无红条 | `evidence/biz-{w}x{h}-{single,double,double-focus}.png` |

- 截图屏：320×568 / 360×640 / 390×844 / 414×896 / 430×932；320、360 的 `-double.png` 按契约命名，内容为**自动单列**（`allowed=false`、无列切换按钮）。
- 全程 `pageerror = 0`（每屏 0/0/0/0/0）。

---

## 七、给「应收 / 集成」的接入说明

1. **payload**：`payload.tar.gz`（同目录），直接解到 0.3.2 基线树即可；`改动清单.md` 已列 4 新增 / 3 修改 / 0 删除。**无删除文件**，无需迁移脚本。
2. **package.json（我无权改，请应收注册）**，新增一行：

   ```json
   "test:bizdir": "node tools/test-bizdir-layout.mjs && node test/t-bizdir.mjs"
   ```

3. **`tools/regress.mjs` 新增 2 步**（名字建议直接叫 `bizdir-layout` / `bizdir-e2e`，放在 `s21-*` 之后）：

   ```js
   {
     id: 'bizdir-layout', name: 'S-22B 建筑目录布局矩阵(单/双列/图标/位置/命中)',
     cmds: [() => npmCmd(['run', 'test:bizdir'])],   // 或 ['node', ['tools/test-bizdir-layout.mjs']] 只跑矩阵
     metric: (o) => { const m = /S-22B 建筑目录矩阵：(\d+) 组合 \/ (\d+) 断言全部通过/.exec(o); return m ? `${m[1]} 组合 / ${m[2]} 断言` : ''; }
   },
   {
     id: 'bizdir-e2e', name: 'S-22B 建筑目录端到端(图标/位置/跳特写/互斥)',
     cmds: [() => ['node', ['test/t-bizdir.mjs']]],
     metric: (o) => fractionOf(o, /S-22B 建筑目录 e2e (\d+)\/(\d+) 通过/)
   }
   ```

   若要合并成一步，`npm run test:bizdir` 串联输出里的最后一行匹配 `(\d+)\/(\d+) 通过`（e2e 汇总行），metric 用 `fractionOf(o, /建筑目录 e2e (\d+)\/(\d+) 通过/)`。
4. **回归脚本前置**：`dist/web-internal` 需先 `node tools/build-web.mjs --internal`（`test/lib.mjs serve()` 直接服务该目录；`regress` 若已含构建步骤则无需重复）。
5. **截图证据**：15 张已随任务产物在 `evidence/`，如需并入仓库 `evidence/` 目录请按既有命名约定复制。

---

## 八、已知取舍 / 风险（如实登记）

1. **行点击语义**：任务书 (d) 原文「点行 = 飞镜头 + 关列表」，但 `t-s19`/`t-s21`（只读）要求点行打开建筑卡。为满足「旧断言只加不减」，点行保持旧语义（开卡片 + 特写），(d) 的「+关列表」落在行内「特写」按钮上；两条路径同一 `focusOn(x,z,3)`，且按钮不覆盖行中心，二者可同时被接受。**若验收方坚持「点行即关列表」**，需允许修改 `test/t-s19.mjs`/`test/t-s21.mjs`（本任务禁止），改动量约 3 行断言 + 1 个动作分支。
2. **列数不落盘**：`bizCols` 是纯 UI 状态，重启/重载默认单列（与「不写存档」约束一致）；宽 <390 时无论请求值都强制单列。
3. **双列窄列宽省略号**：390 双列列宽 169，`市政厅 · Lv1 F0 A0 +10.00/分` 会省略为 `市政厅 · Lv1 F0 A0 +…`（布局矩阵要求不越界，故省略号是设计内行为）；单列到 320 宽仍是完整文案的 46 行档。
4. **极矮档压缩**：320×568 + 安全区 47 且可用区被压到 231 时（S-19 矩阵档），列表用 pad3/行距 0/头部 42 保证不越顶栏；面板 230 高、行高 36（命中 36+2=38 ≥36 满足矩阵下限，正常档仍是 46 ≥40）。
5. 真机（iOS/Android WebView、微信小游戏）未验；本次范围仅 Node + Chromium（375/390/430 等 5 屏 + caps 注入）。

---

## 九、回滚

删除 `src/ui/bizdir.ts`、`test/t-bizdir.mjs`、`tests/bizdir-layout.test.ts`、`tools/test-bizdir-layout.mjs`，并用基线覆盖 `src/app/app.ts`、`src/ui/hud-layout.ts`、`src/ui/hud.ts` 即可（无删除文件、无 schema 变更、无指纹改动，回滚后 `fingerprintOk` 仍为 true）。
