99 lines
4.3 KiB
Markdown
99 lines
4.3 KiB
Markdown
# 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
|
||
|
||
- [x] AC1.1 两个有效区域 `road-parity --compare` 对 Phase 0 基线全绿
|
||
- [x] AC1.2 `npm run test:native-road`、`npm run test:road-workbench` 通过
|
||
- [x] AC1.3 `npm run build:area` 枫树二路完整跑通（含 blender / cesium 阶段）
|
||
- [x] AC1.4 `grep -rn "area-config\|config/areas" packages/road-compiler/` 无命中
|
||
- [x] AC1.5 `packages/road-compiler/` 内 `npm test` 不访问宿主 `inputs/` 或 `outputs/`
|
||
- [x] AC1.6 `scripts/lib/` 下无搬迁文件的残留副本
|
||
- [x] AC1.7 K1 的「函数 × 使用方」矩阵已产出并归档到 `research/`
|
||
- [x] 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）
|