Files
road-compiler/.trellis/tasks/archive/2026-09/08-26-direct-manipulation-road-editor/research/revisions.md
T

2.4 KiB

可复现存盘与 OSM 重导入

问题

仅让最新的 native-road-overrides.json 跟随当前导入 OSM,会使用户无法安全比较“原始 OSM + 精修”和“新的 OSM + 重放精修”。输出 GeoJSON 又不足以解释或再次编辑场景。

建议:不可变 revision,活动工作副本

工作区有一个可编辑的活动副本;每个 revision 都是可重新编译、可审计的冻结快照。OSM 重导入创建新的候选 revision 或工作分支,永不原地覆盖已保存 revision。

工作区
  active/                    当前暂存编辑
  revisions/
    rev-0001/                不可变的“导入基线”
    rev-0002/                命名检查点
    rev-0003/                基于新 OSM 的候选版本

每个 revision 至少保存:

interface RoadRevisionManifest {
  schema: 'road-workbench-revision/v1'
  id: string
  createdAt: string
  label?: string
  parentRevisionId?: string
  source: {
    osmFile: string
    osmSha256: string
    areaConfigFile: string
    areaConfigSha256: string
  }
  documents: {
    nativeRoadOverrides: string
    directEdits: string
    trafficSignals: string
  }
  compiler: {
    packageVersion: string
    gitCommit?: string
    geometrySchema: string
  }
  outputs?: { manifest: string; compiledSha256: string }
}

OSM、area config 和各 JSON 文档均在 revision 目录中复制,manifest 保存 digest。派生输出可作为缓存/审阅证据保存,但“复现来源”始终是输入文档和 compiler identity;恢复时应可重新编译验证 digest,并提示编译器版本差异。

对冲突体验的作用

  • 在当前 revision 内修改 OSM 并重导入,不会破坏旧 revision 的可用性。
  • 用户可以在新 revision 上尝试约束重放并获得精确/可疑/失效状态,同时随时返回旧版本查看原效果。
  • 确认 rebase 后才将新 revision 设为活动版本;失败也不会丢失已精修场景。
  • 保存操作记录同样随 revision 冻结,便于审计;活动副本的未保存 undo/redo 不进入不可变 revision。

已确定的创建策略

  • 导入 OSM 自动创建不可变基线 revision。
  • 用户明确执行“保存检查点”时创建带名称的不可变 revision。
  • 普通保存、草稿预览和重新编译只更新活动副本,不自动制造 revision。

这一策略以可审阅的检查点承载长期历史,避免把高频拖拽/保存变成难以浏览的版本噪声。