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

35 lines
2.5 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.
# 总体设计
## 边界
`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 文档和导出包。