feat(junction): add structure and standards contract

This commit is contained in:
que01 committed 2026-09-07 14:11:44 +08:00
1 parent 8d6f531377
commit 61cf276745
13 files changed
+843 -1

No files matched your search

+141
View File
@@ -0,0 +1,141 @@
'use strict';
const STANDARDS_PROFILE_SCHEMA = 'junction-standards-profile/v1';
function deepFreeze(value) {
if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
for (const nestedValue of Object.values(value)) deepFreeze(nestedValue);
return Object.freeze(value);
}
const CN_URBAN_DEFAULT_PROFILE = deepFreeze({
schema: STANDARDS_PROFILE_SCHEMA,
id: 'cn-urban-default',
label: '中国城市道路(项目默认)',
jurisdiction: '中国城市道路项目',
version: '2026.09',
sources: [
{
title: '城市道路工程设计规范',
edition: '项目采用版本待按地区确认',
clause: '道路宽度、交叉口与步行空间的项目适用条款',
},
{
title: '无障碍设计规范',
edition: '项目采用版本待按地区确认',
clause: '人行连续性与净空的项目适用条款',
},
],
applicability: {
roadClasses: [
'motorway',
'trunk',
'primary',
'secondary',
'tertiary',
'unclassified',
'residential',
'living_street',
'service',
],
shapeKinds: ['cross', 'offset-cross', 't-junction', 'multi-arm', 'unsupported'],
},
rules: [
{
id: 'effective-carriageway-width',
objectKinds: ['road-arm'],
recommended: { min: 6, unit: 'm', note: '项目推荐值,需结合车道数与道路等级调整' },
warning: { min: 4.8, unit: 'm' },
blocking: { min: 0, unit: 'm', invariant: 'finite' },
level: 'hard-invariant',
},
{
id: 'crossing-covers-carriageway',
objectKinds: ['crossing'],
level: 'hard-invariant',
blocking: { invariant: 'covers-effective-carriageway' },
},
{
id: 'stop-line-crossing-clearance',
objectKinds: ['stop-line', 'crossing'],
level: 'hard-invariant',
blocking: { invariant: 'approach-side-non-overlap' },
},
{
id: 'corner-radius-preserves-pedestrian-space',
objectKinds: ['corner', 'sidewalk-turn', 'crossing'],
recommended: { min: 4, max: 18, unit: 'm', note: '项目推荐范围,按转弯需求复核' },
warning: { min: 0.5, max: 30, unit: 'm' },
blocking: { invariant: 'preserves-pedestrian-clearance' },
level: 'hard-invariant',
},
{
id: 'pedestrian-continuity',
objectKinds: ['crossing', 'sidewalk-turn', 'island', 'median'],
level: 'hard-invariant',
blocking: { invariant: 'connected-path' },
},
{
id: 'junction-polygon-validity',
objectKinds: ['junction', 'corner', 'road-arm'],
level: 'hard-invariant',
blocking: { invariant: 'simple-non-self-intersecting-surfaces' },
},
],
projectOverrides: {},
});
function cloneProfile(profile) {
return JSON.parse(JSON.stringify(profile));
}
function validateStandardsProfile(profile) {
if (!profile || typeof profile !== 'object') throw new Error('Junction standards profile must be an object');
for (const field of ['id', 'label', 'jurisdiction', 'version'])
if (typeof profile[field] !== 'string' || profile[field].trim() === '')
throw new Error(`Junction standards profile.${field} must be a non-empty string`);
if (!Array.isArray(profile.sources) || profile.sources.length === 0)
throw new Error('Junction standards profile.sources must contain at least one source');
if (
!profile.applicability ||
!Array.isArray(profile.applicability.roadClasses) ||
!Array.isArray(profile.applicability.shapeKinds)
)
throw new Error('Junction standards profile.applicability must declare roadClasses and shapeKinds');
if (!Array.isArray(profile.rules)) throw new Error('Junction standards profile.rules must be an array');
const ids = new Set();
for (const rule of profile.rules) {
if (!rule || typeof rule.id !== 'string' || !rule.id.trim())
throw new Error('Every standards rule needs a non-empty id');
if (ids.has(rule.id)) throw new Error(`Duplicate junction standards rule: ${rule.id}`);
ids.add(rule.id);
if (!Array.isArray(rule.objectKinds) || rule.objectKinds.length === 0)
throw new Error(`Standards rule ${rule.id} must declare objectKinds`);
if (!['guidance', 'hard-invariant'].includes(rule.level))
throw new Error(`Invalid standards rule level: ${rule.id}`);
if (!rule.recommended && !rule.warning && !rule.blocking)
throw new Error(`Standards rule ${rule.id} must declare a range or invariant`);
}
return profile;
}
function evaluateRange(value, rule) {
if (!Number.isFinite(value)) return 'blocking';
if (rule.blocking?.min !== undefined && value < rule.blocking.min) return 'blocking';
if (rule.blocking?.max !== undefined && value > rule.blocking.max) return 'blocking';
if (rule.warning?.min !== undefined && value < rule.warning.min) return 'warning';
if (rule.warning?.max !== undefined && value > rule.warning.max) return 'warning';
if (rule.recommended?.min !== undefined && value < rule.recommended.min) return 'warning';
if (rule.recommended?.max !== undefined && value > rule.recommended.max) return 'warning';
return 'pass';
}
validateStandardsProfile(CN_URBAN_DEFAULT_PROFILE);
module.exports = {
STANDARDS_PROFILE_SCHEMA,
CN_URBAN_DEFAULT_PROFILE,
cloneProfile,
evaluateRange,
validateStandardsProfile,
};
+170
View File
@@ -0,0 +1,170 @@
'use strict';
const JUNCTION_STRUCTURE_SCHEMA = 'junction-structure/v1';
const SHAPE_KINDS = new Set(['cross', 'offset-cross', 't-junction', 'multi-arm', 'unsupported']);
const DIRECTIONALITY = new Set(['one-way', 'two-way', 'unknown']);
const OVERRIDE_MODES = new Set(['global', 'local']);
const FACILITY_KINDS = new Set(['crossing', 'stop-line', 'island', 'median', 'sidewalk-turn', 'signal']);
function objectKey(value, fallback) {
const key = String(value ?? '').trim();
if (key) return key;
if (fallback) return String(fallback);
throw new Error('Junction object key must be a non-empty string');
}
function readableLabel(value, fallback) {
const label = String(value ?? '').trim();
return label || fallback;
}
function finiteNumber(value, field, { integer = false, minimum = -Infinity } = {}) {
const number = Number(value);
if (!Number.isFinite(number) || (integer && !Number.isInteger(number)) || number < minimum)
throw new Error(`Junction ${field} must be a finite number${integer ? ' integer' : ''} >= ${minimum}`);
return number;
}
function overrideState(input = {}) {
const mode = input.mode || 'global';
if (!OVERRIDE_MODES.has(mode)) throw new Error(`Unsupported junction override mode: ${mode}`);
return {
mode,
...(input.inheritedFrom ? { inheritedFrom: String(input.inheritedFrom) } : {}),
resetToGlobalAvailable: mode === 'local' ? input.resetToGlobalAvailable !== false : false,
};
}
function normalizeRoadArm(input, index) {
const key = objectKey(input.key, `road-arm:${index + 1}`);
const label = readableLabel(input.label, `道路 ${index + 1}`);
const directionality = input.directionality || 'unknown';
if (!DIRECTIONALITY.has(directionality)) throw new Error(`Unsupported road arm directionality: ${directionality}`);
const carriageway = input.carriageway || {};
const normalized = {
key,
label,
heading: finiteNumber(input.heading ?? 0, 'arm heading'),
directionality,
carriageway: {
...(carriageway.laneCount === undefined
? {}
: { laneCount: finiteNumber(carriageway.laneCount, 'lane count', { integer: true, minimum: 0 }) }),
...(carriageway.effectiveWidthMeters === undefined
? {}
: { effectiveWidthMeters: finiteNumber(carriageway.effectiveWidthMeters, 'effective width', { minimum: 0 }) }),
},
...(input.pedestrian
? {
pedestrian: {
connected: Boolean(input.pedestrian.connected),
...(input.pedestrian.bicycleConnected === undefined
? {}
: { bicycleConnected: Boolean(input.pedestrian.bicycleConnected) }),
},
}
: {}),
geometryRef: objectKey(input.geometryRef, `junction:${key}`),
overrideState: overrideState(input.overrideState),
};
return normalized;
}
function normalizeCorner(input, index) {
const key = objectKey(input.key, `corner:${index + 1}`);
const fromArmKey = objectKey(input.fromArmKey || input.incomingRoadArmKey, `road-arm:${index + 1}`);
const toArmKey = objectKey(input.toArmKey || input.outgoingRoadArmKey, `road-arm:${index + 2}`);
if (fromArmKey === toArmKey) throw new Error(`Junction corner ${key} must connect two different road arms`);
return {
key,
label: readableLabel(input.label, `角部 ${index + 1}`),
fromArmKey,
toArmKey,
...(input.angleDegrees === undefined ? {} : { angleDegrees: finiteNumber(input.angleDegrees, 'corner angle') }),
...(input.radiusMeters === undefined
? {}
: { radiusMeters: finiteNumber(input.radiusMeters, 'corner radius', { minimum: 0 }) }),
geometryRef: objectKey(input.geometryRef, `junction:${key}`),
overrideState: overrideState(input.overrideState),
};
}
function normalizeFacility(input, index) {
const kind = String(input.kind || '').trim();
if (!FACILITY_KINDS.has(kind)) throw new Error(`Unsupported junction facility kind: ${kind || '<empty>'}`);
const key = objectKey(input.key, `${kind}:${index + 1}`);
return {
key,
kind,
label: readableLabel(input.label, kind === 'crossing' ? `人行横道 ${index + 1}` : `设施 ${index + 1}`),
...(input.armKey ? { armKey: String(input.armKey) } : {}),
...(input.cornerKey ? { cornerKey: String(input.cornerKey) } : {}),
...(input.relatedFacilityKey ? { relatedFacilityKey: String(input.relatedFacilityKey) } : {}),
...(input.direction === undefined ? {} : { direction: finiteNumber(input.direction, 'facility direction') }),
geometryRef: objectKey(input.geometryRef, `junction:${key}`),
editable: input.editable !== false,
overrideState: overrideState(input.overrideState),
};
}
function assertUniqueKeys(items, objectKind) {
const keys = new Set();
for (const item of items) {
if (keys.has(item.key)) throw new Error(`Duplicate junction ${objectKind} key: ${item.key}`);
keys.add(item.key);
}
return keys;
}
function buildJunctionStructure(input = {}) {
const shape = input.shape || {};
const kind = String(shape.kind || 'unsupported');
if (!SHAPE_KINDS.has(kind)) throw new Error(`Unsupported junction shape kind: ${kind}`);
const arms = (input.arms || []).map(normalizeRoadArm);
const armKeys = assertUniqueKeys(arms, 'road arm');
const corners = (input.corners || []).map(normalizeCorner);
const cornerKeys = assertUniqueKeys(corners, 'corner');
for (const corner of corners)
if (!armKeys.has(corner.fromArmKey) || !armKeys.has(corner.toArmKey))
throw new Error(`Junction corner ${corner.key} references an unknown road arm`);
const facilities = (input.facilities || []).map(normalizeFacility);
const facilityKeys = assertUniqueKeys(facilities, 'facility');
for (const facility of facilities) {
if (facility.armKey && !armKeys.has(facility.armKey))
throw new Error(`Junction facility ${facility.key} references an unknown road arm`);
if (facility.cornerKey && !cornerKeys.has(facility.cornerKey))
throw new Error(`Junction facility ${facility.key} references an unknown corner`);
if (facility.relatedFacilityKey && !facilityKeys.has(facility.relatedFacilityKey))
throw new Error(`Junction facility ${facility.key} references an unknown facility`);
}
const effectiveArmCount = shape.effectiveArmCount ?? arms.length;
finiteNumber(effectiveArmCount, 'effective arm count', { integer: true, minimum: 0 });
if (effectiveArmCount !== arms.length)
throw new Error('Junction effective arm count must match the supplied road arms');
return {
schema: JUNCTION_STRUCTURE_SCHEMA,
junctionKey: objectKey(input.junctionKey, 'junction:unknown'),
label: readableLabel(input.label, '未命名路口'),
shape: {
kind,
label: readableLabel(shape.label, '暂未识别的路口形态'),
effectiveArmCount,
throughPairCount: finiteNumber(shape.throughPairCount ?? 0, 'through pair count', { integer: true, minimum: 0 }),
},
...(input.center ? { center: [...input.center] } : {}),
...(input.effectiveRadiusMeters === undefined
? {}
: { effectiveRadiusMeters: finiteNumber(input.effectiveRadiusMeters, 'effective radius', { minimum: 0 }) }),
arms,
corners,
facilities,
...(input.standards ? { standards: input.standards } : {}),
...(input.reference ? { reference: input.reference } : {}),
};
}
module.exports = {
JUNCTION_STRUCTURE_SCHEMA,
SHAPE_KINDS,
buildJunctionStructure,
};
+2
View File
@@ -5,6 +5,8 @@ module.exports = {
gaodeReference: require('./reference/gaode'),
turnLaneArrows: require('./compile/turn-lane-arrows'),
complexJunction: require('./compile/complex-junction'),
junctionStructure: require('./compile/junction-structure'),
junctionStandards: require('./compile/junction-standards'),
osm: require('./osm'),
trafficSignals: require('./traffic-signals'),
nativeTrafficSignals: require('./native-traffic-signals'),