7.8 KiB
JunctionTools 路口编辑工作区
父任务:.trellis/tasks/08-26-direct-manipulation-road-editor。需求来源与权威合约在父任务的 prd.md / design.md。
目标
用地图上的可识别路口区域作为入口,进入专用的局部 JunctionTools 工作区,在不破坏主地图编辑状态的前提下逐步承载路口几何、进口、控制设施和诊断编辑。远景参考 MATLAB RoadRunner 的路口局部编辑体验,但首期只建立可靠的识别、热区、进入/返回和单路口编辑基础,不追求一次实现完整路口建模。
当前产品设想
- 主地图识别普通路口和已配置的复杂路口 cluster,并以可点击热区表达,而不是依赖点击某一条道路或控制柄。
- 点击热区后进入独立 JunctionTools 编辑器,聚焦路口局部上下文;返回主地图时保留原地图视角、选中对象和未保存编辑。
- 编辑器逐步扩展为路口专用工作区:进口宽度、cutback、角部圆角、路口面、车道/connector、斑马线、停止线和诊断在同一 session 中协调。
- 所有编辑复用现有 direct-edit 文档、preview、revision、undo/redo 和导出契约,不建立第二套持久化几何。
RoadRunner 对标拆解
RoadRunner 的路口能力不能简化成几个拖拽手柄。对本项目有价值的能力可拆成四层:
- 路口识别与入口:从相交道路形成可识别的 junction 对象,并在场景中提供明确的选择目标。
- 局部工作区:聚焦一个路口,显示进口、边界、车道、连接关系、标线和诊断,编辑完成后回到整体场景。
- 几何与拓扑编辑:调整进口宽度、路口边界、转角圆角、车道连接和车道数,并让派生几何保持连续、合法。
- 设施与验证:在路口上下文中布置或调整停止线、斑马线、信号灯等设施,并对冲突、自交、车道宽度和连接状态给出反馈。
本项目的映射不是复制 RoadRunner 内部实现:OSM 中心线和拓扑是只读输入,GeoJSON 是派生输出;可持久化的对象必须是 node/cluster 锚定的语义约束。当前代码已经具备 cluster candidate 检测、complex-junction 几何生成、三类 junction 约束和 preview/save/revision 基础,但缺少“热区 → JunctionTools 工作区”的产品层闭环。
分阶段方向
- 阶段 A:派生路口热区和识别状态(普通 node、已确认 cluster、候选 cluster),点击后进入/返回工作区。
- 阶段 B:单路口局部上下文和现有
junction-approach-width、junction-cutback、junction-corner-radius编辑闭环。 - 阶段 C:车道/connector、斑马线、停止线、信号灯的联动编辑和冲突诊断。
- 阶段 D:cluster 多节点、多进口、多角部及更接近 RoadRunner 的拓扑创作能力。
阶段 A 不应把热区写成新的几何事实;它应由编译模型和 junction plan 派生,避免出现 UI 有路口而编译器不认的第二套数据。
本轮已决边界
- 首期只有普通
node可编辑;已确认cluster只读,candidate cluster只展示识别结果与诊断。 - 阶段 B 只开放进口宽度、cutback、单角部圆角;车道/connector 先展示并诊断,不开放拓扑写入。
- 设施首期允许移动或修改已有斑马线、停止线、信号灯,但不允许创建或删除设施。
- “应用到工作区”形成一个 undo 步骤,并进入主地图共用历史栈;连续拖拽不逐帧进入 undo。
- 离开工作区前必须选择应用并返回、放弃并返回或留在工作区,不自动应用或自动放弃。
- 保存时若编译模型或文档版本变化,拒绝保存并保留草稿,要求重新加载后处理,不自动覆盖或自动 rebase。
- candidate 不得在本轮被确认或转化为持久化 cluster。
- 自交、越界、最小车道宽度等几何非法诊断为
blocking;可修复的设施缺失或间距问题可为warning。 - JunctionTools 使用独立 URL 路由,例如
/junction/:type/:id,支持刷新、浏览器返回和深链接。
总体约束
- OSM 节点、道路中心线和基础拓扑只读;编辑保存语义约束,不保存派生 GeoJSON。
- 普通 node 与复杂 cluster 使用不同的
JunctionRef锚点,不把 cluster 降级成多个普通 node。 - 热区、路口边界和可编辑对象必须来自同一份编译状态;候选识别不能静默改变几何。
- 路口编辑必须复用现有 preview、active document、revision、版本冲突保护和 undo/redo。
- 无效几何不得替换最后有效预览;必须返回结构化诊断。
- 路口 session 与主地图 session 互斥,切换对象前必须应用或取消草稿。
- 导出包契约保持
native-road-package/v1.1不变。
子任务地图
09-02-junction-requirements-research:RoadRunner 能力、用户流程、术语和需求验收基线。09-02-junction-detection-hotspot:node/cluster/candidate 识别、热区派生模型和点击入口。09-02-junction-tools-workspace:独立工作区路由、上下文加载、返回和 session 状态机。09-02-junction-geometry-editor:进口宽度、cutback、圆角、车道/connector 的统一求解与预览。09-02-junction-facilities-validation:斑马线、停止线、信号灯联动、诊断和最终发布验证。
依赖顺序为 1 → 2 → 3 → 4 → 5;每个子任务独立验收,父任务负责跨任务契约和最终集成。
顺序依赖
前置:direct-edit-solver-api(junction 相关的三个 kind 求解与预览端点)与 direct-edit-map-editor(EditSession、ghost/preview 图层、命令栈)。
后继:无。cluster 高级编辑、多路口联动为独立后续任务。
范围
- 路口识别结果和热区入口的最小交互。
- 单
JunctionRef({type:'node'|'cluster', id})的工作区路由与返回主地图的上下文保持;首期只有node进入可编辑 session,cluster与 candidate 只读。 - 加载该路口的编辑上下文:路口面、进口、相邻道路短上下文、车道/connector、步行带、停止线、斑马线、诊断与当前约束。
- 三项可拖能力:进口宽度、cutback、单个角部圆角。
- session draft:首次拖拽即 ghost,防抖后服务端权威局部预览。
- 「应用到工作区」合并有效草稿为活动副本的未保存约束;「保存」持久化;「取消」丢弃草稿并复原。
- 会话边界:切换相邻路口前必须应用或取消。
不做
- cluster 的高级编辑与复合路口模板编排。
- 多个路口的联合会话或联动编辑。
- 控制设施的新建、删除和身份创建;首期只允许修改已有设施的语义参数。
- 主地图道路区间的编辑(属
direct-edit-map-editor)。 - OSM 图拓扑的修改。
- 一次性实现 RoadRunner 级别的完整路口建模、任意拓扑创作或多路口联合编辑。
验收标准
- 从路口面或诊断可进入工作区,并能带位置返回主地图。
- 三项能力各自可拖,首次拖拽即有 ghost,防抖后显示服务端权威几何。
- 预览包含全部受影响派生对象:道路面、路口面、步行带、车道中心线、connector/movement、停止线、斑马线、标线。
- 拟合失败时返回最后有效几何加结构化诊断,不把非法图形显示成已应用。
- 「应用到工作区」后返回主地图仍显示同一几何,且该编辑处于未保存状态、可被主地图 undo/redo 管理。
- 「取消」后回到进入工作区前的状态,活动副本无残留。
- 未处理草稿时切换相邻路口被拒绝,并提示先应用或取消。
- 「保存」后重新编译几何不变,约束状态
exact。 npm run format:check、npm run test、npm run test:client、npm run test:client:unit、npm run build全绿。