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,10 +1,69 @@
|
||||
# 最小 JunctionTools
|
||||
# JunctionTools 路口编辑工作区
|
||||
|
||||
父任务:`.trellis/tasks/08-26-direct-manipulation-road-editor`。需求来源与权威合约在父任务的 `prd.md` / `design.md`。
|
||||
|
||||
## 目标
|
||||
|
||||
用专用工作区承载路口编辑,验证单一普通路口的进口宽度、cutback 与单个角部圆角,闭合"预览 → 应用到工作区 → 保存 → 取消"四态。这是路口能力的最小可信切片,不是完整路口编辑器。
|
||||
用地图上的可识别路口区域作为入口,进入专用的局部 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;每个子任务独立验收,父任务负责跨任务契约和最终集成。
|
||||
|
||||
## 顺序依赖
|
||||
|
||||
@@ -13,7 +72,8 @@
|
||||
|
||||
## 范围
|
||||
|
||||
- 单 `JunctionRef`(`{type:'node'|'cluster', id}`,本期只走 `node`)的工作区路由与返回主地图的上下文保持。
|
||||
- 路口识别结果和热区入口的最小交互。
|
||||
- 单 `JunctionRef`(`{type:'node'|'cluster', id}`)的工作区路由与返回主地图的上下文保持;首期只有 `node` 进入可编辑 session,`cluster` 与 candidate 只读。
|
||||
- 加载该路口的编辑上下文:路口面、进口、相邻道路短上下文、车道/connector、步行带、停止线、斑马线、诊断与当前约束。
|
||||
- 三项可拖能力:进口宽度、cutback、单个角部圆角。
|
||||
- session draft:首次拖拽即 ghost,防抖后服务端权威局部预览。
|
||||
@@ -24,9 +84,10 @@
|
||||
|
||||
- cluster 的高级编辑与复合路口模板编排。
|
||||
- 多个路口的联合会话或联动编辑。
|
||||
- 控制设施的逐个手工布置。
|
||||
- 控制设施的新建、删除和身份创建;首期只允许修改已有设施的语义参数。
|
||||
- 主地图道路区间的编辑(属 `direct-edit-map-editor`)。
|
||||
- OSM 图拓扑的修改。
|
||||
- 一次性实现 RoadRunner 级别的完整路口建模、任意拓扑创作或多路口联合编辑。
|
||||
|
||||
## 验收标准
|
||||
|
||||
|
||||
Reference in new issue
Block a user