Files
road-compiler/.trellis/tasks/archive/2026-09/09-07-junctiontools-standards/prd.md
T

89 lines
7.8 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 行业规范化
## 目标与用户价值
将 JunctionTools 从当前的局部参数面板演进为一个独立、可视化、面向中国城市道路场景的路口编辑器。它必须用用户能辨识的道路、角部和设施对象表达简单与复杂路口,并在编辑前后明确展示几何后果和规范风险。
用户应当能够在一个只显示当前路口及关联道路的工作区中,理解系统识别出的路口形态、选择一个具体对象、用地图手柄或表单编辑它,并知道当前值是推荐、需复核还是不可保存。编辑不要求理解 OSM node ID、segment ID、内部 cluster 或模板名。
## 已确认的产品原则
- 默认规范档为“中国城市道路”。MUTCD/FHWA、NACTO 仅是后续可切换的参考档,不能改变默认输出规则。
- `2×1`、`2×2` 是内部节点布局;前台只显示实际形态,例如 T 字、十字、偏置十字或多臂非规则路口。
- 简单路口、复杂路口、T 字、十字、偏置十字和多臂路口使用同一个对象模型和同一套编辑器信息架构。
- 默认参数是全局值。只有用户明确展开某道路臂、角部或设施后,才创建局部覆盖;局部覆盖可恢复为全局值。
- 编译层是拓扑识别、几何生成和规范校验的唯一权威。前端不根据节点数量推断形态,不复制几何算法。
- 参考 GeoJSON 是只读校准和对照资料,不能直接覆盖 OSM/native 结果。其 `properties.type=1..5` 业务语义未知,不能展示为可编辑业务字段。
- 保留现有可用能力:独立路口视图、预览、地图对象选择、表单编辑、拖拽、草稿、撤销/重做、放弃草稿、保存和版本冲突保护。
## 范围
### 统一路口结构
系统为每个可编辑路口提供稳定的只读 `junctionStructure` 摘要,并为以下对象提供可读名称、稳定内部键、关联几何、可编辑状态和诊断:
| 对象 | 用户可见含义 | 编辑/校验责任 |
| --- | --- | --- |
| 道路臂 | 从路口离开的有效进口/出口道路,而非每条车行道或 OSM 段 | 名称、方向、车道/有效宽度、单行/双向、步行与非机动车状态 |
| 角部 | 两条相邻道路臂之间的转弯区域 | 圆角、步行道转角、相邻导流岛、可行转弯空间 |
| 过街设施 | 对应一个道路臂或角部的人行横道与无障碍连续空间 | 横道跨度、深度、退让、通行连续性 |
| 停止线 | 保护某一过街设施的车辆控制线 | 与横道的相对关系、位置和方向 |
| 导流岛/中央分隔 | 已识别或后续显式配置的分隔和安全岛 | 可用宽度、避让、与过街和转弯空间的关系 |
| 人行道转角 | 步行路径在角部的连续连接 | 连续性、最小可通行带、与圆角/岛的冲突 |
| 信号设施 | 已有信号灯及其关联停止线/过街设施 | 位置可见性和几何关联;不编辑相位配时 |
### 工作区与交互
- 独立 JunctionTools 页面/全屏工作区只渲染当前路口、有效道路臂和关联设施;主地图其他元素不得干扰编辑。
- 顶部显示可读路口标题、实际形态、规范档、参考模式和草稿状态,不显示用户无法辨识的路口编号。
- 左侧按“道路臂、角部、过街与控制设施”列出对象;选中项必须在中心画布中高亮,中心点选对象也必须将右侧表单切换到同一对象。两者一一对应。
- 中间画布显示局部道路、可读道路编号/名称、选区、方向、必要的数值标注及可拖拽手柄。手柄方向必须与表单正方向一致。
- 右侧只显示当前对象的参数、全局或局部覆盖状态、恢复全局操作、推荐/警告/阻塞诊断和定位动作。全局参数的影响范围必须明确写出。
- 底部固定提供撤销、重做、重置当前对象、放弃草稿、应用预览与保存。重置恢复进入该工具时的基线;放弃草稿恢复全部基线。
### 规范校验
第一阶段必须建立下列硬约束与可追踪诊断。具体数值按道路等级、设计速度、地方项目配置由规范档提供,不能把单个演示值冒充全国法定结论。
| 规则 | 最低要求 | 保存语义 |
| --- | --- | --- |
| 车道/道路臂有效宽度 | 不低于适用规范档的最小值;单行和单车道不假定有对向车行道 | 低于物理/配置下限阻塞;偏离推荐值警告 |
| 斑马线覆盖 | 过街跨度覆盖有效车行道及要求的连续步行连接,不被道路边界或岛切断 | 缺口或不连续阻塞 |
| 停止线与斑马线 | 停止线位于车辆来向一侧,与横道保持适用净距,二者不重叠或反向 | 方向错误、重叠或越界阻塞 |
| 角部圆角 | 不得吞没行人过街带、步行转角或相邻设施的净空 | 相交/净空不足阻塞;不舒适尺度警告 |
| 行人连续性 | 每个已配置的过街路径在路缘、角部、岛和对侧人行道之间可连续通过 | 断裂阻塞 |
| 核心与角部面 | 核心面、圆角面、路面/人行道面不得自交、倒置或产生不可用的退化面 | 阻塞 |
| 形态适配 | T 字和多臂路口只生成真实存在的道路臂、角部和设施 | 虚构道路臂或设施阻塞 |
诊断分为三类:`pass` 表示符合项目推荐范围;`warning` 允许预览和保存但需保留原因;`blocking` 禁止保存。属于设计建议的规则不得伪装成保存门禁;几何无效和上述明确不变量必须阻塞保存。
### 参考 GeoJSON 对照
- 显示原始文件、原坐标系、转换后的坐标状态和可读来源说明。
- 允许显示/隐藏、透明度调节以及与当前编译结果的叠加比较。
- 只按空间匹配结果组织参考要素,比较中心、边界框、面积和方向差异;不得按原始 `type` 猜测道路面、横道、岛或人行道。
- 后续可根据高置信度匹配提出“建议值”,但须由用户接受,绝不直接写入草稿或原始配置。
## 非范围
- 不修改 OSM 拓扑,不创建或删除道路、节点或任意自由多边形。
- 不在本任务中实现信号相位、配时、联锁或交通仿真。
- 不承诺同时满足所有地方强制条文,也不将参考规范档包装为法定审查工具。
- 不从参考 GeoJSON 自动拟合或覆写完整道路边界。
- 不在同一阶段一次性实现所有高级设施;导流岛、中央分隔、非机动车过街、无障碍细部和信号关联按阶段交付。
## 验收标准
1. 打开任一路口后,用户能看到实际形态、有效道路臂数量、规范档、设施摘要和草稿状态,主文案不暴露内部 ID。
2. 道路臂、角部、横道、停止线和信号设施在列表、画布和右侧表单中严格一一对应;选中、聚焦和诊断定位一致。
3. 全局值、局部覆盖和恢复全局有明确状态与可逆操作;重置当前对象和放弃草稿都恢复正确基线。
4. T 字、十字、偏置十字和多臂真实 OSM 样例均按有效道路臂渲染,绝不凭内部节点布局补出不存在的道路臂、角部或设施。
5. 对车道/道路臂宽度、横道覆盖、停止线-横道关系、圆角、行人连续性和多边形有效性至少各有一个可重复的通过、警告或阻塞测试。
6. 阻塞诊断阻止保存并将对应对象高亮;警告不会破坏预览/保存链路,且会保留到诊断记录。
7. 参考层可安全叠加、隐藏并显示可读差异;关闭、缺失或匹配失败时不会改变 native 输出或现有编辑功能。
8. 现有普通路口、复杂路口切换、手柄方向、信号显示、草稿放弃、版本冲突以及页面回归均通过现有和新增自动化测试。
## 规划结论与未决项
当前没有阻塞产品决策。数值规则将以带来源、版本、适用条件和项目覆盖项的配置交付;第一阶段的目标是可解释且可测试的项目规范校验,不声称完成法定设计审查。