# JunctionTools 行业规范化设计 ## 边界与职责 JunctionTools 是编译结果的局部编辑工作区,不是另一套地图或另一套几何引擎。它只显示当前路口及关联道路,所有几何推导和拓扑判断仍由编译器完成。 | 层 | 责任 | 不负责 | | --- | --- | --- | | 编译层 | 识别有效道路臂与形态、生成核心/角部/设施几何、构造结构摘要、执行几何与规范校验 | 组件状态、选择样式、表单布局 | | 服务/API 层 | 以同一 revision 提供结构、诊断、手柄、局部预览与保存;返回稳定对象键和可读标签 | 由客户端重新计算拓扑或范围 | | 客户端 | 局部画布、对象选择、表单、全局/局部覆盖、诊断解释和参考层呈现 | 根据节点数分类、猜测引用 GeoJSON `type` 语义、绕过校验保存 | 现有 direct-edit revision、草稿、预览、放弃、保存和冲突保护是底座。新结构只能旁路扩展这些协议,不能另建一条无版本保护的保存路径。 ## 规范化对象合约 每次状态/预览响应在现有路口描述之上提供只读 `junctionStructure`。其对象键内部稳定但不作为默认 UI 标题;所有对象均附带 `label`、`geometryRef`、`editable` 和 `validationRefs`。 ```ts type JunctionStructure = { junctionKey: string; label: string; shape: { kind: 'cross' | 'offset-cross' | 't-junction' | 'multi-arm' | 'unsupported'; label: string; effectiveArmCount: number; throughPairCount: number; }; arms: RoadArm[]; corners: JunctionCorner[]; facilities: Crossing | StopLine | IslandOrMedian | SidewalkTurn | Signal[]; standards: StandardsEvaluation; reference?: ReferenceComparison; }; type RoadArm = { key: string; label: string; heading: number; directionality: 'one-way' | 'two-way' | 'unknown'; carriageway: { laneCount?: number; effectiveWidthMeters?: number }; pedestrian?: { connected: boolean; bicycleConnected?: boolean }; geometryRef: string; overrideState: OverrideState; }; type OverrideState = { mode: 'global' | 'local'; inheritedFrom?: string; resetToGlobalAvailable: boolean; }; ``` `Corner` 通过相邻道路臂键表达归属,而不是以四角索引假定十字路口;`Crossing` 和 `StopLine` 都显式关联道路臂和彼此的对象键;`Signal` 只表达现有设施和关联关系。没有输入证据的道路臂、岛、横道、停止线或信号不得在 T 字、多臂或单行道路中被虚构。 ### 全局与局部覆盖 参数定义为 `scope=global | object`,并记录生效来源。全局写入影响集合中的所有适用对象;局部写入只影响选定对象。用户选择“单独调整”才创建局部值,选择“恢复全局”删除局部覆盖并立即以全局值预览。 不能机械地把任意全局参数复制到所有对象。编译层应只暴露对该对象和路口形态有效的参数,例如 T 字没有第四角的局部圆角;单行道路没有假想的对向车道宽度。 ## 工作区信息架构 ```text ┌ 标题(可读路口名)· 实际形态 · 中国城市道路 · 参考模式 · 草稿状态 ┐ ├ 道路臂 / 角部 / 设施 ┬ 当前路口局部画布 ┬ 参数与诊断 ┤ │ 可读名称、类型、状态 │ 道路标签、方向、选区、手柄、参考叠加、诊断定位 │ 对象名、作用域、字段、恢复全局、规则 │ ├──────────────────────────────────────────────────────────────────────────┤ │ 撤销 · 重做 · 重置当前对象 · 放弃草稿 · 应用预览 · 保存 │ └──────────────────────────────────────────────────────────────────────────┘ ``` - 顶栏只保留决策性状态;内部 node/cluster ID 可以在调试信息中出现,绝不占主标题。 - 左栏以“道路臂、角部、过街与控制设施”分组,条目使用道路名;无法取得名称时使用稳定的“道路 1、道路 2”并在画布同色标注。 - 中央画布是隔离的局部范围。对象呈现必须支持 `default`、`hover`、`selected`、`warning`、`blocking` 和 `disabled`,并能显示代表同一对象的多个几何片段。 - 选择来源无差别:列表点击、地图点击、诊断“定位”或手柄聚焦都写入唯一 `selectedObjectKey`。右栏订阅该键,不根据最近修改的字段猜测上下文。 - 参数输入使用支持单位、步进上下键、范围和无效态的现有成熟组件。拖动产生的预览与表单使用同一约束值及同一正方向;如果没有安全的手柄,保留表单但明确原因。 ## 标准档与校验合约 标准档是版本化数据,不是散落在组件中的魔法常量。 ```ts type StandardsProfile = { id: string; label: string; jurisdiction: string; version: string; sources: Array<{ title: string; edition?: string; clause?: string; url?: string }>; applicability: { roadClasses: string[]; designSpeedsKph?: number[]; shapeKinds: string[] }; rules: Array<{ id: string; objectKinds: string[]; recommended?: Range; warning?: Range; blocking?: Range | GeometryInvariant; level: 'guidance' | 'hard-invariant'; }>; projectOverrides?: Record; }; ``` 首个档案 `cn-urban-default` 记录来源、适用道路等级、设计速度和项目覆盖项。内容按三种层次执行: 1. **设计建议**:推荐范围和警告范围,允许保存,例如舒适圆角、优选横道尺度。 2. **规范下限/项目约束**:由配置给出阻塞范围,例如适用车道宽度、有效步行带和停止线净距。 3. **几何不变量**:不依赖地域数值,始终阻塞,例如自交、反向停止线、横道未覆盖可用车行道、步行路径断裂、对不存在道路臂的设施生成。 校验响应必须包含 `ruleId`、严重度、对象键、可读信息、受影响几何和建议动作。客户端以这些字段高亮对象和表单字段;禁止只返回 node/segment ID 或不可操作的 alert。 ## 数据流 ```text OSM + area config + direct-edit revision + optional reference GeoJSON -> junction topology / effective-arm classification -> geometry plan + junctionStructure + profile evaluation -> compiled layers, handles, diagnostics, reference comparison -> /api/state and preview/save responses -> isolated JunctionTools canvas + selectedObjectKey + parameter editor -> constraint patch -> preview -> validation -> revision-protected save ``` 结构摘要与诊断必须来自同一编译快照,避免画布显示一个形态、右栏使用另一个草稿状态。预览失败或 `blocking` 时仍返回足够的对象和几何引用,使用户能定位问题,但不得生成可保存的成功 revision。 ## GeoJSON 参考层 现有 `convertGeoJson()` 的 GCJ-02 到 WGS84 转换、`referenceFile` 和 `inspectReference()` 是唯一入口。参考比较对象记录:原始/转换后的坐标状态、来源文件、可见性、透明度、空间匹配置信度、中心偏移、边界框差、面积差、主方向差和未匹配原因。 匹配规则以相交、距离、包络和方向等空间证据为基础。原始 `properties.type` 只可作为调试计数,不能决定其属于路面、人行道、横道或导流岛。未来的建议工作流为“识别高置信度差异 -> 展示建议与依据 -> 用户接受为草稿”;参考数据不能直接覆写当前几何。 ## 兼容、渐进发布与回退 - 没有标准档、结构摘要或参考文件时,现有 JunctionTools 保持原有编辑能力和普通路口文案。 - Stage 1 的结构和诊断先只读旁路发布;每项硬阻塞在具有 fixture、明确来源和回归测试前不接入保存门禁。 - 参考层失败时仅关闭叠加和比较,不改变编译几何、草稿或保存行为。 - 每一类高级设施都以可关闭的对象分组接入;关闭后保留道路臂、角部、横道、停止线和信号的既有能力。 - 保存协议与 revision 冲突处理不变;任何新字段缺失时客户端要有兼容降级,不阻断旧区域配置。