# Phase 3 执行计划

## Step 1 — 枚举现有分流逻辑（定 schema 之前）

- [x] 读 `blender/generate_scene.py:796-834` 全部道路分支
- [x] 列出每个 `source` 的处理方式：直接渲染 / 按属性分流 / 跳过
- [x] 已知分流：
      - `center_lines`：`color != "white"` → `center_lines` 材质；
        `color == "white"` → `native_center_line_white`
      - `lane_separators`：`color != "yellow"` → `lane_separators`；
        `color == "yellow"` → `native_lane_separator_yellow`
- [x] 确认 `lane_centerlines` / `connectors` 确实未被消费（→ `role: "semantic"`）
- [x] 产出 `research/native-layer-consumption-matrix.md`

**门槛**：manifest schema 能表达矩阵里的每一行，无"特例硬编码"残留。

## Step 2 — 定 manifest schema 并落契约

- [x] 按父任务 `design.md` §3.2 定稿 schema
- [x] 写入编译器仓库契约文档，版本标为 `native-road-package/v1.1`
- [x] 记录：v1.1 起 `manifest.json` 为必需输出

## Step 3 — 编译器侧：生成 manifest

- [x] 编译器内建立图层注册表（单一事实源），`compileGeometry` 的输出键与之对应
- [x] 写 `manifest.json` 到 outDir
- [x] 编译器自校验：manifest 声明的每个 `source` 都必须有对应 geojson 文件，
      反之亦然（缺一即报错，不静默）
- [x] parity：此步只**新增** manifest.json，其余文件应逐字节不变；hanyang-block 不参与

```bash
# 只应多出 manifest.json
node scripts/road-parity.js --config config/areas/fengshu-er-road.json \
  --compare .../baseline/fengshu-er-road.json
```

## Step 4 — Blender 侧：抽模块 + 读 manifest

- [x] 新建 `blender/osmassets/native_roads.py`
- [x] 把 `generate_scene.py:796-834` 的道路分支迁入
- [x] 改为读 manifest 遍历；`role == "semantic"` 跳过
- [x] `splitBy` 通用化实现，替掉两处硬编码 lambda
- [x] **加断言**：manifest 里的 `materialLayer` 若不在 `catalog.MATERIALS` /
      `ROAD_LAYERS` 中，直接 raise，不静默跳过（风险表第二条）
- [x] 删除 `catalog.NATIVE_ROAD_LAYERS`
- [x] `generate_scene.py` 只保留一行调用

## Step 5 — 验证

```bash
# .blend 结构摘要对基线
npm run build:area -- --config config/areas/fengshu-er-road.json
# 走 artifact-parity-guide 的结构摘要比对

# 两个有效区域跑通（hanyang-block 为废案，不参与）
for a in fengshu-er-road nantaizi-lake-innovation-valley; do
  npm run build:area -- --config config/areas/$a.json || echo "FAIL $a"
done

# 建筑/植被/水体未被改动
git diff --stat -- blender/osmassets/ | grep -vE "native_roads|catalog"
```

- [x] 渲染预览图人工对照（结构摘要粒度不足的兜底）

## Step 6 — AC3.4 实测（可扩展性证明）

这一步是整个 Phase 3 的价值证明，不可跳过。

- [x] 编译器加一个 throwaway 图层 `debug_probe.geojson`（复用 road-surface 几何仅验证 wiring）
      + manifest 声明 `role: "marking"`，复用现有材质槽
- [x] **不改宿主任何代码**，跑 blender 阶段
- [x] 确认 Blender 场景中出现该图层几何
- [x] 截图/记录证据到任务 `research/`
- [x] 回滚 throwaway 图层

## Review Gate

AC3.1–AC3.7 全绿，特别是 AC3.4 有实测证据。

## Rollback

- 恢复 `catalog.NATIVE_ROAD_LAYERS`，`generate_scene.py` 恢复内联分支
- `manifest.json` 可保留输出（无消费方时无害）
- 编译器侧图层注册表保留（它本身是改进）