# 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 的路口能力不能简化成几个拖拽手柄。对本项目有价值的能力可拆成四层: 1. 路口识别与入口:从相交道路形成可识别的 junction 对象,并在场景中提供明确的选择目标。 2. 局部工作区:聚焦一个路口,显示进口、边界、车道、连接关系、标线和诊断,编辑完成后回到整体场景。 3. 几何与拓扑编辑:调整进口宽度、路口边界、转角圆角、车道连接和车道数,并让派生几何保持连续、合法。 4. 设施与验证:在路口上下文中布置或调整停止线、斑马线、信号灯等设施,并对冲突、自交、车道宽度和连接状态给出反馈。 本项目的映射不是复制 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` 不变。 ## 子任务地图 1. `09-02-junction-requirements-research`:RoadRunner 能力、用户流程、术语和需求验收基线。 2. `09-02-junction-detection-hotspot`:node/cluster/candidate 识别、热区派生模型和点击入口。 3. `09-02-junction-tools-workspace`:独立工作区路由、上下文加载、返回和 session 状态机。 4. `09-02-junction-geometry-editor`:进口宽度、cutback、圆角、车道/connector 的统一求解与预览。 5. `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` 全绿。