119 lines
4.0 KiB
Markdown
119 lines
4.0 KiB
Markdown
# Phase 0 执行计划
|
||
|
||
## 前置
|
||
|
||
- [ ] 分支：`experiment/road-compiler-rethink`（已在）
|
||
- [ ] 确认工作区干净（`.trellis/tmp-*.js` 五个未跟踪文件与本任务无关，可先清理或忽略）
|
||
- [ ] 阅读父任务 `design.md` §1 契约定义
|
||
|
||
## Step 1 — 摸清两区域当前状态
|
||
|
||
```bash
|
||
ls config/areas/
|
||
for d in outputs/*/native-road/layers; do echo "$d: $(ls $d | wc -l)"; done
|
||
```
|
||
|
||
判定：`hanyang-block` 为废案，不纳入本阶段；只核查两个有效区域的配置与当前产物。
|
||
|
||
- [x] 逐区域检查 config 的 `nativeRoad.edgeLines` / `junctionTemplates.enabled`
|
||
- [x] 将两个有效区域的配置差异记录在基线 README
|
||
|
||
**门槛**：两个有效区域的图层差异有书面解释。
|
||
|
||
## Step 2 — 确定性核查
|
||
|
||
```bash
|
||
# 备份
|
||
cp -r outputs/<area>/native-road /tmp/rc-baseline-a
|
||
# 重编
|
||
rm -rf outputs/<area>/native-road
|
||
npm run road:compile -- --config config/areas/<area>.json
|
||
cp -r outputs/<area>/native-road /tmp/rc-baseline-b
|
||
# 比对
|
||
diff -r /tmp/rc-baseline-a /tmp/rc-baseline-b
|
||
```
|
||
|
||
- [x] 对两个有效区域各跑一遍
|
||
- [x] 记录所有差异字段 → volatile 清单
|
||
- [x] 额外一轮：删掉 `native-traffic-signals.json` 重生成，
|
||
确认信号 ID 是否确定（`traffic-signals.js` require 了 `crypto`，重点核查）
|
||
- [ ] 若发现**几何坐标级**的非确定性 → 停止本阶段，先开 bug 任务修掉
|
||
|
||
**门槛** 🔴：确定性已证明，或非确定性已定位并修复。这是全案的地基。
|
||
|
||
## Step 3 — 写 `scripts/road-parity.js`
|
||
|
||
按 `design.md` §2 实现。
|
||
|
||
- [x] `--snapshot` 生成归一化 checksum 清单
|
||
- [x] `--compare` 比对并逐文件报差异，不一致时非零退出
|
||
- [x] GeoJSON 双 hash（`contentHash` 排序后 / `orderHash` 原序）
|
||
- [x] volatile 字段按 Step 2 结论归一化
|
||
- [x] 自验：同一区域连跑两次 snapshot，`--compare` 必须通过
|
||
|
||
```bash
|
||
node scripts/road-parity.js --config config/areas/fengshu-er-road.json --snapshot /tmp/s1.json
|
||
node scripts/road-parity.js --config config/areas/fengshu-er-road.json --compare /tmp/s1.json
|
||
echo "exit=$?" # 必须为 0
|
||
```
|
||
|
||
**门槛**：脚本对未改动的代码报告一致。
|
||
|
||
## Step 4 — 建立两区域基线
|
||
|
||
```bash
|
||
mkdir -p .trellis/tasks/08-25-road-compiler-extraction/baseline
|
||
for a in fengshu-er-road nantaizi-lake-innovation-valley; do
|
||
rm -rf outputs/$a/native-road
|
||
npm run road:compile -- --config config/areas/$a.json
|
||
node scripts/road-parity.js --config config/areas/$a.json \
|
||
--snapshot .trellis/tasks/08-25-road-compiler-extraction/baseline/$a.json
|
||
done
|
||
```
|
||
|
||
- [x] 两个基线 JSON 生成
|
||
- [x] 写 `baseline/README.md`：生成时的 git commit、命令、volatile 字段清单、
|
||
两个有效区域图层差异的解释
|
||
- [x] 反向自验：再跑一次 `--compare` 两个基线全部通过
|
||
|
||
## Step 5 — K2 决策
|
||
|
||
- [x] 检查 `comparison.json` 当前是否真被消费（grep 宿主与 workbench）
|
||
- [x] 若有 → 方案 B（可选注入），在契约里定义 `comparisonDir` 为 optional
|
||
|
||
## Step 6 — 落契约文档
|
||
|
||
- [x] 写 `docs/native-road-package-v1.md`，内容源自父任务 `design.md` §1
|
||
- [x] 补入 Step 2 的 volatile 字段清单
|
||
- [x] 补入 Step 5 的 K2 决策
|
||
- [x] 在 `docs/changelog.md` 记一行
|
||
|
||
## 验证命令汇总
|
||
|
||
```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
|
||
|
||
# 确认无生产代码改动
|
||
git diff --stat -- scripts/lib blender
|
||
```
|
||
|
||
最后一条必须为空输出 —— Phase 0 不碰生产代码。
|
||
|
||
## Review Gate
|
||
|
||
全部 AC0.1–AC0.6 打勾后，再进 Phase 1。**基线不可靠时不要前进。**
|
||
|
||
## Rollback
|
||
|
||
本阶段纯新增（文档 / 脚本 / 基线数据）。回滚 = 删除新增文件。
|
||
唯一例外：Step 2 若发现并修复了非确定性 bug，那部分是真实代码改动，
|
||
应拆成独立 commit 并单独保留。
|