Files
osmWorkflow/.trellis/tasks/archive/2026-08/08-25-rc-p1-package-boundary/implement.md
T

3.9 KiB
Raw Blame History

Phase 1 执行计划

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

Step 0 — 前置

# 基线必须先绿
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/ 检查反向依赖

验证命令汇总

# 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 清理)。