From 92ab2edd96c2135e330631357115ed09a84e0cbd Mon Sep 17 00:00:00 2001
From: que01
Date: Mon, 7 Sep 2026 16:45:37 +0800
Subject: [PATCH] feat(junction): add reference geometry comparison layer
---
.../check.jsonl | 2 ++
.../design.md | 5 ++++
.../implement.jsonl | 3 +++
.../implement.md | 6 +++++
.../prd.md | 18 +++++++++++++
.../task.json | 26 +++++++++++++++++++
workbench/client/src/App.tsx | 23 +++++++++++++---
workbench/client/src/components/MapCanvas.tsx | 5 ++++
.../client/src/junction/JunctionWorkspace.tsx | 6 +++++
workbench/client/src/map/layers.ts | 11 ++++++++
workbench/client/src/types/state.ts | 7 ++++-
11 files changed, 107 insertions(+), 5 deletions(-)
create mode 100644 .trellis/tasks/09-07-junctiontools-stage4-reference-comparison/check.jsonl
create mode 100644 .trellis/tasks/09-07-junctiontools-stage4-reference-comparison/design.md
create mode 100644 .trellis/tasks/09-07-junctiontools-stage4-reference-comparison/implement.jsonl
create mode 100644 .trellis/tasks/09-07-junctiontools-stage4-reference-comparison/implement.md
create mode 100644 .trellis/tasks/09-07-junctiontools-stage4-reference-comparison/prd.md
create mode 100644 .trellis/tasks/09-07-junctiontools-stage4-reference-comparison/task.json
diff --git a/.trellis/tasks/09-07-junctiontools-stage4-reference-comparison/check.jsonl b/.trellis/tasks/09-07-junctiontools-stage4-reference-comparison/check.jsonl
new file mode 100644
index 0000000..c1a8f92
--- /dev/null
+++ b/.trellis/tasks/09-07-junctiontools-stage4-reference-comparison/check.jsonl
@@ -0,0 +1,2 @@
+{"file":".trellis/spec/frontend/quality-guidelines.md","reason":"Run frontend quality gates."}
+{"file":".trellis/spec/backend/direct-edit-api.md","reason":"Verify reference data does not alter save/preview contracts."}
diff --git a/.trellis/tasks/09-07-junctiontools-stage4-reference-comparison/design.md b/.trellis/tasks/09-07-junctiontools-stage4-reference-comparison/design.md
new file mode 100644
index 0000000..07028ac
--- /dev/null
+++ b/.trellis/tasks/09-07-junctiontools-stage4-reference-comparison/design.md
@@ -0,0 +1,5 @@
+# 技术设计
+
+服务端继续在启动时调用 `readJunctionReference()`,将转换后的 GeoJSON 作为可选只读字段返回;不把参考 `properties.type` 投影为业务对象。客户端在 `MapCanvas` 图层工厂中新增独立 reference layer,使用 `state.junctionReference.converted` 更新,显示状态由 App 本地开关控制。
+
+比较指标优先复用 `comparison.json` 和 `junctionReference` 已有字段;缺失时显示“暂无匹配”,不执行客户端空间推断。参考层只参与渲染,不进入 `EditSession`、preview 或 save payload。
diff --git a/.trellis/tasks/09-07-junctiontools-stage4-reference-comparison/implement.jsonl b/.trellis/tasks/09-07-junctiontools-stage4-reference-comparison/implement.jsonl
new file mode 100644
index 0000000..a09dbb2
--- /dev/null
+++ b/.trellis/tasks/09-07-junctiontools-stage4-reference-comparison/implement.jsonl
@@ -0,0 +1,3 @@
+{"file":".trellis/spec/frontend/quality-guidelines.md","reason":"Follow frontend component and validation conventions."}
+{"file":".trellis/spec/frontend/direct-edit-client.md","reason":"Keep reference rendering outside edit baseline and preview ownership."}
+{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"Trace reference data without changing native output."}
diff --git a/.trellis/tasks/09-07-junctiontools-stage4-reference-comparison/implement.md b/.trellis/tasks/09-07-junctiontools-stage4-reference-comparison/implement.md
new file mode 100644
index 0000000..d7ed7f1
--- /dev/null
+++ b/.trellis/tasks/09-07-junctiontools-stage4-reference-comparison/implement.md
@@ -0,0 +1,6 @@
+# 实施清单
+
+1. 扩展客户端图层类型和更新逻辑,接入参考 GeoJSON。
+2. 在 App 增加参考层开关、透明度和状态摘要。
+3. 增加参考层转换/缺失兼容测试或类型覆盖。
+4. 运行完整质量门禁并归档阶段任务。
diff --git a/.trellis/tasks/09-07-junctiontools-stage4-reference-comparison/prd.md b/.trellis/tasks/09-07-junctiontools-stage4-reference-comparison/prd.md
new file mode 100644
index 0000000..0db0078
--- /dev/null
+++ b/.trellis/tasks/09-07-junctiontools-stage4-reference-comparison/prd.md
@@ -0,0 +1,18 @@
+# JunctionTools Stage 4:参考几何对照
+
+## 目标
+
+将已有参考 GeoJSON 以只读叠加层接入工作台,展示原始/转换状态和空间比较指标,同时保证参考数据不会影响 native 编译、草稿或保存。
+
+## 范围
+
+- 复用 `convertGeoJson` 和现有 `junctionReference` 数据流。
+- 客户端提供参考层显示开关和透明度控制。
+- 状态提供来源、坐标系、转换状态及比较指标;关闭、缺失或匹配失败时安全降级。
+
+## 验收标准
+
+1. 参考层可显示/隐藏并调整透明度,不改变 native 图层和保存请求。
+2. UI 显示参考来源、GCJ-02 到 WGS84 转换状态和 bbox/中心差异(若已有比较结果)。
+3. 无参考文件、转换失败或无匹配时 native 输出和现有编辑流程保持不变。
+4. 客户端类型检查、单测、构建、格式检查和后端回归通过。
diff --git a/.trellis/tasks/09-07-junctiontools-stage4-reference-comparison/task.json b/.trellis/tasks/09-07-junctiontools-stage4-reference-comparison/task.json
new file mode 100644
index 0000000..00e7521
--- /dev/null
+++ b/.trellis/tasks/09-07-junctiontools-stage4-reference-comparison/task.json
@@ -0,0 +1,26 @@
+{
+ "id": "junctiontools-stage4-reference-comparison",
+ "name": "junctiontools-stage4-reference-comparison",
+ "title": "JunctionTools Stage 4 参考几何对照",
+ "description": "",
+ "status": "in_progress",
+ "dev_type": null,
+ "scope": null,
+ "package": null,
+ "priority": "P2",
+ "creator": "dingkang",
+ "assignee": "dingkang",
+ "createdAt": "2026-09-07",
+ "completedAt": null,
+ "branch": null,
+ "base_branch": "main",
+ "worktree_path": null,
+ "commit": null,
+ "pr_url": null,
+ "subtasks": [],
+ "children": [],
+ "parent": null,
+ "relatedFiles": [],
+ "notes": "",
+ "meta": {}
+}
\ No newline at end of file
diff --git a/workbench/client/src/App.tsx b/workbench/client/src/App.tsx
index ec17dd7..70e1a27 100644
--- a/workbench/client/src/App.tsx
+++ b/workbench/client/src/App.tsx
@@ -67,6 +67,7 @@ import {
const layerLabels: Array<[LayerName, string]> = [
['osm', '方向道路参考线'],
+ ['reference', '参考几何叠加'],
['native', '自研道路与路口面'],
['sidewalks', '路缘与步行带'],
['lanes', '车道与转向路径'],
@@ -78,10 +79,9 @@ const layerLabels: Array<[LayerName, string]> = [
['signals', '红绿灯设施'],
['junctionHotspots', '路口编辑热区'],
];
-const defaultLayers = Object.fromEntries(layerLabels.map(([key]) => [key, key !== 'edgeLines'])) as Record<
- LayerName,
- boolean
->;
+const defaultLayers = Object.fromEntries(
+ layerLabels.map(([key]) => [key, key !== 'edgeLines' && key !== 'reference']),
+) as Record;
const direction = (road: Road) => (road.direction === 'forward' ? '沿 OSM 方向' : '逆 OSM 方向');
const label = (road: Road) => road.tags.name || `${road.highway}(OSM ${road.osmWayIds.join(', ')})`;
const laneIndex = (id: string) => Number(id.split(':').at(-1));
@@ -89,6 +89,7 @@ function App() {
const [state, setState] = useState();
const [selected, setSelected] = useState(null);
const [layers, setLayers] = useState(defaultLayers);
+ const [referenceOpacity, setReferenceOpacity] = useState(0.55);
const [scene, setScene] = useState(false);
const [junctionHotspots, setJunctionHotspots] = useState(true);
const [status, setStatus] = useState('正在加载工作台...');
@@ -1003,6 +1004,19 @@ function App() {
);
})}
+ {state.junctionReference ? (
+
+ ) : null}
@@ -1051,6 +1065,7 @@ function App() {
scene={scene}
junctionHotspots={junctionHotspots}
junctionNodeMarkers={junctionNodeMarkers}
+ referenceOpacity={referenceOpacity}
onJunctionHotspot={(ref: JunctionRef, _coordinate, descriptor) => {
openJunction(ref);
const approachRoad = descriptor.approachRoadIds
diff --git a/workbench/client/src/components/MapCanvas.tsx b/workbench/client/src/components/MapCanvas.tsx
index cdac837..4e5c6ef 100644
--- a/workbench/client/src/components/MapCanvas.tsx
+++ b/workbench/client/src/components/MapCanvas.tsx
@@ -78,6 +78,7 @@ interface Props {
junctionHotspots?: boolean;
onJunctionHotspot?: (ref: JunctionRef, coordinate: Coordinate, descriptor: JunctionDescriptor) => void;
junctionNodeMarkers?: Array<{ coordinate: Coordinate; label: string; selected: boolean }>;
+ referenceOpacity?: number;
}
export function MapCanvas({
state,
@@ -114,6 +115,7 @@ export function MapCanvas({
junctionHotspots = true,
onJunctionHotspot,
junctionNodeMarkers = [],
+ referenceOpacity = 0.55,
}: Props) {
const target = useRef(null);
const mapRef = useRef
+ {state?.junctionReference ? (
+
+ 参考层:{state.junctionReference.coordinateSystem || 'GCJ-02'} → WGS84 ·{' '}
+ {state.junctionReference.source || '已加载参考文件'}
+
+ ) : null}
- 道路臂
-
diff --git a/workbench/client/src/map/layers.ts b/workbench/client/src/map/layers.ts
index d1f0261..7880649 100644
--- a/workbench/client/src/map/layers.ts
+++ b/workbench/client/src/map/layers.ts
@@ -20,6 +20,7 @@ export type LayerName =
| 'native'
| 'sidewalks'
| 'osm'
+ | 'reference'
| 'lanes'
| 'edgeLines'
| 'directionArrows'
@@ -66,6 +67,15 @@ export function createLayers(
: undefined,
}),
}),
+ reference: new VectorLayer({
+ source: source(),
+ visible: false,
+ opacity: 0.55,
+ style: new Style({
+ fill: new Fill({ color: '#7c3aed22' }),
+ stroke: new Stroke({ color: '#7c3aed', width: 2, lineDash: [6, 4] }),
+ }),
+ }),
lanes: new VectorLayer({
source: source(),
style: new Style({ stroke: new Stroke({ color: '#f5f6ee', width: 1.5, lineDash: [5, 4] }) }),
@@ -224,6 +234,7 @@ export function updateLayers(
);
put('osm', { type: 'FeatureCollection', features: [] });
get('osm').addFeatures(roads);
+ put('reference', state.junctionReference?.converted);
put('lanes', state.layers.laneCenterlines);
put('edgeLines', state.layers.edgeLines);
put('directionArrows', state.layers.directionArrows);
diff --git a/workbench/client/src/types/state.ts b/workbench/client/src/types/state.ts
index 72e7db6..e6aaa43 100644
--- a/workbench/client/src/types/state.ts
+++ b/workbench/client/src/types/state.ts
@@ -121,7 +121,12 @@ export interface WorkbenchState {
trafficRuntime: { signals: unknown[] };
comparison: Record;
layers: Record;
- junctionReference?: { converted: GeoJson };
+ junctionReference?: {
+ source?: string;
+ coordinateSystem?: string;
+ converted: GeoJson;
+ comparison?: Record;
+ };
debug?: {
junctionCandidates: JunctionCandidate[];
junctionClusters?: JunctionClusterConfig[];