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

138 lines
8.3 KiB
Markdown

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