# Phase 1 执行计划

分批搬迁，每批后跑 parity。**不要一次性大搬。**

## Step 0 — 前置

```bash
# 基线必须先绿
for a in fengshu-er-road nantaizi-lake-innovation-valley; do
  node scripts/road-parity.js --config config/areas/$a.json \
    --compare .trellis/tasks/08-25-road-compiler-extraction/baseline/$a.json || echo "FAIL $a"
done
```

- [ ] 两个有效区域基线全绿（否则回 Phase 0）

## Step 1 — K1 矩阵（动代码之前）

- [ ] 读 `scripts/lib/traffic-signals.js` 全文，列出所有 export
- [ ] 对每个 export `grep -rn` 找使用方
- [ ] 产出 `research/traffic-signals-split-matrix.md`：函数 × 使用方 × 归属判定
- [ ] `buildTrafficSignals`（`test-preview-assets.js`）归属定档

**门槛**：矩阵完成，无"待定"项。

## Step 2 — 建包骨架

```
packages/road-compiler/
  package.json          # CommonJS，无构建步骤（父任务 C2）
  src/
  bin/
  test/fixtures/
  docs/
```

- [ ] `package.json` 名称、入口、`test` script
- [ ] 根 `package.json` 加 workspace 或 `file:` 依赖

## Step 3 — 分批搬迁（每批一个 commit + 一次 parity）

**批 1：纯函数，零风险**
- [ ] `lib/lane-geometry.js` → `src/geometry/lane-geometry.js`
- [ ] `lib/gaode-junction-reference.js` → `src/reference/gaode.js`
- [ ] 宿主侧改 require 指向包
- [ ] parity ✓

**批 2：几何模块**
- [ ] `lib/turn-lane-arrows.js`
- [ ] `lib/complex-junction.js`
- [ ] parity ✓

**批 3：信号（K1 执行）**
- [ ] 按 Step 1 矩阵拆 `lib/traffic-signals.js`
- [ ] `lib/native-traffic-signals.js` 与 schema 部分入包
- [ ] `lib/osm.js` 入包
- [ ] 宿主保留 legacy 读取器，从包 import schema
- [ ] parity ✓ + `npm run test:traffic-signals`（若存在）

**批 4：编译器核心**
- [ ] `lib/native-road.js` → `src/compile/native-road.js`
- [ ] parity ✓

**批 5：CLI + 窄契约（R1.2）**
- [ ] `compile-native-roads.js` → `bin/compile.js`，入参改 `RoadCompilerInput`
- [ ] `check-native-roads.js` → `bin/check.js`
- [ ] 宿主 `area-config.js` 加 `toRoadCompilerInput(area)`
- [ ] `build-area.js` 改为传 input 对象
- [ ] K3：`referenceFile` 改为宿主解析后传绝对路径，config 内改相对路径
- [ ] parity ✓

**批 6：workbench**
- [ ] `road-workbench.js` + `workbench/app.js` 入包
- [ ] OpenLayers 依赖暂沿用宿主 `node_modules`（同仓库内可行），记入 Phase 2 K4
- [ ] `npm run test:road-workbench` ✓

**批 7：测试 fixture（R1.5）**
- [ ] `inputs/osm/枫树二路.osm` 复制进 `test/fixtures/`
- [ ] `test-native-road.js` 改读包内 fixture
- [ ] 在包目录内独立跑 `npm test` ✓

## Step 4 — 清理与验证

- [ ] 删除 `scripts/lib/` 下所有搬迁文件的残留（AC1.6）
- [ ] `grep -rn "area-config\|config/areas" packages/road-compiler/` 必须为空（AC1.4）
- [ ] `grep -rn "\.\./\.\./scripts\|osm2streets-qgis-workflow" packages/road-compiler/` 检查反向依赖

## 验证命令汇总

```bash
# parity
for a in fengshu-er-road nantaizi-lake-innovation-valley; do
  node scripts/road-parity.js --config config/areas/$a.json \
    --compare .trellis/tasks/08-25-road-compiler-extraction/baseline/$a.json || echo "FAIL $a"
done

# 测试
npm run test:native-road
npm run test:road-workbench
(cd packages/road-compiler && npm test)

# 端到端（含 blender / cesium）
npm run build:area -- --config config/areas/fengshu-er-road.json

# 反向依赖为 0
grep -rn "area-config\|config/areas" packages/road-compiler/ && echo "VIOLATION"
```

## Review Gate

AC1.1–AC1.8 全绿。**parity 有任何一项不绿都不得进 Phase 2** —— 那意味着搬迁改变了行为，
而在同一仓库内查因比拆仓库后查因便宜得多。

## Rollback

每批一个 commit，可逐批 `git revert`。
过渡期内若需紧急回退，宿主 require 改回 `scripts/lib/` 旧路径即可
（前提：该批尚未执行 Step 4 清理）。