refactor: consume external road compiler
This commit is contained in:
@@ -1,74 +1,55 @@
|
||||
# Phase 2 执行计划
|
||||
|
||||
## Step 1 — 前置
|
||||
执行前提：用户已在最新 P2 规划摘要后明确批准。发布目标已定为私有 `https://git.app.que01.top/que01/road-compiler.git`，首发 tag 为 `v0.1.0`。
|
||||
|
||||
- [ ] Phase 1 的 AC1.1–AC1.8 全绿
|
||||
- [ ] 定档 §「待决策」四项（仓库名 / 托管 / 分发 / 过渡期策略）
|
||||
## 1. 导出并核验历史
|
||||
|
||||
## Step 2 — 拆出仓库（保历史）
|
||||
- [ ] 创建临时 export 分支或临时 clone，使用 `git subtree split --prefix=packages/road-compiler` 或 `git filter-repo --path packages/road-compiler/ --path-rename packages/road-compiler/:` 导出。
|
||||
- [ ] 在导出仓库验证 `git log --follow src/compile/native-road.js` 包含 2026-08-13 以来的 native compiler 历史。
|
||||
- [ ] 在私有 `https://git.app.que01.top/que01/road-compiler.git` 创建并推送独立仓库；创建带注释的 `v0.1.0` tag。
|
||||
|
||||
## 2. 使编译器仓库自持
|
||||
|
||||
- [ ] 将 CLI 作为 package `bin` 入口，接受由宿主写出的 `RoadCompilerInput` JSON，并继续输出唯一的 `NATIVE_ROAD_COMPILE_DONE` JSON 标记。
|
||||
- [ ] 补全 `package.json`、锁文件和 `ol` 依赖；workbench vendor 文件从自身安装目录提供。
|
||||
- [ ] 迁入 `docs/native-road-package-v1.md`、两个 baseline 和它们的测试驱动，新增独立 README。
|
||||
- [ ] 在不含宿主文件的临时 clone 内执行依赖安装、单元测试、两区域 parity 与 workbench 启动测试。
|
||||
- [ ] grep 验证没有 `area-config`、`config/areas`、宿主项目名或宿主相对路径引用。
|
||||
|
||||
## 3. 宿主改为外部 CLI 消费
|
||||
|
||||
- [ ] 将 compiler 以精确 git tag `v0.1.0` 安装到宿主并记录 lockfile；禁止范围版本、`latest`、`*` 和裸分支。
|
||||
- [ ] 将 `toRoadCompilerInput()` 序列化到每个区域的 pipeline staging 目录，传给 compiler CLI。
|
||||
- [ ] 在 `build-area.js` 的 blender 前置阶段调用 CLI。沿用管线的 `spawnSync` / `runCommand` 失败语义（启动错误、exit status、signal）和直通日志；缓冲或 tee stdout 后，解析恰好一个完成标记并验证其 `areaId`、`output` 与当前区域匹配。
|
||||
- [ ] 将 host workbench 的 fresh compile 回调切换到同一 CLI，不改变 fresh-process 行为。
|
||||
- [ ] 把所有 host 对 `packages/road-compiler/**` 的直接 import 替换成已安装包的公开 API 或 CLI；两个区域 parity 均通过后删除 in-host 副本。
|
||||
- [ ] 将宿主 pipeline spec 改为指向编译器仓库所拥有的契约文档。
|
||||
|
||||
## 4. 验证与发布门
|
||||
|
||||
新仓库（干净 clone）：
|
||||
|
||||
```bash
|
||||
# 方案 A：subtree split
|
||||
git subtree split --prefix=packages/road-compiler -b road-compiler-export
|
||||
# 在新目录初始化并拉入该分支
|
||||
|
||||
# 方案 B：filter-repo（更彻底，推荐）
|
||||
git clone --no-local . /tmp/road-compiler-split
|
||||
cd /tmp/road-compiler-split
|
||||
git filter-repo --path packages/road-compiler/ --path-rename packages/road-compiler/:
|
||||
npm ci
|
||||
npm test
|
||||
npm run test:road-parity
|
||||
npm run road:workbench -- --config test/fixtures/fengshu-er-road.input.json --no-compile
|
||||
```
|
||||
|
||||
⚠️ 注意：Phase 1 的搬迁若用了 `git mv`，历史可 `--follow` 追溯；
|
||||
若用了删除+新建，`filter-repo` 只能追到 Phase 1。
|
||||
**Phase 1 搬迁时必须用 `git mv`** —— 这条已在 Phase 1 implement Step 3 隐含，
|
||||
此处显式记录依赖。
|
||||
|
||||
- [ ] 拆出后验证：`git log --follow src/compile/native-road.js | tail -20`
|
||||
能看到 08-13 native-road-compiler 的提交
|
||||
|
||||
## Step 3 — 新仓库自持化
|
||||
|
||||
- [ ] `package.json` 补全依赖（含 K4 的 OpenLayers）
|
||||
- [ ] `npm install && npm test` 在新仓库独立通过
|
||||
- [ ] 基线 JSON 迁入 `test/baseline/`
|
||||
- [ ] 契约文档迁入 `docs/`
|
||||
- [ ] README：契约摘要 + 与宿主项目关系说明
|
||||
|
||||
## Step 4 — 宿主改造
|
||||
|
||||
- [ ] `package.json` 依赖指向新仓库（开发期 `file:`）
|
||||
- [ ] `build-area.js` 改子进程调用 + 解析 `NATIVE_ROAD_COMPILE_DONE`
|
||||
- [ ] `area-config.js` 的 `toRoadCompilerInput()` 输出改为 CLI 参数或 input JSON 文件
|
||||
- [ ] 删除 `packages/road-compiler/`（或按过渡期决策保留）
|
||||
- [ ] `.trellis/spec/pipeline/` 加契约指针
|
||||
|
||||
## Step 5 — 验证
|
||||
宿主两个有效区域的逐字节 parity：
|
||||
|
||||
```bash
|
||||
# 宿主端到端
|
||||
npm run build:area -- --config config/areas/fengshu-er-road.json
|
||||
|
||||
# 三区域 parity
|
||||
for a in fengshu-er-road hanyang-block 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
|
||||
|
||||
# 反向依赖为 0（在新仓库内跑）
|
||||
grep -rn "osm2streets-qgis-workflow\|area-config" . --exclude-dir=node_modules --exclude-dir=.git \
|
||||
&& echo "VIOLATION"
|
||||
|
||||
# 锁版本检查
|
||||
node -e 'const d=require("./package.json").dependencies;console.log(d)' | grep -i road
|
||||
node scripts/road-parity.js --config config/areas/fengshu-er-road.json \
|
||||
--compare .trellis/tasks/08-25-road-compiler-extraction/baseline/fengshu-er-road.json
|
||||
node scripts/road-parity.js --config config/areas/nantaizi-lake-innovation-valley.json \
|
||||
--compare .trellis/tasks/08-25-road-compiler-extraction/baseline/nantaizi-lake-innovation-valley.json
|
||||
```
|
||||
|
||||
- [ ] 在一台未 clone 宿主的环境（或 `/tmp` 全新 clone）验证 AC2.2
|
||||
|
||||
## Review Gate
|
||||
|
||||
AC2.1–AC2.7 全绿。特别是 AC2.2（脱离宿主可自测）—— 这是"独立可维护"的实质。
|
||||
- [ ] 为 CLI 标记成功、缺失、重复、非法 JSON、areaId 不匹配和 output 不匹配补测试。
|
||||
- [ ] 跑 package 单测、宿主 native-road / workbench / traffic signals / turn-lane-arrows 测试，以及两个 parity 检查。
|
||||
- [ ] 使用 `trellis-check` 做最终跨层检查；Blender 完整构建需以提权方式运行，原因是 macOS Metal 初始化不能在沙箱内启动。
|
||||
|
||||
## Rollback
|
||||
|
||||
- 宿主依赖改回 `file:packages/road-compiler`（若过渡期保留了该目录）
|
||||
- 或 `git revert` 宿主侧改造 commit；新仓库留着不影响宿主
|
||||
- 外部仓库和已发布 tag 保留不动；在宿主 revert 消费改造即可回到 P1 边界。
|
||||
- 若按决定临时保留 in-host 副本，可将依赖回指该副本以恢复；该退路不取代 host parity 验证。
|
||||
|
||||
Reference in New Issue
Block a user