# Phase 1：包边界（不换仓库）

父任务：`.trellis/tasks/08-25-road-compiler-extraction/`
技术设计：父任务 `design.md` §2（模块清单 / K1 拆分建议）

## Goal

在**当前仓库内**建立 `packages/road-compiler/`，移入编译器全部模块，
把对 `readAreaConfig` 的耦合换成窄输入契约，产物对 Phase 0 基线逐字节一致。

**本阶段不换仓库。** 目的是把"改坏了编译器"与"拆坏了仓库"分成两个可归因的步骤
（父任务 D4）。

## Requirements

### R1.1 目录与模块搬迁

在 `packages/road-compiler/` 内建立结构，移入父任务 `design.md` §2.1 列出的全部文件
（约 3400 行核心 + workbench）。

搬迁后 `scripts/lib/` 下不应再留下这些文件的副本 —— 并存会导致
"改了一份忘了另一份"的静默不一致。

### R1.2 窄输入契约

- 编译器入口只接受父任务 `design.md` §1.1 定义的 `RoadCompilerInput`
- 编译器内不得出现 `require("area-config")`、不得读 `config/areas/*.json`、
  不得从 areaId 推导任何路径
- 宿主 `scripts/lib/area-config.js` 新增 `toRoadCompilerInput(area)` 做映射
- 三个 CLI（`compile` / `check` / `workbench`）改为接受显式参数或 input JSON

### R1.3 K1：`traffic-signals.js` 拆分 🔴

**全案唯一需要细读再动的地方。** 按父任务 `design.md` §2.3：

- 随编译器走：OSM 信号节点提取 + 信号文档 schema
- 留宿主：`readTrafficSignalFeatures`（`build-osm2streets-qgis.js`）、
  `readTrafficSignals`（`build-area.js`）
- 待判定：`buildTrafficSignals`（`test-preview-assets.js`）—— 需读代码确认归属
- 拆完后宿主从编译器包 import schema（宿主→编译器是允许方向）

动手前必须先产出一份「函数 × 使用方」矩阵，确认无遗漏。

### R1.4 K3：参考文件路径约定

`config/areas/fengshu-er-road.json` 的
`junctionTemplates.clusters[].referenceFile` 是指向宿主仓库的绝对路径。

- 定义解析约定：相对 config 文件所在目录，或由宿主在 `toRoadCompilerInput()`
  中解析为绝对路径后传入
- 倾向后者：**编译器只接受已解析的绝对路径，不做路径推导**（符合 R1.2）
- config 内改为相对路径，宿主负责解析

### R1.5 K5：自带测试 fixture

- `test-native-road.js:167` 读 `inputs/osm/枫树二路.osm`
- 该文件（或裁剪版）复制进 `packages/road-compiler/test/fixtures/`
- 测试改为读包内 fixture，不再访问宿主 `inputs/`
- 目标：编译器包 `npm test` 不依赖宿主任何目录

### R1.6 宿主侧接线保持不变

- `build-area.js` 本阶段继续 in-process `require`（子进程改造留到 Phase 2）
- `npm run road:compile` / `road:check` / `road:workbench` 行为对用户不变
- `blender/` 完全不改

## Acceptance Criteria

- [ ] AC1.1 三区域 `road-parity --compare` 对 Phase 0 基线全绿
- [ ] AC1.2 `npm run test:native-road`、`npm run test:road-workbench` 通过
- [ ] AC1.3 `npm run build:area` 三区域完整跑通（含 blender / cesium 阶段）
- [ ] AC1.4 `grep -rn "area-config\|config/areas" packages/road-compiler/` 无命中
- [ ] AC1.5 `packages/road-compiler/` 内 `npm test` 不访问宿主 `inputs/` 或 `outputs/`
- [ ] AC1.6 `scripts/lib/` 下无搬迁文件的残留副本
- [ ] AC1.7 K1 的「函数 × 使用方」矩阵已产出并归档到 `research/`
- [ ] AC1.8 `compiled.json` 结构未变（父任务 AC7 / C1）

## 依赖与顺序

- **前置**：Phase 0 必须完成且基线可靠
- **阻塞**：Phase 2
- 与 Phase 3、4 无直接依赖，但它们都在 Phase 2 之后

## 风险

| 风险 | 缓解 |
|---|---|
| K1 拆分遗漏某个使用方 → 运行时才炸 | 先做矩阵，再动代码；`grep -rn` 全仓验证 |
| 搬迁过程中相对 require 路径改错 | 分小步 commit，每步跑 parity |
| `workbench/app.js` 的 OpenLayers import map 指向宿主 node_modules | 本阶段仍在同仓库，可暂不处理；记入 Phase 2（K4） |
| 一次性大搬迁难以归因 | 按模块分批：先纯函数（lane-geometry / gaode-reference），再 complex-junction，最后 native-road 与 CLI |

## Out of Scope

- 换仓库（Phase 2）
- layer manifest（Phase 3）
- IR / pass manager 重构（父任务 C1）
- 引入 TypeScript 或构建步骤（父任务 C2）