Files

4.3 KiB
Raw Permalink Blame History

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)