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

8.3 KiB

JunctionTools 行业规范化设计

边界与职责

JunctionTools 是编译结果的局部编辑工作区,不是另一套地图或另一套几何引擎。它只显示当前路口及关联道路,所有几何推导和拓扑判断仍由编译器完成。

层 责任 不负责
编译层 识别有效道路臂与形态、生成核心/角部/设施几何、构造结构摘要、执行几何与规范校验 组件状态、选择样式、表单布局
服务/API 层 以同一 revision 提供结构、诊断、手柄、局部预览与保存;返回稳定对象键和可读标签 由客户端重新计算拓扑或范围
客户端 局部画布、对象选择、表单、全局/局部覆盖、诊断解释和参考层呈现 根据节点数分类、猜测引用 GeoJSON type 语义、绕过校验保存

现有 direct-edit revision、草稿、预览、放弃、保存和冲突保护是底座。新结构只能旁路扩展这些协议,不能另建一条无版本保护的保存路径。

规范化对象合约

每次状态/预览响应在现有路口描述之上提供只读 junctionStructure。其对象键内部稳定但不作为默认 UI 标题;所有对象均附带 label、geometryRef、editable 和 validationRefs。

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 字没有第四角的局部圆角;单行道路没有假想的对向车道宽度。

工作区信息架构

┌ 标题(可读路口名)· 实际形态 · 中国城市道路 · 参考模式 · 草稿状态 ┐
├ 道路臂 / 角部 / 设施 ┬ 当前路口局部画布                              ┬ 参数与诊断 ┤
│ 可读名称、类型、状态   │ 道路标签、方向、选区、手柄、参考叠加、诊断定位 │ 对象名、作用域、字段、恢复全局、规则 │
├──────────────────────────────────────────────────────────────────────────┤
│ 撤销 · 重做 · 重置当前对象 · 放弃草稿 · 应用预览 · 保存                  │
└──────────────────────────────────────────────────────────────────────────┘
  • 顶栏只保留决策性状态;内部 node/cluster ID 可以在调试信息中出现,绝不占主标题。
  • 左栏以“道路臂、角部、过街与控制设施”分组,条目使用道路名;无法取得名称时使用稳定的“道路 1、道路 2”并在画布同色标注。
  • 中央画布是隔离的局部范围。对象呈现必须支持 default、hover、selected、warning、blocking 和 disabled,并能显示代表同一对象的多个几何片段。
  • 选择来源无差别:列表点击、地图点击、诊断“定位”或手柄聚焦都写入唯一 selectedObjectKey。右栏订阅该键,不根据最近修改的字段猜测上下文。
  • 参数输入使用支持单位、步进上下键、范围和无效态的现有成熟组件。拖动产生的预览与表单使用同一约束值及同一正方向;如果没有安全的手柄,保留表单但明确原因。

标准档与校验合约

标准档是版本化数据,不是散落在组件中的魔法常量。

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<string, unknown>;
};

首个档案 cn-urban-default 记录来源、适用道路等级、设计速度和项目覆盖项。内容按三种层次执行:

  1. 设计建议:推荐范围和警告范围,允许保存,例如舒适圆角、优选横道尺度。
  2. 规范下限/项目约束:由配置给出阻塞范围,例如适用车道宽度、有效步行带和停止线净距。
  3. 几何不变量:不依赖地域数值,始终阻塞,例如自交、反向停止线、横道未覆盖可用车行道、步行路径断裂、对不存在道路臂的设施生成。

校验响应必须包含 ruleId、严重度、对象键、可读信息、受影响几何和建议动作。客户端以这些字段高亮对象和表单字段;禁止只返回 node/segment ID 或不可操作的 alert。

数据流

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 冲突处理不变;任何新字段缺失时客户端要有兼容降级,不阻断旧区域配置。