Files
road-compiler/.trellis/tasks/08-26-direct-edit-junction-tools/design.md
T

2.5 KiB
Raw Blame History

总体设计

边界

JunctionTools 是主地图之外的局部编辑器。主地图只负责显示派生热区和进入入口;编辑器负责一个 JunctionRef 的上下文、草稿、预览、应用、保存和取消。

数据流

compiled model/junctionPlans → junction descriptors → hotspot layer → JunctionRef → junction session → semantic constraints → /api/edit-preview → affected layers → apply/save → active document/revision。

热区是派生显示对象,不新增持久化 schema。node 使用 node id,cluster 使用 cluster id 加 arm/corner 锚点。所有长度使用米,位置锚定 station 或 OSM node。

编辑器分层

  • junction-detection:纯逻辑识别 descriptor、状态和热区几何。
  • junction-workspace:路由、上下文加载、session 四态和主地图返回。
  • junction-solver:把 node/cluster 约束归一为 effective plan,供普通与复杂几何共同消费。
  • junction-facilities:设施联动、诊断汇总和发布前检查。
  • OpenLayers 仅作为显示/输入 adapter,不能直接写正式编译 source。

首期决策约束

  • JunctionRef 首期只允许 type: 'node' 进入可编辑 session;cluster 和 candidate descriptor 可展示但不可写入。
  • 工作区与主地图共享 undo/redo 栈;一次“应用到工作区”是一个历史边界,拖拽过程只产生 draft/preview。
  • 工作区离开由显式守卫控制:有未处理草稿时必须应用、放弃或取消离开;不得静默处理草稿。
  • 保存请求必须携带打开时的文档/编译版本。版本不一致返回冲突,保留本地草稿,不做强制覆盖或隐式 rebase。
  • 阶段 B 的求解写入仅覆盖三种既有 junction constraint;车道、connector 和设施在此阶段只作为派生上下文与诊断输入。
  • 设施编辑只允许修改已有设施的语义 override,不新增或删除设施身份。
  • 诊断接口必须提供稳定 code 和 severity,几何非法为 blocking,非致命设施问题可为 warning。
  • JunctionTools 通过独立路由承载 JunctionRef,路由变化不得重建 MapCanvas,返回时恢复主地图视角和选择快照。

兼容与回滚

阶段 A/B 可挂在现有编辑开关下;未进入 JunctionTools 时主地图行为不变。cluster 几何统一前不得开放 cluster 写入。任何阶段失败都可回退到只读热区或现有普通路口编辑,不影响 v1 overrides、v2 文档和导出包。