docs(tasks): plan junction tools delivery
This commit is contained in:
1 parent
6a0736517f
commit
8c99bb7340
14 files changed
+211
-60
No files matched your search
@@ -1,21 +1,34 @@
|
||||
# 设计
|
||||
# 总体设计
|
||||
|
||||
技术合约不在本文重复定义。权威定义见父任务 `.trellis/tasks/08-26-direct-manipulation-road-editor/design.md` 的以下小节:
|
||||
## 边界
|
||||
|
||||
- 「约束模型」— `junction-approach-width`、`junction-cutback`、`junction-corner-radius` 三个 kind 与其锚点。
|
||||
- 「编辑所有权」— junction reserve 独占、`junction-approach-width` 优先于道路 profile、单 `JunctionRef` 会话。
|
||||
- 「Handle manifest」— 手柄字段与 `reserves`。
|
||||
- 「预览时序与延迟预算」— 防抖、`previewSeq` 仲裁、`degraded`。
|
||||
- 「上线与回滚形态」— `directEdit` 开关。
|
||||
`JunctionTools` 是主地图之外的局部编辑器。主地图只负责显示派生热区和进入入口;编辑器负责一个 `JunctionRef` 的上下文、草稿、预览、应用、保存和取消。
|
||||
|
||||
会话状态、四态语义与所有权边界的完整推导见父任务 `research/junction-tools.md`。
|
||||
## 数据流
|
||||
|
||||
## 本子任务的局部决定
|
||||
`compiled model/junctionPlans` → `junction descriptors` → `hotspot layer` → `JunctionRef` → `junction session` → `semantic constraints` → `/api/edit-preview` → affected layers → apply/save → active document/revision。
|
||||
|
||||
- 工作区是独立路由,不是主地图上的浮层面板:路口编辑是高密度局部操作,叠在主地图上会与道路手柄争夺命中区。
|
||||
- 复用 `direct-edit-map-editor` 的 `EditSession`、ghost/preview source 与命令栈,不新建第二套编辑基础设施。差异只在加载的上下文范围与可用 kind。
|
||||
- 草稿属于活动工作副本的 session,不是独立导出文件。因此「取消」只需丢弃 session,不涉及文件回滚。
|
||||
- 「应用到工作区」不写盘:合并后的约束是活动副本的未保存状态,交给主地图的普通 undo/redo 管理。这样保存路径只有一条。
|
||||
- 会话互斥用显式守卫实现:存在未处理草稿时切换 `JunctionRef` 直接拒绝并提示,不做自动应用或自动丢弃——两者都会让用户丢失意图。
|
||||
- 本期只实现 `JunctionRef.type === 'node'`。`cluster` 分支保留类型但入口置灰,避免把 cluster 降级成多个互相冲突的普通路口编辑。
|
||||
- 单个角部圆角:本期只允许编辑一个 corner,多角部批量编辑属后续任务。
|
||||
热区是派生显示对象,不新增持久化 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 文档和导出包。
|
||||
Reference in new issue
Block a user