refactor: consume external road compiler
This commit is contained in:
@@ -1,80 +1,62 @@
|
||||
# Phase 2：拆仓库
|
||||
|
||||
父任务：`.trellis/tasks/08-25-road-compiler-extraction/`
|
||||
技术设计：父任务 `design.md` §1.3（消费方式）、§2（模块清单）
|
||||
|
||||
## Goal
|
||||
|
||||
把 `packages/road-compiler/` 拆成保留 git 历史的独立仓库，
|
||||
宿主改为锁版本依赖 + 子进程调用消费。
|
||||
把当前 `packages/road-compiler/` 拆为保留 git 历史、可脱离宿主独立测试和运行的仓库；宿主改为消费一个锁定版本的编译器 CLI。这样道路编译器可以独立演进，宿主依然通过版本化文件契约稳定构建场景。
|
||||
|
||||
## Confirmed Facts
|
||||
|
||||
- P1 已完成：编译器实现和 workbench 的所有权在 `packages/road-compiler/`；宿主负责将区域配置映射为 `RoadCompilerInput`。
|
||||
- `git log --follow packages/road-compiler/src/compile/native-road.js` 已能追溯到 2026-08-13 的 native-road compiler 历史。
|
||||
- 契约为 `native-road-package/v1`，完成标记为 `NATIVE_ROAD_COMPILE_DONE <json>`；`comparisonDir` 是可选输入，继续保留 `comparison.json`。
|
||||
- 当前宿主远端为内部 Git 服务 `https://git.app.que01.top/que01/osmWorkflow.git`；P2 独立编译器仓库定为私有 `https://git.app.que01.top/que01/road-compiler.git`。
|
||||
- 可维护范围只有 `fengshu-er-road` 和 `nantaizi-lake-innovation-valley`。`hanyang-block` 是废案，不参与基线、测试、验收或迁移语料。
|
||||
|
||||
## Requirements
|
||||
|
||||
### R2.1 保留 git 历史 🔴
|
||||
### R2.1 保留 Git 历史
|
||||
|
||||
- 用 `git subtree split` 或 `git filter-repo` 拆出，**不得**用 `cp` + `git init`
|
||||
- 理由（父任务 R3.2）：1695 行几何逻辑的 blame 是踩坑记录，
|
||||
丢了以后没人敢改 `compileGeometry` 里任何一行
|
||||
- 验证：新仓库内 `git log --follow src/compile/native-road.js` 能看到
|
||||
08-13 native-road-compiler 以来的完整历史
|
||||
- 用 `git subtree split` 或 `git filter-repo` 导出，不得以复制目录再 `git init` 替代。
|
||||
- 新仓库中 `git log --follow src/compile/native-road.js` 必须能追溯到 P1 之前的 native-road compiler 提交。
|
||||
|
||||
### R2.2 子进程为主契约
|
||||
### R2.2 新仓库可独立运行
|
||||
|
||||
- 宿主 `build-area.js` 改为 `execFileSync` 调编译器 CLI，
|
||||
解析 `NATIVE_ROAD_COMPILE_DONE` stdout 标记（父任务 design §1.3）
|
||||
- in-process `require` 可保留为可选优化路径，但不得是唯一路径
|
||||
- 与既有 QGIS / GDAL / Blender 调用方式一致
|
||||
（见 `.trellis/spec/pipeline/external-tools.md`）
|
||||
- 新仓库拥有 compiler、CLI、check、workbench、其测试 fixture、两个 parity baseline、契约文档和 README。
|
||||
- 新仓库 own `ol` 及其 workbench 所需的运行依赖；workbench 不得从宿主 `node_modules` 提供浏览器资源。
|
||||
- 新仓库不得引用宿主的 `area-config`、`config/areas`、`scripts/` 或本仓库绝对路径。
|
||||
|
||||
### R2.3 锁版本依赖
|
||||
### R2.3 宿主的消费边界
|
||||
|
||||
- 开发期：`file:` 或 workspace 依赖
|
||||
- 稳定后：git tag / 私有 npm，宿主 `package.json` **锁具体版本，不用 `latest`**
|
||||
- 契约版本 `native-road-package/v1` 与包版本分开演进：
|
||||
包可以发 patch，契约版本只在破坏性变更时升
|
||||
- `scripts/lib/area-config.js` 继续是唯一的区域配置归一化与 `RoadCompilerInput` 映射位置。
|
||||
- `scripts/build-area.js` 用已安装编译器的 CLI 子进程编译，继承 stdout/stderr，检查启动错误、退出状态和 signal，并解析且校验唯一的 `NATIVE_ROAD_COMPILE_DONE` 标记。
|
||||
- 宿主只依赖 CLI、写入的文件和版本化输入 JSON；不再以相对路径 import 编译器内部模块。保留的宿主 signal 文件 I/O 适配层改为只调用公开包 API。
|
||||
- `road-workbench` 保持每次编译均启动新进程的语义，但改为调用已安装 CLI。
|
||||
|
||||
### R2.4 K4：workbench 依赖自持
|
||||
### R2.4 版本与迁移
|
||||
|
||||
- `road-workbench` 的 OpenLayers 从新仓库自己的 `node_modules` 提供
|
||||
- import map 路径相应调整
|
||||
|
||||
### R2.5 基线迁移
|
||||
|
||||
- Phase 0 的三区域基线 JSON 搬进新仓库当测试语料（父任务 R4 第三条）
|
||||
- 新仓库 CI/test 能独立跑 parity，无需宿主在场
|
||||
- **同时**宿主保留一份，用于验证升级编译器版本后产物未变
|
||||
|
||||
### R2.6 契约文档迁移
|
||||
|
||||
- `docs/native-road-package-v1.md` 搬进新仓库
|
||||
- 宿主 `.trellis/spec/pipeline/` 留指针，说明契约由编译器仓库拥有
|
||||
- 宿主依赖必须锁定一个具体编译器版本，禁止 `latest` 或 `*`；包版本与 `native-road-package/v1` 的契约版本独立演进。
|
||||
- 初始分发使用带注释的 git tag `v0.1.0`；宿主锁定该 tag。完整 parity 验证后移除 `packages/road-compiler/`，不保留 in-host 副本作为正常消费路径。
|
||||
- 宿主保留两份 baseline，用来验证今后升级编译器版本后没有产物漂移。
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] AC2.1 新仓库 `git log --follow` 能追到搬迁前的历史
|
||||
- [ ] AC2.2 新仓库 `npm test` 在**未 clone 宿主**的机器上通过
|
||||
- [ ] AC2.3 宿主从锁版本依赖构建，三区域 parity 对基线全绿
|
||||
- [ ] AC2.4 `build-area.js` 走子进程路径，`NATIVE_ROAD_COMPILE_DONE` 被正确解析
|
||||
- [ ] AC2.5 宿主 `package.json` 依赖为具体版本，非 `latest` / 非 `*`
|
||||
- [ ] AC2.6 编译器仓库对宿主反向依赖数为 0（父任务 AC8，grep 验证）
|
||||
- [ ] AC2.7 `npm run road:workbench` 在新仓库内独立可跑
|
||||
|
||||
## 依赖与顺序
|
||||
|
||||
- **前置**：Phase 1 完成且 AC1.1–AC1.8 全绿
|
||||
- **阻塞**：Phase 3、Phase 4
|
||||
|
||||
## 待决策（进入本阶段时定）
|
||||
|
||||
| 项 | 选项 |
|
||||
|---|---|
|
||||
| 仓库名 | `road-compiler` / `native-road-compiler` / `osm-road-compiler` |
|
||||
| 托管 | GitHub 私有 / 公开 / 内部 git |
|
||||
| 分发 | git tag 依赖 / 私有 npm registry |
|
||||
| 宿主过渡期 | 是否保留 `packages/road-compiler/` 一段时间做双跑对照 |
|
||||
- [ ] AC2.1 独立仓库的 `git log --follow src/compile/native-road.js` 可见 P1 前的 compiler 历史。
|
||||
- [ ] AC2.2 在未 clone 宿主的干净目录中，新仓库 `npm ci`（或等价锁文件安装）和 `npm test` 均通过。
|
||||
- [ ] AC2.3 新仓库的两区域 parity（`fengshu-er-road`、`nantaizi-lake-innovation-valley`）均与迁入 baseline 完全一致。
|
||||
- [ ] AC2.4 宿主用锁版本依赖运行 CLI；`build-area.js` 成功解析一个有效的 `NATIVE_ROAD_COMPILE_DONE` 标记，缺失、重复或非法标记会失败。
|
||||
- [ ] AC2.5 宿主的两个区域 parity 均对保留 baseline 全绿。
|
||||
- [ ] AC2.6 宿主 `package.json` 的 compiler 依赖是具体、可复现版本，不是 `latest`、`*` 或裸分支。
|
||||
- [ ] AC2.7 编译器仓库对宿主反向依赖为 0，且其 workbench 可独立启动。
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- layer manifest（Phase 3）
|
||||
- drawtonomy 扩展（Phase 4）
|
||||
- 任何编译器内部逻辑改动 —— 本阶段代码内容不变，只换位置与消费方式
|
||||
- 编译器几何、规则或输出内容改动。
|
||||
- 图层 manifest 和道路/建筑渲染分离（Phase 3）。
|
||||
- drawtonomy 扩展（Phase 4）。
|
||||
- `hanyang-block` 修复、迁移或作为验收样本。
|
||||
|
||||
## Release Decision
|
||||
|
||||
独立仓库为私有 `https://git.app.que01.top/que01/road-compiler.git`。首发以带注释 tag `v0.1.0` 发布，宿主依赖精确锁定该 tag；两个区域 parity 均通过后删除 `packages/road-compiler/`。该决定授权 P2 在该内部远端创建和推送仓库，但不授权发布到 npm 或其他托管平台。
|
||||
|
||||
Reference in New Issue
Block a user