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

119 lines
3.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Phase 1 执行计划
分批搬迁,每批后跑 parity。**不要一次性大搬。**
## Step 0 — 前置
```bash
# 基线必须先绿
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/` 检查反向依赖
## 验证命令汇总
```bash
# 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 清理)。