85 lines
3.7 KiB
Markdown
85 lines
3.7 KiB
Markdown
# Phase 0：冻结契约与 parity 基线
|
||
|
||
父任务：`.trellis/tasks/08-25-road-compiler-extraction/`
|
||
契约权威定义：父任务 `design.md` §1
|
||
|
||
## Goal
|
||
|
||
在任何代码移动之前，把 `native-road-package/v1` 契约落成仓库内文档，
|
||
并为两个有效区域建立可复跑的逐文件 parity 基线，作为全案唯一 oracle。
|
||
|
||
**本阶段不移动、不重构任何生产代码。** 只新增文档、基线数据和一个校验脚本。
|
||
|
||
## Requirements
|
||
|
||
### R0.1 契约文档
|
||
|
||
- 把父任务 `design.md` §1（输入契约 / 输出契约 / 消费方式）落成
|
||
`docs/native-road-package-v1.md`。
|
||
- 文档必须列全 12 个图层名、`compiled.json` 顶层结构、`diagnostics.json` 记录形状、
|
||
stdout 标记格式。
|
||
- Phase 2 会把该文档搬进编译器仓库，此处先落在宿主。
|
||
|
||
### R0.2 确定性前置核查 🔴
|
||
|
||
**基线只有在编译器确定性的前提下才有意义。** 必须先证明这一点。
|
||
|
||
- 对同一输入连续跑两次 `road:compile`，比较全部输出文件。
|
||
- 识别并记录所有 volatile 字段（时间戳、绝对路径、staging 目录名、
|
||
任何来自 `mkdtemp` 的随机名、Map/Set 迭代顺序敏感的输出）。
|
||
- 校验脚本必须归一化或排除这些字段。
|
||
- 若发现真实的非确定性（相同输入产出不同几何），**必须先修掉再继续**，
|
||
否则整个拆分没有 oracle。
|
||
|
||
### R0.3 parity 校验脚本
|
||
|
||
- 新增 `scripts/road-parity.js`（宿主侧，Phase 2 随编译器搬走）。
|
||
- 能力：
|
||
- `--snapshot <out.json>` 遍历指定区域的 `native-road/` 全部文件 +
|
||
`native-traffic-signals.json`，归一化后输出排序稳定的 checksum 清单
|
||
- `--compare <baseline.json>` 与基线比对，差异逐文件报告
|
||
- 非零退出码表示不一致
|
||
- GeoJSON 需按稳定键排序后再 hash（避免 feature 顺序抖动造成假阳性），
|
||
但**顺序本身若变化必须被报告**——用两个 hash：`contentHash`（排序后）
|
||
与 `orderHash`（原序），分别报告。
|
||
|
||
### R0.4 两区域基线
|
||
|
||
- 区域：`fengshu-er-road`、`nantaizi-lake-innovation-valley`
|
||
- 从干净状态跑 `npm run road:compile`，产出基线 JSON 提交进版本控制
|
||
- 基线文件位置：`.trellis/tasks/08-25-road-compiler-extraction/baseline/<area>.json`
|
||
（Phase 2 搬进编译器仓库当测试语料，见父任务 R4）
|
||
|
||
`hanyang-block` 是废案，不纳入编译、快照或后续 parity 兼容范围。
|
||
|
||
### R0.5 K2 决策定档
|
||
|
||
`comparison.json` 依赖宿主 osm2streets 产物（`compile-native-roads.js:87` 读
|
||
`area.outputs.geojsonDir`），拆出后不可达。本阶段必须做出决策并写入契约文档：
|
||
|
||
- 方案 A：移除 `comparison.json`（osm2streets 已 legacy）
|
||
- 方案 B：保留，`comparisonDir` 作为可选输入注入
|
||
- 倾向 A。决策写入 `docs/native-road-package-v1.md` 的「已移除能力」一节。
|
||
|
||
## Acceptance Criteria
|
||
|
||
- [x] AC0.1 `docs/native-road-package-v1.md` 存在，覆盖输入契约、输出契约、
|
||
12 图层清单、stdout 标记、已移除能力
|
||
- [x] AC0.2 连续两次编译的 parity 比对通过（确定性已证明），volatile 字段清单已记录在文档内
|
||
- [x] AC0.3 `scripts/road-parity.js` 可用，`--snapshot` / `--compare` 均工作，
|
||
不一致时非零退出
|
||
- [x] AC0.4 两个区域基线 JSON 已提交，且每个都能用 `--compare` 自比对通过
|
||
- [x] AC0.5 K2 决策已定档并写入契约文档
|
||
- [x] AC0.6 未修改任何生产代码（`git diff` 只含新增文档 / 脚本 / 基线）
|
||
|
||
## 依赖与顺序
|
||
|
||
- 无前置依赖，本阶段是全案入口
|
||
- **阻塞** Phase 1、2、3、4 —— 没有基线就没有 oracle
|
||
|
||
## Out of Scope
|
||
|
||
- 任何生产代码改动（含"顺手修一下"）
|
||
- 目录结构调整
|
||
- `compiled.json` 结构变更
|