Files
road-compiler/.trellis/tasks/archive/2026-09/08-26-direct-edit-junction-tools/prd.md
T

111 lines
8.6 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 路口编辑工作区
父任务:`.trellis/tasks/08-26-direct-manipulation-road-editor`。需求来源与权威合约在父任务的 `prd.md` / `design.md`。
## 目标
用地图上的可识别路口区域作为入口,进入一个独立的 JunctionTools 路口编辑页面。页面专注展示单个路口及其完整局部上下文,在同一可视化画布和同一编辑会话中同时承载路口几何、已有设施、参数双向联动、预览和诊断。主地图只负责发现、导航和返回,不承载完整路口编辑体验。
## 当前产品设想
- 主地图识别普通路口和已配置的复杂路口 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:独立单路口页面、局部上下文和现有三项几何参数编辑闭环。
- 阶段 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 级别的完整路口建模、任意拓扑创作或多路口联合编辑。
## 验收标准
### 独立一体化页面方向(2026-09-03)
- [ ] `/junction/:type/:id` 是独立路口编辑页面,进入后自动聚焦单个路口;主地图只作为入口和返回目标。
- [ ] 页面画布持续展示路口几何与已有斑马线、停止线、信号灯,参数面板不得遮挡主要路口视图。
- [ ] 几何参数和已有设施调整在同一页面、同一 draft/preview/undo/apply/save/cancel 链路中完成。
- [ ] 表单与地图操作双向同步:表单修改反映到画布,地图拖拽回写参数;失败预览保留最后有效几何并显示诊断。
- [ ] 首版支持已有设施的移动或已有字段修改,不创建、删除或跨路口迁移设施;cluster 与 candidate 继续只读。
- [ ] 从路口面或诊断可进入工作区,并能带位置返回主地图。
- [ ] 三项能力各自可拖,首次拖拽即有 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` 全绿。