chore(task): archive completed road editor workflows
This commit is contained in:
1 parent
39e338668b
commit
d61c86ed2c
26 files changed
+6
-6
No files matched your search
@@ -0,0 +1,5 @@
|
||||
{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "检查跨层数据流是否一致:约束 kind、manifest 字段、API 载荷、客户端类型不得各写一套"}
|
||||
{"file": ".trellis/spec/guides/code-reuse-thinking-guide.md", "reason": "检查是否出现第二套米制换算、第二套 ID 校验或重复的 overrides 应用逻辑"}
|
||||
{"file": ".trellis/tasks/08-26-direct-manipulation-road-editor/research/joint-solver.md", "reason": "逐条核对约束不变量:最小车道宽、外缘不交叉、路口连续、connector 包含性"}
|
||||
{"file": ".trellis/tasks/08-26-direct-manipulation-road-editor/research/junction-tools.md", "reason": "核对编辑所有权与会话边界未被越过:道路 handle 不得进入 junction reserve"}
|
||||
{"file": ".trellis/tasks/08-26-direct-manipulation-road-editor/research/current-system.md", "reason": "核对 v1 overrides、feature 回链字段与既有 API 行为未被破坏"}
|
||||
@@ -0,0 +1,272 @@
|
||||
# 直接操纵道路编辑设计
|
||||
|
||||
> 本文是约束模型、合约与边界的唯一权威定义。`research/` 下的文档是探索记录;如与本文冲突,以本文为准。
|
||||
|
||||
## 架构边界
|
||||
|
||||
OSM、area config 快照和现有 v1 overrides 仍是道路模型的基线。`native-road-edits/v2` 记录 OSM 语义锚点上的约束与操作,不保存最终 GeoJSON。
|
||||
|
||||
```text
|
||||
OSM + area config snapshot + v1 overrides + v2 direct edits
|
||||
-> compileRoadModel
|
||||
-> applyRoadOverrides
|
||||
-> resolveDirectEditConstraints
|
||||
-> editable profiles + junction plans + handle manifest
|
||||
-> compileGeometry -> GeoJSON / diagnostics / layers
|
||||
```
|
||||
|
||||
预览与正式编译共用 `resolveDirectEditConstraints` 与 `compileGeometry`;浏览器不实现第二套道路几何算法。
|
||||
|
||||
## 约束模型
|
||||
|
||||
锚点类型(约束挂在哪里)与约束 kind(约束什么)是两个维度。此前 `research/data-model-options.md` 与本文混用二者,导致两套命名冲突,此处统一。
|
||||
|
||||
```ts
|
||||
type Side = 'left' | 'right'
|
||||
|
||||
type SemanticAnchor =
|
||||
| { type: 'road-station'; roadId: string; station: number; side?: Side }
|
||||
| { type: 'road-interval'; roadId: string; startStation: number; endStation: number; side?: Side }
|
||||
| { type: 'junction-approach'; nodeId: string; segmentId: string; side?: Side }
|
||||
| { type: 'junction-corner'; nodeId: string; incomingRoadId: string; outgoingRoadId: string }
|
||||
|
||||
type RoadConstraintKind =
|
||||
| 'road-edge-offset'
|
||||
| 'road-sidewalk-width'
|
||||
| 'road-lane-divider'
|
||||
| 'junction-approach-width'
|
||||
| 'junction-cutback'
|
||||
| 'junction-corner-radius'
|
||||
| 'junction-crosswalk-inset'
|
||||
| 'junction-crosswalk-size'
|
||||
| 'junction-stop-line-offset'
|
||||
```
|
||||
|
||||
| kind | 锚点 | value | 单位与含义 | 所有者 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `road-edge-offset` | `road-interval` | `{ offsetMeters, transition }` | 米,相对基线外缘的法向偏移 | 主地图 |
|
||||
| `road-sidewalk-width` | `road-interval` | `{ widthMeters, transition }` | 米,`0` 表示关闭步行带 | 主地图 |
|
||||
| `road-lane-divider` | `road-interval` | `{ boundaryIndex, offsetMeters, transition }` | 米,相对中心线的带符号横向偏移(左负右正) | 主地图 |
|
||||
| `junction-approach-width` | `junction-approach` | `{ widthMeters }` | 米 | JunctionTools |
|
||||
| `junction-cutback` | `junction-approach` | `{ cutbackMeters }` | 米 | JunctionTools |
|
||||
| `junction-corner-radius` | `junction-corner` | `{ radiusMeters }` | 米 | JunctionTools |
|
||||
| `junction-crosswalk-inset` | `junction-approach` | `{ insetMeters }` | 米,斑马线距路口边界的退让 | 主地图 / JunctionTools |
|
||||
| `junction-crosswalk-size` | `junction-approach` | `{ depthMeters, stripeCount }` | 米 + 整数条带数 | 主地图 |
|
||||
| `junction-stop-line-offset` | `junction-approach` | `{ offsetMeters }` | 米,停止线沿进口后退的距离 | 主地图 / JunctionTools |
|
||||
|
||||
前 6 个 kind 对应 PRD 首期范围(外缘、步行带、车道分隔 + 进口、cutback、角部)。
|
||||
|
||||
`junction-crosswalk-inset` 与 `junction-stop-line-offset` 于 2026-08-28 追加,是「更多元素可直接操纵」方向的第一类扩展:控制标线的**位置**
|
||||
成为可编辑参数。它们不改变路口形状,只移动标线,因此不触发路口边界重算。
|
||||
放置是否成立的判据(`STOP_LINE_MAX_APPROACH_DISTANCE_METERS` 等)不在此范围内。
|
||||
|
||||
`junction-crosswalk-size` 于 2026-08-31 追加,是第一个改变标线**自身尺寸**而非位置的 kind。
|
||||
横跨道路的跨度不是存储值,而是 `stripeCount × pitch` 派生;pitch 固定 0.9m 不可编辑,
|
||||
因为条带宽与间隙在现实中是标准化的,而它横跨的道路不是。加宽靠增加条带数,
|
||||
所以跨度是**量化**的。同批修掉了「跨度恒为 4.95m,与路宽无关」的缺陷:
|
||||
无约束时条带数由整段车行道宽度推导。
|
||||
|
||||
新增 kind 的前提:**几何阶段必须已经消费它**。本项目曾为 `profile.interval` 交付过
|
||||
一个拖动无效果的手柄(见 `08-26-direct-edit-map-editor/research/interval-not-applied.md`),
|
||||
所以扩展 kind 时先证明 `compileGeometry()` 读取该参数,再画任何手柄。
|
||||
|
||||
`transition: 'smoothstep' | 'linear'`,默认 `smoothstep`,作用于 interval 两端回归基线的过渡段。
|
||||
|
||||
`boundaryIndex` 从左外缘起 1-based,有效范围 `1..laneCount-1`。重放时若车道数变化导致越界,该约束转 `stale`,不做近似映射。
|
||||
|
||||
`station` 是相对道路中心线的归一化弧长 `0..1`,不是绝对经纬度或数组下标。保存时同时写 `anchorSnapshot`(当时坐标、切线方位、道路长度、相邻 OSM node ID)作为重定位与冲突检测证据。
|
||||
|
||||
道路横断面拖拽默认写 `road-interval`:拖拽位置为区间中心,求解器按道路长度与两端 junction reserve 推导初始 `startStation` / `endStation`;用户用范围手柄只更新该区间,不存储鼠标轨迹。
|
||||
|
||||
## Handle manifest
|
||||
|
||||
服务端从同一语义模型生成手柄清单,客户端不自行推导手柄位置或可拖方向。
|
||||
|
||||
```ts
|
||||
interface HandleManifest {
|
||||
schema: 'road-edit-handles/v1'
|
||||
revisionId: string
|
||||
previewSeq: number
|
||||
handles: EditHandle[]
|
||||
reserves: JunctionReserve[]
|
||||
}
|
||||
|
||||
interface EditHandle {
|
||||
handleId: string
|
||||
kind: RoadConstraintKind
|
||||
anchor: SemanticAnchor
|
||||
position: [number, number] // EPSG:4326
|
||||
axisAzimuth: number // 允许拖拽的方向,度,相对真北
|
||||
value: { current: number; min: number; max: number; unit: 'meter' }
|
||||
constraintId?: string // 已有约束回链
|
||||
affects: string[] // 受影响派生 feature 的 native_id
|
||||
editable: boolean
|
||||
disabledReason?: string
|
||||
}
|
||||
|
||||
interface JunctionReserve {
|
||||
nodeId: string
|
||||
roadId: string
|
||||
fromStation: number
|
||||
toStation: number
|
||||
}
|
||||
```
|
||||
|
||||
手柄 feature 的 properties 只携带 `handleId`,语义通过 manifest 反查。`reserves` 是主地图禁入区:落在其中的道路手柄必须 `editable: false` 且给出 `disabledReason`,引导用户进入 `JunctionTools`。`affects` 用于拖拽时高亮将被同步改变的对象,满足 PRD 第 2 条。
|
||||
|
||||
## 坐标与单位分层
|
||||
|
||||
持久化层只有米和归一化 station,没有像素、没有度。
|
||||
|
||||
| 层 | 坐标 / 单位 | 规则 |
|
||||
| --- | --- | --- |
|
||||
| 持久化约束 | 米 + station `0..1` | 禁止写入经纬度或像素 |
|
||||
| 服务端求解 | 局部米制框架 | 复用 `src/geometry/lane-geometry.js` 的 `metersAt()`、`haversineMeters()`、`projectedDistanceAlong()`、`lateralOffsetFrom()`,不新增第二套换算 |
|
||||
| 传输 | EPSG:4326 + 方位角 | manifest 与预览 GeoJSON 一律 4326 |
|
||||
| 客户端渲染 | EPSG:3857 | 沿用 `workbench/client/src/map/layers.ts` 现有 `dataProjection: 'EPSG:4326'` / `featureProjection: 'EPSG:3857'` |
|
||||
|
||||
客户端把指针位移换成米时必须先转回 4326 再用球面距离,禁止拿 3857 坐标差当米:3857 在纬度 φ 处有 `1/cos φ` 放大,直接相减会让同一次拖拽在不同纬度得到不同结果。
|
||||
|
||||
## 预览时序与延迟预算
|
||||
|
||||
```text
|
||||
pointer down -> 读 handle 的 anchor,建 draft operation
|
||||
pointer move -> 立即更新客户端 ghost + 递增 previewSeq 的防抖请求
|
||||
pointer up -> 强制发一次非防抖的最终请求
|
||||
```
|
||||
|
||||
- 防抖:拖拽中 80ms trailing;`pointerup` 不防抖。
|
||||
- 时序:每个会话的 `previewSeq` 单调递增,响应回显它。客户端丢弃 `previewSeq` 小于已应用最大值的响应,并在发新请求时用 `AbortController` 取消在途请求。乱序响应绝不允许覆盖较新的预览。
|
||||
- 延迟预算:单道路 / 单路口局部求解 p95 ≤ 300ms。超预算仍返回结果但标 `degraded: true`,客户端保留 ghost 与待定状态,不做几何闪烁。
|
||||
- 无效草稿返回 `diagnostics` 且不替换最后一个有效预览。
|
||||
|
||||
## 文档、活动副本与 revision
|
||||
|
||||
活动工作副本包含 v1 overrides、v2 edits、area config 快照和信号数据。导入 OSM 自动创建不可变基线 revision;用户命名检查点时冻结所有输入副本、hash、compiler identity 和可选产物。普通保存与预览只更新活动副本。
|
||||
|
||||
```ts
|
||||
interface RoadEditDocument {
|
||||
schema: 'native-road-edits/v2'
|
||||
documentVersion: number
|
||||
base: { osmSha256: string; areaConfigSha256: string; compilerGeometryVersion: string }
|
||||
constraints: RoadConstraint[]
|
||||
operations: RoadEditOperation[]
|
||||
}
|
||||
|
||||
interface RoadConstraint {
|
||||
id: string
|
||||
kind: RoadConstraintKind
|
||||
anchor: SemanticAnchor
|
||||
anchorSnapshot: AnchorSnapshot
|
||||
value: unknown
|
||||
enabled: boolean
|
||||
status: ConstraintStatus
|
||||
provenance: { operationId: string; createdAt: string; author?: string }
|
||||
}
|
||||
|
||||
type ConstraintStatus = 'exact' | 'recheck' | 'pending' | 'conflicted' | 'stale'
|
||||
```
|
||||
|
||||
| status | 含义 | 是否参与求解 |
|
||||
| --- | --- | --- |
|
||||
| `exact` | 锚点 ID 精确匹配 | 是 |
|
||||
| `recheck` | 锚点匹配,但编译器几何版本已变 | 是,且需用户显式确认 |
|
||||
| `pending` | 需按 snapshot 重定位的候选匹配 | 否,等用户确认 |
|
||||
| `conflicted` | 候选不唯一或偏差超阈值 | 否 |
|
||||
| `stale` | 锚点已不存在,或参数越界 | 否 |
|
||||
|
||||
重导入先按 `roadId` / `segmentId` / `nodeId` 精确匹配;失败才用 `anchorSnapshot` 的 OSM node、距离与切线找候选。绝不静默模糊应用。
|
||||
|
||||
## 存储布局与迁移
|
||||
|
||||
现状是每次导入创建一个 `workbench-data/import-<id>/` 目录(`workbench/server.js` 用 `fs.mkdtempSync`),内含 `source.osm`、`native-road-overrides.json`、`native-traffic-signals.json`、`outputs/`。新结构在该目录内扩展,不改动既有文件语义:
|
||||
|
||||
```text
|
||||
workbench-data/import-<id>/
|
||||
source.osm 保留,v1 路径兼容
|
||||
native-road-overrides.json 保留,仍是 v1 覆盖的权威文件
|
||||
native-traffic-signals.json 保留
|
||||
outputs/ 保留
|
||||
osm/<sha256>.osm 内容寻址的 OSM 副本,多 revision 共享
|
||||
active/
|
||||
native-road-edits.json v2 直接编辑文档
|
||||
area-config.snapshot.json 区域配置快照(含 nativeRoad.junctionTemplates)
|
||||
state.json documentVersion、activeRevisionId
|
||||
revisions/
|
||||
rev-0001/manifest.json 导入基线
|
||||
rev-0002/manifest.json 命名检查点
|
||||
```
|
||||
|
||||
迁移是惰性的:新版本首次打开既有 import 目录时创建 `active/`,并把当前 `source.osm` + overrides + signals + area config 冻结为 `rev-0001`。不移动、不重写任何既有文件,旧版本仍能读原路径。
|
||||
|
||||
留存:revision 永不自动删除。OSM 内容寻址后,重复导入同一文件不产生副本。`outputs/` 缓存可显式清理,清理不影响可复现性——复现来源始终是输入文档加 compiler identity。
|
||||
|
||||
## area config 所有权
|
||||
|
||||
`nativeRoad.junctionTemplates` 目前住在项目级区域配置文件里,`/api/junction-clusters` 直接改写它(`workbench/server.js:224-243`),旧客户端还提示用户手工复制回配置文件。这让 revision 不可复现:同一份 OSM + overrides 在不同 area config 下编译结果不同。
|
||||
|
||||
规则:
|
||||
|
||||
- 每个 revision 与活动副本各持有一份 `area-config.snapshot.json`。
|
||||
- 编译与预览只读快照,不在编译期读外部配置文件。
|
||||
- `/api/junction-clusters` 改为写活动副本快照,响应仍返回可复制到项目配置的片段,保留现有导出提示的价值。
|
||||
- `RoadEditDocument.base.areaConfigSha256` 指向快照。
|
||||
- cluster 的高级编辑延后,但快照合约现在建立,避免最小 JunctionTools 落地后返工。
|
||||
|
||||
## 编译器几何版本变更
|
||||
|
||||
`base.compilerGeometryVersion` 与当前不一致时,约束仍按精确锚点重放,但全部标 `recheck` 并要求一次显式"确认重放";不自动改值,也不自动判失效。rebase 响应必须给出各 status 的计数与逐条明细。
|
||||
|
||||
## 编辑所有权
|
||||
|
||||
主地图 Road editor 只编辑两个 junction reserve 之间的道路内部 interval。reserve 内的 approach width、transition、cutback 和 corner 由 `JunctionTools` 独占。同一进口上 `junction-approach-width` 显式约束优先于道路 profile,求解器负责边界连续。
|
||||
|
||||
`JunctionTools` 是独立的单 `JunctionRef` 页面(`{type:'node'|'cluster', id}`):主地图只负责发现和导航,页面自身负责路口自动居中、完整可视化画布、几何与已有设施编辑。页面不得被参数面板遮挡;路口面、进口、车道/connector、斑马线、停止线和信号灯都必须保持可见,编辑控件覆盖在同一画布上。拖拽立即 ghost,服务端返回完整局部派生图层;"应用到工作区"把有效草稿合并为活动副本的未保存约束,"保存"才持久化,"取消"回到进入前状态。切换相邻路口前必须应用或取消。
|
||||
|
||||
## 不变量
|
||||
|
||||
- 基线 OSM topology 与 centerline 不由直接编辑改变。
|
||||
- 单车道最小宽度 2.4m;横断面总宽等于车道、边缘与步行带之和。
|
||||
- 同一站点左右外缘不得交叉;相邻 profile 之间必须有可计算的过渡。
|
||||
- 进口截面在 cutback 处与路口边界连续;路口面不自交。
|
||||
- connector、停止线、人行横道必须落在所属道路 / 路口可用面内,否则产生阻塞性诊断。
|
||||
- 无效草稿不替换最后一个有效预览。
|
||||
- 每次提交到活动副本是单个可撤销 operation;已保存编辑的撤销追加反向操作或禁用约束,历史不重写。
|
||||
- 普通路口锚定 node,复杂 cluster 锚定 cluster 与 arm,二者不共用低层约束。
|
||||
|
||||
## API 合约
|
||||
|
||||
新增端点:
|
||||
|
||||
| 端点 | 行为 |
|
||||
| --- | --- |
|
||||
| `GET /api/edit-state` | 活动文档、`documentVersion`、revision 元数据、约束状态、handle manifest |
|
||||
| `POST /api/edit-preview` | 传 `previewSeq` + draft operations,返回局部 preview 图层、diagnostics、manifest、`degraded`;不写文件 |
|
||||
| `POST /api/edits` | 校验并保存活动 v2 文档,要求 `expectedDocumentVersion` |
|
||||
| `POST /api/revisions` | 从活动副本创建命名不可变 revision |
|
||||
| `POST /api/revisions/:id/rebase` | 对目标 revision 显式重放,返回各 status 计数与明细 |
|
||||
|
||||
单写者保护:`POST /api/edits` 的 `expectedDocumentVersion` 与服务端不一致时返回 409 与当前版本,不写入。这挡住同机多标签页的静默互相覆盖;多人协作仍延后。
|
||||
|
||||
现有端点的变化(字段只增不改):
|
||||
|
||||
- `/api/state`、`/api/session` 增量返回 `activeRevisionId` 与 `documentVersion`。
|
||||
- `/api/import` 导入成功后自动创建基线 revision,返回其 id。
|
||||
- `/api/overrides` 保持 v1 语义;只有无法用 v1 表达的局部编辑进入 v2。
|
||||
- `/api/junction-clusters` 改写活动副本快照而非外部配置文件。
|
||||
- 所有写入沿用现有 staging 目录原子替换模式。
|
||||
|
||||
## 上线与回滚形态
|
||||
|
||||
客户端编辑能力全程挂在 `directEdit` 开关后,默认关闭,直到交付级验收标准全部通过。开关关闭时工作台行为与当前 main 完全一致:不注册编辑 interaction、不请求 manifest、不创建 handles/ghost/preview 图层。
|
||||
|
||||
服务端是纯增量:新端点独立于既有路由;`active/` 与 `revisions/` 不存在时旧代码路径照常工作;v1 `native-road-overrides.json` 始终保持权威且格式不变。因此任何一步回滚都不会让既有 `import-*` 目录无法打开,也不需要数据迁移回退脚本。
|
||||
|
||||
## 客户端边界
|
||||
|
||||
`workbench/client/index.html` 只加载 `src/main.tsx`,`sendWorkbenchApp()` 优先 `dist/index.html` 并回退到同一个 index.html。因此遗留的 `workbench/client/app.js`(约 1400 行 vanilla)已不是任何入口。本任务只在 React 应用内实现编辑能力,不同步 app.js;删除它另开任务。
|
||||
|
||||
客户端目前没有单元测试运行器(`test:client` 只是 `tsc --noEmit`)。本任务引入 `vitest`(node 环境)覆盖纯逻辑:EditSession 命令栈与 undo/redo、`previewSeq` 乱序丢弃、handle 事件到约束值的投影、米制换算。OpenLayers 地图行为(不重建 Map、图层增量替换)由 `implement.md` 的手测清单覆盖。
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,8 @@
|
||||
{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "本特性横跨 compiler / server / client 三层,新增 JSONL 文档、API 载荷与配置字段,正是该指南的触发条件"}
|
||||
{"file": ".trellis/spec/guides/code-reuse-thinking-guide.md", "reason": "米制换算必须复用 src/geometry/lane-geometry.js,v1 overrides 与 ID 校验必须复用而非另建一套"}
|
||||
{"file": ".trellis/tasks/08-26-direct-manipulation-road-editor/research/current-system.md", "reason": "现有可复用锚点、feature 回链字段与当前缺口清单"}
|
||||
{"file": ".trellis/tasks/08-26-direct-manipulation-road-editor/research/joint-solver.md", "reason": "求解阶段的插入点、依赖链顺序与约束不变量来源"}
|
||||
{"file": ".trellis/tasks/08-26-direct-manipulation-road-editor/research/canvas-integration.md", "reason": "输入 adapter 的候选、ol-ext 探针退出条件与回退优先级"}
|
||||
{"file": ".trellis/tasks/08-26-direct-manipulation-road-editor/research/revisions.md", "reason": "revision manifest 字段与重导入冲突体验的来源"}
|
||||
{"file": ".trellis/tasks/08-26-direct-manipulation-road-editor/research/junction-tools.md", "reason": "JunctionTools 的会话边界、预览/应用/保存状态与路口所有权划分"}
|
||||
{"file": ".trellis/tasks/08-26-direct-manipulation-road-editor/research/data-model-options.md", "reason": "三种数据模型的比较背景与选择理由;kind 枚举以 design.md 为准"}
|
||||
@@ -0,0 +1,107 @@
|
||||
# 实施计划
|
||||
|
||||
每步是一个独立提交,带自己的验证命令、门禁和回滚点。门禁不过就停在该步,不带着已知缺陷进入下一步。
|
||||
|
||||
约束与合约的权威定义在 `design.md`;本文只管执行顺序与验证。
|
||||
|
||||
## 全局回滚策略
|
||||
|
||||
- 任务分支上一步一提交,回滚等于 `git revert` 该提交,不做跨步大回滚。
|
||||
- 客户端编辑能力全程挂在 `directEdit` 开关后,默认关闭,直到第 8 步手测清单通过才默认开启。开关关闭时工作台行为与当前 main 完全一致。
|
||||
- 服务端新增端点与新文件是纯增量:`active/` 与 `revisions/` 不存在时,旧代码路径照常工作。任何一步回滚都不会让既有 import 目录无法打开。
|
||||
- v1 `native-road-overrides.json` 始终保持权威且格式不变,任何步骤都不迁移它。
|
||||
|
||||
## 0. 前置:依赖与测试基础设施
|
||||
|
||||
- 目标:先把验证能力建好,避免后续步骤"写完没法测"。
|
||||
- 范围:`package.json` 增加 `vitest`(固定版本)与 `test:client:unit` 脚本;建立客户端纯逻辑测试目录。不碰任何产品代码。
|
||||
- 验证:`npm run test:client:unit`(空套件通过)、`npm run format:check`、`npm run test`。
|
||||
- 门禁:新脚本可跑通且不影响现有 `test` / `test:client` / `build`。
|
||||
- 回滚点:仅 `package.json` 与测试目录,revert 无副作用。
|
||||
|
||||
## 1. `ol-ext` 限时探针
|
||||
|
||||
- 目标:只回答一个问题——能否复用通用 handle 的命中、pointer 生命周期与视觉反馈。
|
||||
- 范围:隔离探针,不修改生产基线图层,不进依赖清单直到通过。
|
||||
- 验证:手动跑探针页;确认 OL `Map` 未重建、proxy 拖拽稳定、基线 source 未被写入、事件能转成 draft 值。
|
||||
- 门禁:三条同时成立才把 `ol-ext` 固定为依赖。超过一个工作日或任一条不成立,立刻停止排障。
|
||||
- 回滚点:删除探针目录,改用原生 OL `Snap` + 小型 `PointerInteraction` adapter。`HandleManifest -> RoadEditOperation -> RoadConstraint -> preview solver` 合约不变,因此本步失败最多换输入层,不动 schema、求解器或已保存编辑。
|
||||
|
||||
## 2. v2 文档、活动副本与 revision 基础
|
||||
|
||||
- 目标:落地 `native-road-edits/v2`、operations、`anchorSnapshot` 与 5 态重放状态机。
|
||||
- 范围:新增文档读写、`active/` 与 `revisions/` 布局、内容寻址 OSM 副本、`documentVersion`、命名检查点与恢复读取。惰性迁移既有 import 目录,不移动既有文件。v1 overrides 完全不动。
|
||||
- 验证:`npm run test`(新增 fixture:文档往返、`documentVersion` 递增、惰性迁移在只有旧文件的目录上生成 `rev-0001`、内容相同的 OSM 不产生第二份副本)。
|
||||
- 门禁:既有 `workbench-data/import-*` 目录在新代码下可正常打开,且未被改写;schema 校验拒绝越界 `boundaryIndex` 与非法 station。
|
||||
- 回滚点:revert 本步后 `active/` 与 `revisions/` 只是残留目录,旧代码忽略它们照常运行。
|
||||
|
||||
## 3. area config 快照
|
||||
|
||||
- 目标:切断编译对外部区域配置文件的运行期依赖,让 revision 真正可复现。
|
||||
- 范围:活动副本与每个 revision 各写一份 `area-config.snapshot.json`;编译与预览改读快照;`/api/junction-clusters` 改写快照并在响应里返回可复制片段。
|
||||
- 验证:`npm run test` 新增 fixture——冻结 revision 后修改外部 area config,重新编译该 revision 结果不变;快照缺失时给出明确错误而非静默用外部文件。
|
||||
- 门禁:现有 `/api/junction-clusters` 的用户可见行为(返回可复制片段)不退化。
|
||||
- 回滚点:revert 后编译回到读外部配置文件;已写的快照文件被忽略,不影响 v1 链路。
|
||||
|
||||
## 4. 约束求解边界
|
||||
|
||||
- 目标:在 `compileGeometry()` 前插入纯函数 `resolveDirectEditConstraints`,输出 editable profiles、junction plans、handle manifest 与 diagnostics。
|
||||
- 范围:实现 6 个 kind 的求解;interval 默认范围推导(避开两端 reserve);junction reserve 计算;`junction-approach-width` 对道路 profile 的优先级与边界连续过渡。米制换算复用 `src/geometry/lane-geometry.js`,不新增第二套。
|
||||
- 验证:`npm run test` 新增 fixture——每个 kind 的重放、最小车道宽 2.4m、左右外缘不交叉、道路/路口连续、路口面不自交、connector 包含性、`boundaryIndex` 越界转 `stale`、锚点缺失/歧义分别转 `stale`/`conflicted`。
|
||||
- 门禁:求解是纯函数,无文件写入、无网络;`npm run test` 全绿且既有 baseline 输出在无 v2 约束时逐字节不变。
|
||||
- 回滚点:无 v2 约束时该步是恒等变换,因此 revert 前后编译输出一致,可安全单独回退。
|
||||
|
||||
## 5. 预览与编辑 API
|
||||
|
||||
- 目标:草稿预览与持久化分离,预览绝不写文件。
|
||||
- 范围:`GET /api/edit-state`、`POST /api/edit-preview`、`POST /api/edits`、`POST /api/revisions`、`POST /api/revisions/:id/rebase`;`previewSeq` 回显;`degraded` 标记;`expectedDocumentVersion` 前置条件与 409;`/api/state`、`/api/session`、`/api/import` 的增量字段。
|
||||
- 验证:`npm run test` 新增 server integration——预览调用前后目录 mtime 与内容不变;`expectedDocumentVersion` 不匹配返回 409 且不写入;原子写入在中途失败时不留半份文件;rebase 返回各 status 计数;预览与正式编译对同一约束集给出相同几何。
|
||||
- 门禁:预览零写入;409 路径有测试覆盖;现有 `/api/overrides`、`/api/compile`、`/api/state` 的既有字段与行为不变。
|
||||
- 回滚点:新端点是增量,revert 后客户端开关已关闭,工作台回到 v1 行为。
|
||||
|
||||
## 6. 主地图 Road editor
|
||||
|
||||
- 目标:外缘、步行带、车道分隔与区间范围可拖,禁入 junction reserve。
|
||||
- 范围:selection → handle manifest;handles / ghost / preview 三个独立 source;`EditSession` 命令栈与 undo/redo;80ms 防抖与 `pointerup` 最终请求;`previewSeq` 乱序丢弃与 `AbortController` 取消;无效草稿反馈;应用/保存/取消。全部挂在 `directEdit` 开关后。
|
||||
- 验证:`npm run test:client`、`npm run test:client:unit`(命令栈与 undo/redo、乱序响应丢弃、handle 事件到约束值的投影、米制换算的纬度正确性)、`npm run build`。
|
||||
- 门禁:单元测试覆盖上述四类纯逻辑;拖拽期间 `Map` 未重建且只有受影响 source 被替换(手测清单第 1-3 项)。
|
||||
- 回滚点:关掉 `directEdit` 开关即可现场止损,无需回滚代码;必要时 revert 本步。
|
||||
|
||||
## 7. 最小 JunctionTools
|
||||
|
||||
- 目标:单一普通 node 路口的进口宽度、cutback、单角部圆角,闭合预览/应用/取消。
|
||||
- 范围:单 `JunctionRef` 会话的路由与返回主地图的上下文;session draft;完整局部预览;应用合并到活动副本;取消回到进入前状态;切换路口前强制应用或取消。不做 cluster 高级编辑、不做多路口联动。
|
||||
- 验证:`npm run test:client:unit`(会话状态机:draft → 应用 → 主工作区未保存约束;取消后状态复原;未处理草稿时切换被拒绝)、`npm run test`(局部求解与全量编译一致)、`npm run build`。
|
||||
- 门禁:预览包含全部受影响派生对象(道路面、路口面、步行带、车道中心线、connector、停止线、斑马线、标线);拟合失败时返回最后有效几何加结构化诊断,不把非法图形显示成已应用。
|
||||
- 回滚点:路由与开关独立,revert 不影响第 6 步的主地图编辑能力。
|
||||
|
||||
## 8. 全量验证与开关默认开启
|
||||
|
||||
- 目标:跑完交付级验收标准,确认可默认开启 `directEdit`。
|
||||
- 范围:补齐 `prd.md`「验收标准(交付阶段)」逐条证据;开关默认值改为开启。
|
||||
- 验证:`npm run format:check`、`npm run test`、`npm run test:client`、`npm run test:client:unit`、`npm run build`,加下方手测清单。
|
||||
- 门禁:交付级验收标准全部勾选;任一条不过则开关保持关闭,任务不进入 Phase 3。
|
||||
- 回滚点:只改开关默认值,回滚成本为一行。
|
||||
|
||||
## 手测清单
|
||||
|
||||
自动化测试覆盖不到的地图行为,每次进入第 8 步都要跑一遍:
|
||||
|
||||
1. 选中道路 → 出现手柄,浏览器 devtools 中 `Map` 实例未变(拖拽前后同一对象引用)。
|
||||
2. 拖动外缘 → 只有道路面、步行带、车道线、标线、connector 的 source 被替换,底图与未受影响图层无重绘闪烁。
|
||||
3. 连续快速拖拽后松手 → 最终几何与松手位置一致,无回跳(验证乱序丢弃与最终请求)。
|
||||
4. 拖到违反最小车道宽 → 出现阻塞诊断,地图停在最后一个有效预览。
|
||||
5. 手柄落在 junction reserve 内 → 不可拖动并提示进入 `JunctionTools`。
|
||||
6. 进入 `JunctionTools` 调三项 → 预览完整;应用 → 返回主地图仍显示同一几何;取消 → 状态复原。
|
||||
7. 未处理草稿时尝试切换相邻路口 → 被拒绝并提示先应用或取消。
|
||||
8. 保存 → 重新编译 → 几何不变,约束状态 `exact`。
|
||||
9. 重新导入同一份 OSM → 约束全部 `exact`;导入删掉某条道路的 OSM → 相关约束 `stale`,旧 revision 仍可打开复现原结果。
|
||||
10. 两个标签页同时保存 → 后者 409 提示,前者结果保留。
|
||||
11. 关闭 `directEdit` 开关 → 工作台行为与当前 main 一致。
|
||||
|
||||
## 步骤依赖
|
||||
|
||||
0 → 1 可并行于 2;2 → 3 → 4 → 5 是硬顺序;6 依赖 1、4、5;7 依赖 6;8 依赖全部。第 1 步失败不阻塞 2-5,只改变第 6 步的输入 adapter 选择。
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,118 @@
|
||||
# 直接操纵道路编辑工作台
|
||||
|
||||
## 目标
|
||||
|
||||
让道路编译工作台支持类似 Drawtonomy 的直接操纵:用户能在地图上选择生成的道路面并通过有语义的控制柄调整细节,同时保留 OSM 作为输入来源、修改可解释且可审计,并能在重新编译或重新导入后可靠地重放。
|
||||
|
||||
## 已确认的事实
|
||||
|
||||
- `src/compile/native-road.js` 从 OSM 生成方向道路、车道、道路面、步行带、路口面、标线和连接路径;这些 GeoJSON 是派生输出,不是持久化编辑源。
|
||||
- 现有 `native-road-overrides/v1` 已支持道路宽度/车道数/步行带开关、路口和车道连接、以及标线样式,且以稳定的 OSM 派生语义 ID 定位目标,并在 OSM 改动后识别失效项。
|
||||
- 编译器使用 staging 目录原子发布输出;工作台已经具有单例 OpenLayers 地图、命令式图层 source 更新、选择高亮和暂存/保存/重新编译链路。
|
||||
- Drawtonomy 的公开 SDK 表明其道路由共享 `point`、`linestring` 和引用左右边界的 `lane` 构成;连接关系和导出几何从该对象图派生。其编辑器核心(手势状态机、选择、历史)不在公开仓库中,不能作为源码依赖。
|
||||
|
||||
## 产品要求
|
||||
|
||||
1. 编辑目标必须是道路语义对象,而不是直接保存最终 GeoJSON 多边形。
|
||||
2. 拖拽时必须即时显示预览,并清楚呈现将被同步影响的道路面、车道、标线和路口对象。
|
||||
3. 每次持久化修改都必须可解释:谁在何处、以什么规则、相对什么输入锚点施加了何种约束。
|
||||
4. OSM 重新导入或编译器升级后,修改应自动重放、明确报告冲突/失效,绝不能静默改写到错误道路。
|
||||
5. 用户必须可以撤销/重做未保存编辑,并能查看、禁用或删除已保存编辑。
|
||||
6. 新架构应复用现有道路参数 overrides、ID 校验、编译和图层更新能力,而不是并行维护第二套地图数据。
|
||||
7. OSM 道路中心线和拓扑保持只读;直接操纵首期仅编辑由它派生的横断面与路口细节。
|
||||
8. 首期必须同时验证道路横断面与路口细节的联合编辑:道路外缘、步行带、车道分隔,以及路口进口、cutback 与转弯角部都属于首批能力。
|
||||
9. 道路横断面拖拽默认生成以拖拽站点为中心的局部区间,并在区间边界平滑过渡回基线;用户可以用范围控制柄修改影响区间。
|
||||
10. 拖拽时浏览器立即更新控制柄、辅助线与半透明 ghost;在短防抖后调用服务端权威预览,服务端使用与正式编译相同的约束求解器返回受影响派生图层。浏览器不维护第二套道路几何算法。
|
||||
11. 工作台必须支持可复现的存盘 revision:冻结一次编译所需的 OSM 输入、区域配置、已有 overrides、直接编辑约束、信号数据和编译身份;重新导入 OSM 创建新 revision,不覆盖旧 revision。
|
||||
12. 导入 OSM 自动创建基线 revision;用户显式保存命名检查点时创建不可变 revision;普通保存和预览只更新活动副本。
|
||||
13. 路口点击编辑进入专用 `JunctionTools` 工作区,而非在主地图叠加完整路口控制面板;该工作区复用活动 revision 与直接编辑约束,并在操作后尽快重新求解生成道路拓扑和相关派生图层。
|
||||
14. `JunctionTools` 的草稿从首次拖拽起即显示即时 ghost 和服务端权威几何预览;“应用到工作区”仅合并有效草稿到主工作区,“保存”才持久化,“取消”丢弃本次会话草稿。
|
||||
15. 一次 `JunctionTools` 会话只编辑一个 node 或 cluster;切换相邻路口前必须应用或取消当前草稿。
|
||||
16. 主地图道路区间编辑仅拥有两个路口之间的内部区间;`JunctionTools` 独占路口保留区内的进口、cutback 与角部约束。求解器保证两侧连续,并以显式 junction approach 约束优先。
|
||||
17. 首个 `JunctionTools` 交付只验证单一普通路口的进口宽度、cutback 和单个角部圆角;必须展示完整拟合预览并能应用回主工作区。
|
||||
18. 约束 kind 枚举必须唯一且与首期范围一一对应;车道分隔必须有自己的约束 kind,不得借用外缘偏移表达。
|
||||
19. 预览必须有明确时序保证:乱序响应不得覆盖较新预览;拖拽防抖与 `pointerup` 最终请求分离;超出延迟预算时降级提示而不是几何闪烁。
|
||||
20. 持久化约束只使用米与归一化 station;坐标与单位换算的分层职责必须固定,客户端不得用投影坐标差充当米。
|
||||
21. 区域配置(含 `nativeRoad.junctionTemplates`)必须随活动副本与 revision 冻结为快照,编译与预览只读快照;否则 revision 不可复现。
|
||||
22. 同机多标签页并发保存必须被显式挡住(版本前置条件加冲突提示),不得静默互相覆盖。多人协作仍延后。
|
||||
23. revision 不自动删除;OSM 副本按内容寻址避免重复;派生产物缓存可清理且清理不影响可复现性。
|
||||
24. 编译器几何版本变化时,约束既不自动失效也不自动改值,必须经用户显式确认重放。
|
||||
25. 编辑能力只进 React 工作台;遗留 vanilla 客户端不同步、不在本任务内删除。
|
||||
26. 客户端纯逻辑必须可自动化测试;地图交互行为以固化在 `implement.md` 的手测清单覆盖。
|
||||
|
||||
## 需要完成的研究与设计
|
||||
|
||||
- 梳理当前模型、输出 feature 属性和现有 overrides 可直接复用的锚点。
|
||||
- 明确 Drawtonomy 的公开对象图、共享几何和派生原则,以及它与 OSM 编译流程不相同的边界。
|
||||
- 比较参数反推、语义几何约束、局部补丁几何三种数据模型,并给出持久化、重放、冲突、撤销和迁移策略。
|
||||
- 在确认编辑边界后,形成交互模型、编译边界、API 合约、版本化 schema 和分阶段实施计划。
|
||||
- 在实现前验证 `ol-ext` 的 Transform interaction 能否仅操作临时代理 feature,并与现有 `ol@10.10.0`、React 生命周期和局部预览稳定协作;验证结果决定是否纳入正式依赖。
|
||||
- `ol-ext` 验证必须是有时间上限、可独立删除的探针;失败仅替换输入 adapter,不得改变约束文档、求解器或编译架构。
|
||||
- `ol-ext` 探针限时一个工作日;必须同时满足“无地图重建、无基线 source 写入、拖拽稳定”,否则停止排障并采用 OpenLayers 原生 proxy + 小型语义 adapter。
|
||||
|
||||
## 任务地图
|
||||
|
||||
本任务是父任务:持有需求集、`design.md` 权威合约、跨子任务验收标准与最终集成验证。实现落在四个子任务,顺序依赖写在各自 `prd.md` / `implement.md`,不由树结构隐含。
|
||||
|
||||
| 子任务 | 交付物 | 对应父 `implement.md` 步骤 | 前置 |
|
||||
| --- | --- | --- | --- |
|
||||
| `08-26-direct-edit-documents` | v2 文档、活动副本、revision、area config 快照、测试基础设施 | 0、2、3 | 无 |
|
||||
| `08-26-direct-edit-solver-api` | `resolveDirectEditConstraints` 与预览/保存/revision/rebase API | 4、5 | documents |
|
||||
| `08-26-direct-edit-map-editor` | `ol-ext` 探针与主地图道路区间编辑 | 1、6 | solver-api 第 2 步(manifest) |
|
||||
| `08-26-direct-edit-junction-tools` | 单一普通路口的进口、cutback、单角部圆角 | 7 | solver-api、map-editor |
|
||||
|
||||
父任务自留第 8 步:跑完交付级验收标准并把 `directEdit` 开关默认开启。
|
||||
|
||||
## 延后项
|
||||
|
||||
- 不在当前前置架构阶段设计或实现高级复合路口模板编排、多个路口的联合会话、控制设施逐个手工布置、协作合并或全面的拓扑创作工具。
|
||||
|
||||
## 首个交付范围
|
||||
|
||||
- 版本化直接编辑文档、活动工作副本和命名 revision 检查点。
|
||||
- 限时的 `ol-ext` 代理 feature 验证及原生 OpenLayers adapter 回退。
|
||||
- 服务端权威预览 API 与客户端即时 ghost。
|
||||
- 主地图的道路内部区间:外缘、步行带、车道分隔和范围控制。
|
||||
- 最小 `JunctionTools`:单一普通路口的进口、cutback、单角部圆角、预览/应用/取消。
|
||||
- 约束重放的精确匹配、待确认和失效状态;旧 revision 永不被重导入覆盖。
|
||||
|
||||
## 验收标准(规划阶段)
|
||||
|
||||
- [x] 已提供当前能力与可复用边界的证据清单。
|
||||
- [x] 已区分 Drawtonomy 的公开事实、可迁移原则和不可验证的编辑器内部实现。
|
||||
- [x] 已确定持久化编辑数据不是最终 GeoJSON,并有版本化、可重放、可失效诊断的数据方案。
|
||||
- [x] 已明确拖拽预览、应用、保存、重新编译、撤销/重做、OSM 重导入和 revision 检查点的行为。
|
||||
- [x] 已定义 `ol-ext` 限时探针、原生 OpenLayers 回退与不改变数据合同的止损规则。
|
||||
- [x] 已定义首个 Road editor 与最小 JunctionTools 的范围、所有权和延后项。
|
||||
- [x] 约束 kind 枚举唯一,且覆盖首期全部 6 项能力(含车道分隔)。
|
||||
- [x] handle manifest、坐标分层、预览时序、area config 快照、单写者保护、留存策略均已在 `design.md` 定义。
|
||||
- [x] 已明确遗留客户端边界与客户端测试基础设施的决定。
|
||||
- [x] 已形成 `design.md` 和 `implement.md`,供用户审阅后再开始实现。
|
||||
|
||||
## 验收标准(交付阶段)
|
||||
|
||||
### 独立 JunctionTools 页面(重新确认,2026-09-03)
|
||||
|
||||
JunctionTools 必须是一个独立的路口编辑页面,而不是覆盖在主地图上的参数弹层。主地图只负责发现路口、显示入口和返回导航;进入 `/junction/:type/:id` 后,页面主要视觉对象是当前单个路口,不能被编辑面板遮挡。
|
||||
|
||||
- [ ] 页面自动聚焦并适配当前路口,持续显示路口面、进口道路、圆角、cutback、斑马线、停止线和信号灯。
|
||||
- [ ] 几何编辑与已有设施编辑在同一页面完成,使用同一份 draft、preview、undo/redo、apply、save、cancel 状态。
|
||||
- [ ] 参数输入和地图拖拽是同一参数的两个输入通道:任一通道变化都会在路口画布上显示权威预览,另一通道同步当前值。
|
||||
- [ ] 预览失败时保留最后一个有效几何并显示结构化诊断;非法值不得显示成已应用几何。
|
||||
- [ ] 首版支持已有斑马线、停止线、信号灯的可视化调整和已有字段编辑;设施创建、删除和跨路口迁移不在首版范围。
|
||||
- [ ] 主地图的道路级编辑能力不因进入独立页面而消失;离开页面前必须明确应用、保存、放弃或继续停留。
|
||||
|
||||
每条都必须可执行验证,不接受"看起来对了"。
|
||||
|
||||
- [ ] 拖动道路外缘 → 保存 → 重新编译,道路面、步行带、车道线、标线与 connector 一致更新,约束状态为 `exact`。
|
||||
- [ ] 车道分隔手柄可独立调整某条分隔线,且不等价于外缘偏移的副作用。
|
||||
- [ ] 落在 junction reserve 内的道路手柄不可拖动,并给出引导进入 `JunctionTools` 的原因。
|
||||
- [ ] `JunctionTools` 单路口会话可调进口宽度、cutback 与一个角部圆角,预览包含全部受影响派生对象;应用后主地图继续显示同一预览,取消后回到进入前状态。
|
||||
- [ ] 违反最小车道宽 2.4m 或造成路口面自交的草稿返回阻塞性诊断,且不替换最后一个有效预览。
|
||||
- [ ] 快速连续拖拽时乱序预览响应不会覆盖较新结果(可通过注入延迟的测试复现)。
|
||||
- [ ] 同一 OSM 重新导入后,约束按 `exact` / `pending` / `conflicted` / `stale` 分类报告;旧 revision 仍可打开并复现原结果。
|
||||
- [ ] 修改 area config 后,旧 revision 的编译结果不变(证明快照生效)。
|
||||
- [ ] 两个标签页并发保存时,后者收到 409 且不覆盖前者。
|
||||
- [ ] 未保存编辑可撤销/重做;已保存编辑的撤销以反向操作或禁用约束体现,历史不被重写。
|
||||
- [ ] 拖拽与选择过程中 OpenLayers `Map` 未被重建,只有受影响 source 被替换。
|
||||
- [ ] `npm run format:check`、`npm run test`、`npm run test:client`、新增客户端单元测试与 `npm run build` 全绿。
|
||||
+108
@@ -0,0 +1,108 @@
|
||||
# Canvas 与控制柄工具方案
|
||||
|
||||
## OpenLayers 能力确认
|
||||
|
||||
当前项目使用 `ol@10.10.0`。OpenLayers `VectorLayer` 默认由 Canvas renderer 绘制,当前工作台正是这种模式。类型声明可确认:
|
||||
|
||||
- `ol/interaction/Modify` 支持对 source/feature collection 的顶点修改,带 `modifystart` / `modifyend`、自定义 vertex style、pixel tolerance 与 hit detection。
|
||||
- `ol/interaction/Snap` 支持顶点、边、交点吸附,且会改写交互事件的 coordinate/pixel,供其他 pointer interaction 使用。
|
||||
- `ol/interaction/Translate` 支持 feature 集合的拖动和 start/move/end 事件。
|
||||
|
||||
因此,OL 具备 Canvas 渲染、命中测试、投影换算、视口同步与低层 pointer 交互所需的基础能力。它没有白板编辑器的命令历史、语义控制柄、约束求解、工具状态或多对象选择模型。
|
||||
|
||||
## 不使用原生 `Modify` 直接编辑道路面
|
||||
|
||||
`Modify` 会直接改变传入 feature 的 geometry 坐标,也允许插入/删除顶点。这适合通用 GIS 几何编辑,但不适合本项目:道路面和路口面是编译产物,顶点没有稳定的编辑语义,直接修改会使车道、标线和 connector 脱节。
|
||||
|
||||
它可被借鉴的只是事件生命周期、Canvas 命中与样式机制;道路源图层必须保持只读。
|
||||
|
||||
## 建议架构
|
||||
|
||||
```text
|
||||
OpenLayers Map / VectorLayer (Canvas)
|
||||
- 基线与预览 GeoJSON 图层:只读、由编译器/preview solver 提供
|
||||
- editHandles VectorLayer:Point/LineString feature,Canvas 画柄与影响区间
|
||||
- EditPointerInteraction:命中 handle -> 投影拖拽方向 -> 更新 draft command
|
||||
- Snap:只对批准的语义锚点/网格 source 生效
|
||||
|
|
||||
v
|
||||
React EditSession(selection、draft、undo/redo)
|
||||
|
|
||||
v
|
||||
constraint preview solver -> 仅更新受影响 source
|
||||
```
|
||||
|
||||
控制柄是独立的、可丢弃的 UI feature;它的 properties 只携带 `handleId`,并通过 manifest 反查 semantic anchor。任何鼠标移动都先被投影为结构化约束值,再重算预览,绝不把 handle 的地理坐标直接写为道路 polygon 坐标。
|
||||
|
||||
## 引入独立 Canvas 白板库的判断
|
||||
|
||||
将 tldraw、Fabric、Konva 等作为覆盖层或替换 OL,均会引入第二个 viewport、平移/缩放手势、坐标系与 hit-test 系统。与地理坐标、OL hit detection、原有图层开关和地图导航同步的成本很高,且不能自动提供道路领域的约束模型。
|
||||
|
||||
除非“Quickdraw”是一个能在既有地图 Canvas 内以 OpenLayers coordinate/pointer API 运行的明确库,否则首选是继续把 OL 作为唯一 Canvas 和视口,使用它成熟的 interaction primitives,加一个小而领域化的 `EditPointerInteraction`。这不是手写画布;渲染、坐标、事件和吸附都由 OL 提供,新增代码只负责道路语义。
|
||||
|
||||
## 成熟的 OpenLayers 扩展:ol-ext
|
||||
|
||||
`ol-ext` 是当前最匹配的成熟扩展候选:npm 最新版为 `4.0.38`(2026-02-23),BSD-3-Clause,仓库仍持续维护。其 `interaction/Transform` 明确提供:
|
||||
|
||||
- 单独的 Canvas overlay layer 与可定制的 transform handles;
|
||||
- 与 `Select` 交互同步选择;
|
||||
- feature translate / scale / stretch / rotate;
|
||||
- `translatestart`、`translating`、`translateend`、`scalestart`、`scaling`、`scaleend` 等生命周期事件;
|
||||
- 通过 `PointerInteraction` 实现,因此共享 OpenLayers 的地图坐标、事件分发与视口。
|
||||
|
||||
这能承担通用控制柄的视觉和 pointer 生命周期,消除自行实现 hover、命中、capture、拖拽状态机和控制柄绘制的大部分工作。
|
||||
|
||||
### 不能委托给 ol-ext 的部分
|
||||
|
||||
`Transform` 的最终行为仍是缩放、旋转或平移传入 feature 几何。其控制柄是矩形 bounding box,而道路编辑需要沿道路法线的 edge offset、沿中心线的范围控制和路口特定的 cutback/corner radius;这些语义并非该扩展的能力。
|
||||
|
||||
推荐将 ol-ext 只绑定到**短生命周期 proxy feature**:
|
||||
|
||||
```text
|
||||
语义 handle manifest -> proxy feature / ol-ext Transform
|
||||
-> transform event -> 约束值(法向偏移、station interval、cutback、radius)
|
||||
-> preview solver -> 新预览几何与新的 proxy
|
||||
```
|
||||
|
||||
真实编译产物图层不可传给 `Transform`。对于不能表达为标准 translate/scale 的角部圆角和区间范围控制,仍需一个很小的领域 adapter;但它只做“事件到约束”的投影,不维护自己的 Canvas 或通用手势系统。
|
||||
|
||||
## 建议的验证闸门
|
||||
|
||||
在正式实现前完成一个隔离技术验证:将 `ol-ext` 的 Transform 绑定到单道路的临时 proxy,确认它能在当前 `ol@10.10.0`、React map 生命周期下稳定工作,并验证一次拖拽只更新 proxy/preview source、不会改写基线 source、不会重建地图。通过后再将它固定为依赖;不通过则保留 OpenLayers 原生 interaction 方案,避免在主分支承诺未经验证的扩展。
|
||||
|
||||
## 有限探针与回退策略
|
||||
|
||||
`ol-ext` 不是架构前提。探针只允许解决一个问题:复用通用 handle 的命中、pointer lifecycle 和视觉反馈。它有明确的时间上限和退出条件:
|
||||
|
||||
| 结果 | 动作 |
|
||||
| --- | --- |
|
||||
| 可在临时 proxy 上平稳拖拽,且不写基线 source、不重建 Map | 作为标准 transform 代理的可选依赖 |
|
||||
| 与 `ol@10.10.0` 或 React 生命周期不兼容 | 删除探针,不迁移现有 MapCanvas;走原生 OL 方案 |
|
||||
| 能运行但矩形 scale/rotate 模型妨碍道路法线/路口约束 | 不把它用于道路手柄;仅保留可复用部分或删除 |
|
||||
| 探针超过预设时间仍无法达到以上条件 | 停止排障,按回退方案推进 |
|
||||
|
||||
回退方案按优先顺序:
|
||||
|
||||
1. **OpenLayers 原生 proxy + 小型 `PointerInteraction` adapter**:Point/LineString proxy 仍由 OL Canvas 绘制和命中,使用 `Snap` 处理吸附;adapter 只处理已命中的少量语义 handle 到 constraint 的投影。它不重写渲染、相机、图层或通用选择,工作量受限。
|
||||
2. **DOM handle overlay + 成熟手势库**:仅在当前选中道路/路口上放置少数固定像素的 React/HTML controls,用成熟拖拽手势库处理 pointer capture;每个地图 postrender 将它们用 `map.getPixelFromCoordinate()` 对齐。地图仍是唯一视口,未命中 handle 的事件继续交给 OL。适合复杂的范围、数值标签和路口控制,但不是 Canvas 风格。
|
||||
3. **不采用的方向**:迁移到 MapLibre/Leaflet 仅为获取绘制插件,或把 Quickdraw 叠到 OL 上。这会更换地图/视口基础设施,成本远高于有限 adapter,且不能解决道路语义。
|
||||
|
||||
无论哪个输入 adapter 运行,`HandleManifest -> RoadEditOperation -> RoadConstraint -> preview solver` 的数据合同保持不变。因此探针失败最多替换输入层,不会推翻 schema、求解器或已保存编辑。
|
||||
|
||||
## Drawtonomy 的关系
|
||||
|
||||
公开 checkout 未包含 `Canvas.tsx`,也未在 package manifests 或 lockfile 中暴露 `tldraw`、Konva、Fabric、Excalidraw 或名为 Quickdraw 的依赖。因此不能从该源码确认其编辑器具体使用了哪个成熟 Canvas 库,只能借鉴其公开的对象图原则。
|
||||
|
||||
## Quickdraw 核查结论
|
||||
|
||||
检查 `/tmp/quickdraw` 后,确认它是 MIT 许可、零运行时依赖的完整无限白板 SDK,而不是地图编辑器控制柄库:
|
||||
|
||||
- `packages/core/src/editor.js` 在传入 container 内创建自己的 scene canvas 和 overlay canvas,并实现独立 camera(`x/y/z`)、平移、缩放、pinch、pointer capture、hit test、selection 和 resize/rotate/arrow handles。
|
||||
- `packages/core/src/store.js` 使用不可变 record、transaction、diff、batch undo/redo;同一手势的连续更新会合并为一个 history entry。
|
||||
- 内建形状和工具是封闭集合(笔、箭头、几何形状、文字等),公开资料中没有可把 OpenLayers feature 注册为原生 shape/handle 或让它共享外部 map camera 的扩展接口。
|
||||
|
||||
### 结论
|
||||
|
||||
不将 Quickdraw 作为覆盖层或替代 OpenLayers:二者都会处理 pointer、wheel、pinch、屏幕到世界坐标转换和 camera,接入后要持续同步两套视口,且会破坏当前 OL 地图导航和图层命中。也不将 Quickdraw 的 flat drawing document 作为道路约束的存储格式。
|
||||
|
||||
可直接借鉴的成熟实现原则是:固定像素尺寸的控制柄、overlay 与场景分离、pointer capture、一个 gesture 对应一个 transaction、不可变 diff 的 undo/redo、以及局部渲染。项目自身的 `EditSession` 应采用相同语义,但以 `RoadEditOperation` / `RoadConstraint` 为数据而非 Quickdraw shape。
|
||||
+30
@@ -0,0 +1,30 @@
|
||||
# 当前系统能力地图
|
||||
|
||||
## 编译链路
|
||||
|
||||
`src/compile/compiler.js:16` 读取 OSM 和 `native-road-overrides.json`,调用 `compileRoadModel()` 与 `compileGeometry()`,写入 staging 目录后原子替换产物目录。生成 GeoJSON 因此是可丢弃、可重建的派生层。
|
||||
|
||||
`src/compile/native-road.js:79` 将 OSM way 按共享节点拆分为方向道路;每条道路有稳定的 `road:way/<way>[:segment/<n>]:<direction>` ID、`segmentId`、OSM 节点端点和中心线。道路面/步行带/车道线/中心线/路口/连接线均由这个模型计算。
|
||||
|
||||
## 可直接复用
|
||||
|
||||
| 现有能力 | 直接操纵中的职责 |
|
||||
| --- | --- |
|
||||
| 道路、端点、车道与 segment ID | 约束的语义锚点和 OSM 重导入后的匹配基础 |
|
||||
| `native-road-overrides/v1` 校验与 stale diagnostics | 新 schema 的版本化校验、失效检测和编辑列表 |
|
||||
| `applyRoadOverrides()` | 把可反推的拖拽收敛为既有 `widthMeters`、步行带等参数 |
|
||||
| `compileGeometry()` | 约束生效后的权威重算边界 |
|
||||
| feature `native_id`、`road_id`、`segment_id`、`osm_node_id` | 渲染 feature 到语义编辑目标的回链 |
|
||||
| OpenLayers 单实例 + source registry | 手柄、预览和选中态可作为独立 source/layer 增量更新,避免重建容器 |
|
||||
| 暂存/保存/重新编译 API | 命令历史与持久化操作的基础链路 |
|
||||
|
||||
## 当前缺口
|
||||
|
||||
- 没有描述“一个渲染边界/顶点对应哪个语义控制点”的 handle manifest。
|
||||
- 现有 road override 只能整体宽度/车道数,不表达沿道路位置变化、边缘偏移、局部过渡或路口角部约束。
|
||||
- 没有操作日志、撤销/重做、预览求解器或冲突 rebase 状态。
|
||||
- 路口模板在 area 配置中,不在 overrides 文件;直接操纵要明确哪些路口细节可落到 area 模板、哪些可成为用户覆盖项。
|
||||
|
||||
## 约束
|
||||
|
||||
不要将道路面 polygon、标线 polygon 或任意 OpenLayers `Feature` 坐标作为主要持久化编辑内容。它们没有足够的拓扑语义,且在 OSM 拆段、路口重算或编译器升级后很难可靠重放。
|
||||
+81
@@ -0,0 +1,81 @@
|
||||
# 可编辑数据模型的比较
|
||||
|
||||
> 本文是方案比较的探索记录。约束模型、kind 枚举、锚点类型与文档 schema 的权威定义在 `design.md`;如有冲突以 `design.md` 为准。
|
||||
|
||||
## 共同不变量
|
||||
|
||||
- OSM 原文与其解析出的道路模型是基线,不由拖拽直接覆盖。
|
||||
- 所有持久化修改都必须含版本、稳定锚点、创建时基线指纹、参数、状态和解释信息。
|
||||
- 每个输出 feature 都必须能给出生成它的输入语义 ID 与适用约束,供 UI 选择和诊断使用。
|
||||
- 拖拽过程可使用临时求解结果;只有显式保存才写入可重放命令。
|
||||
|
||||
## 方案比较
|
||||
|
||||
| 方案 | 持久化内容 | 优点 | 根本限制 |
|
||||
| --- | --- | --- | --- |
|
||||
| 参数反推 | `widthMeters`、lane count、步行带宽度等 | 可最大复用 v1,重编译最稳 | 不能表达沿程局部收放、独立边缘或路口角部 |
|
||||
| 语义几何约束 | 对道路横断面、边缘、过渡、路口的约束 | 兼顾直接操纵与 OSM 重放;适合本项目 | 需要 solver、优先级和冲突诊断 |
|
||||
| 局部 patch 几何 | 渲染 polygon 的顶点/边偏移 | 表达最自由 | 极难在 OSM 或生成算法变化后重定位,拓扑易破坏 |
|
||||
|
||||
## 建议方向:版本化的约束文档
|
||||
|
||||
不是将所有编辑统一存为一个巨型 mesh,而是将它们存为带锚点的声明式约束,并保留“由哪个交互生成”的命令记录。
|
||||
|
||||
```ts
|
||||
interface RoadEditDocument {
|
||||
schema: 'native-road-edits/v2'
|
||||
base: {
|
||||
osmSha256: string
|
||||
compilerGeometryVersion: string
|
||||
createdAt: string
|
||||
}
|
||||
constraints: RoadConstraint[]
|
||||
operations: RoadEditOperation[]
|
||||
}
|
||||
|
||||
interface RoadConstraint {
|
||||
id: string
|
||||
kind: RoadConstraintKind // 6 个取值见 design.md「约束模型」
|
||||
anchor: SemanticAnchor
|
||||
anchorSnapshot: AnchorSnapshot
|
||||
value: unknown
|
||||
enabled: boolean
|
||||
status: ConstraintStatus // exact | recheck | pending | conflicted | stale
|
||||
provenance: { operationId: string; createdAt: string; author?: string }
|
||||
}
|
||||
|
||||
type SemanticAnchor =
|
||||
| { type: 'road-station'; roadId: string; station: number; side?: 'left' | 'right' }
|
||||
| { type: 'road-interval'; roadId: string; startStation: number; endStation: number; side?: 'left' | 'right' }
|
||||
| { type: 'junction-approach'; nodeId: string; segmentId: string; side?: 'left' | 'right' }
|
||||
| { type: 'junction-corner'; nodeId: string; incomingRoadId: string; outgoingRoadId: string }
|
||||
```
|
||||
|
||||
`station` 是相对道路中心线归一化弧长 `0..1`,而不是绝对经纬度或数组下标。它对顶点加减和轻微 OSM 几何调整更稳定;保存时还应记录 `anchorSnapshot`(当时位置、切线、道路长度、相邻 OSM node ID)作为重定位/冲突检测证据。
|
||||
|
||||
道路横断面拖拽默认写入 `road-interval` 约束:拖拽位置为 interval 中心,系统根据道路长度与邻近路口预留距离推导初始 `startStation` / `endStation`,并在两端使用明确的 `transition: 'smoothstep'` 回归基线。用户调整范围手柄时只更新该 interval,不存储鼠标轨迹。
|
||||
|
||||
## 分层求解规则
|
||||
|
||||
1. **基线层**:OSM → 当前道路模型和默认横断面。
|
||||
2. **现有参数层**:v1 road/connection/style overrides;可由简单拖拽写入,继续兼容。
|
||||
3. **几何约束层**:按语义锚点计算横断面、边界和路口局部形状;冲突时按明确优先级或提示用户处理。
|
||||
4. **派生层**:道路面、步行带、车道中心线、标线、停止线和 connector 必须一起重新计算,不能只移动视觉面。
|
||||
|
||||
## 操作、撤销和重导入
|
||||
|
||||
- UI 维护本地命令栈:pointer down 生成草稿,pointer move 更新临时 constraint,pointer up 合并为一个 `operation`;undo/redo 仅移动指针,不写文件。
|
||||
- 保存后写入完整约束文档和不可变 `operations` 记录;已保存编辑的撤销创建反向操作或禁用约束,不修改历史。
|
||||
- 重导入时先按 `roadId`/`nodeId` 精确匹配;失败时使用 `anchorSnapshot` 的 OSM node、距离和切线作候选匹配。匹配不唯一或偏差超阈值即标记 `conflicted`,不自动应用。
|
||||
- v1 覆盖项保留并逐步迁移:全路宽度仍是 road override;只有无法表达的局部调整进入 v2 constraints。
|
||||
|
||||
## 需要在产品边界确认后细化
|
||||
|
||||
- 路口角部是否由独立约束处理,还是将路口升级为可编辑的模板/参数对象。
|
||||
- 是否需要多人协作;若需要,operation log 必须具备 actor、revision 和并发合并策略。
|
||||
|
||||
## 已确认边界
|
||||
|
||||
OSM 中心线与拓扑保持只读。直接操纵不会新增 `centerline-control-point`、分段、合并或连接/断开拓扑操作;这类修改通过修正 OSM 后重新导入完成。v2 约束因此只作用在由中心线派生的横断面、边缘、步行带与路口细节。
|
||||
|
||||
首期范围包含道路外缘、步行带、车道分隔,以及路口进口、cutback 与转弯角部。路口必须是独立的 `junction-*` anchor,不应伪装成某一条道路末端的 edge offset;它会同时影响道路截断、路口面、connector、停止线、斑马线和标线。
|
||||
+26
@@ -0,0 +1,26 @@
|
||||
# Drawtonomy:可验证的设计证据
|
||||
|
||||
本笔记仅基于本机 `/Users/que01/Project/drawtonomy` 的公开源码与文档。该 checkout 不包含编辑器 Canvas、指针事件、选择或历史实现;不能据此断言它具体如何处理拖拽状态机。
|
||||
|
||||
## 公开事实
|
||||
|
||||
- `README.md` 将其描述为 topology-aware lane、snap 与 point sharing;连接会随编辑保持。
|
||||
- `packages/drawtonomy-sdk/src/types.ts` 定义 `point`、`linestring`、`lane`:lane 用 `leftBoundaryId` / `rightBoundaryId` 引用边界,边界以 `pointIds` 引用点,`next`/`prev` 表示车道关系。
|
||||
- `packages/drawtonomy-sdk/src/exporter/osmToShapes.ts` 从 Lanelet2 导入时复用相同的点和 linestring,对相邻道路保留共享边界与方向反转信息。
|
||||
- `packages/drawtonomy-sdk/src/exporter/laneCenterline.ts` 从左右边界按归一化弧长采样,导出中心线和宽度;中心线是派生数据。
|
||||
- `docs/exporter.md` 指出可重新编辑的 SVG 内嵌完整 snapshot,导出器只从对象图读取数据。
|
||||
|
||||
## 可迁移原则
|
||||
|
||||
1. **拥有关系而非复制关系**:共享点/边界只保存一次,依赖对象通过 ID 引用。因此一个动作自然波及所有关联几何。
|
||||
2. **编辑源与展示/导出分离**:编辑对象图是源,中心线、边界渲染、导出格式是派生物。
|
||||
3. **显式拓扑**:车道连接不是靠距离猜测,而是用 `next` / `prev` 表示。
|
||||
4. **可重新打开的完整状态**:持久化内容足以重新构建编辑场景,而不是一张结果图。
|
||||
|
||||
## 不应直接照搬
|
||||
|
||||
Drawtonomy 是从空白画布或 Lanelet2 形状开始编辑的创作工具;本项目以 OSM 为权威输入、编译器推导道路横断面和路口。若完全改为点/边界对象图,会失去现有 OSM 重导入、规则推导和可追溯性,且制造第二个不一致的地图源。
|
||||
|
||||
## 对本项目的结论
|
||||
|
||||
借鉴其“语义对象图 + 依赖重算 + 共享锚点”的原则,但将持久化内容定义为附着在 OSM 派生语义 ID 上的约束,而不是迁移到 Drawtonomy 的自由形状 snapshot。
|
||||
+56
@@ -0,0 +1,56 @@
|
||||
# 道路与路口的联合求解边界
|
||||
|
||||
## 当前依赖已经存在
|
||||
|
||||
`compileGeometry()` 目前以同一 `model` 和 `junctionPlans` 依次生成道路面、车道中心线、边缘线、控制设施、中心线/车道标线、步行带、connector 与路口面。它们不是孤立图层:
|
||||
|
||||
```text
|
||||
道路横断面 / 进口尺寸
|
||||
-> 道路面、步行带、车道偏移
|
||||
-> 车道线与 connector
|
||||
-> 路口边界、cutback、转弯圆角
|
||||
-> 停止线、斑马线、箭头与诊断
|
||||
```
|
||||
|
||||
普通路口目前由 `compileJunctionPlans()` 的 approach、`cutbackMeters` 和 boundary 驱动;复合路口则由 `junctionTemplates.clusters` 和 `complex-junction.js` 的 core radius、进口包络和角部岛生成。直接操纵不能在最终 `roadSurface` / `intersectionSurface` 上独立移动顶点,否则会破坏这条依赖链。
|
||||
|
||||
## 提议的新增阶段
|
||||
|
||||
```text
|
||||
OSM -> compileRoadModel -> 现有 v1 参数覆盖
|
||||
-> resolveDirectEditConstraints
|
||||
-> editableRoadModel + editableJunctionPlans
|
||||
-> 既有图层编译器(逐步接收扩展参数) -> GeoJSON
|
||||
```
|
||||
|
||||
`resolveDirectEditConstraints` 的职责是:
|
||||
|
||||
1. 将 `road-station` / `road-interval` 约束整理为道路横断面 profile;
|
||||
2. 将道路末端 profile 与 `junction-approach` 约束合并,构建一致的进口截面;
|
||||
3. 以 `junction-corner` / `junction-cutback` 约束生成可验证的 junction plan;
|
||||
4. 在违反最小车道宽、相邻道路相交、交叉口连接线包络等不变量时,返回明确冲突而非偷偷修复;
|
||||
5. 输出一个 handle manifest,使地图手柄能从同一语义模型读取位置、可拖动方向、受影响对象和可见的值。
|
||||
|
||||
道路 interval 的默认范围由求解器决定,而不是 UI 预设像素:避开两端的 junction cutback,优先取拖拽站点两侧可用长度的有限比例;若道路过短或与另一个约束重叠,预览返回可调整范围或冲突信息。
|
||||
|
||||
## 交互预览
|
||||
|
||||
拖动不触发文件写入或完整工作台重建。地图维护 `EditSession`:
|
||||
|
||||
```text
|
||||
pointer down: 读取 handle 的 semantic anchor,创建 draft command
|
||||
pointer move: 投影鼠标位置 -> 立即更新 ghost 与 draft constraint -> 防抖服务端预览求解
|
||||
pointer up: 验证成功则压入本地命令栈;失败保留提示并回退到上一个有效预览
|
||||
save: 批量持久化 constraints + operations
|
||||
compile: 用已保存文档运行权威全量编译
|
||||
```
|
||||
|
||||
浏览器 ghost 仅包含控制柄、辅助线与半透明预估轮廓,不承担权威道路几何。服务端复用正式编译的约束求解逻辑,返回受影响的少数 OpenLayers source(道路面、步行带、路口、标线、connector 和 handles);客户端替换它们,而非卸载 `MapCanvas` 或重新创建 `Map`。这与现有图层可见性和选择修复一致。
|
||||
|
||||
## 约束不变量
|
||||
|
||||
- 单车道最小宽度,例如 2.4m;道路横断面总宽度等于车道、边缘和步行带之和。
|
||||
- 一个站点的左右外缘不得交叉;相邻 profile 之间必须有可计算的过渡。
|
||||
- 进口截面必须在路口 cutback 处与路口边界连续。
|
||||
- connector、停止线和人行横道必须保持在所属道路/路口可用面内,否则产生阻塞性诊断。
|
||||
- 普通路口与复杂 cluster 不共用相同低层约束:前者锚定 node,后者锚定 cluster 和 arm,避免将 cluster 缩减为多个互相冲突的普通路口编辑。
|
||||
+71
@@ -0,0 +1,71 @@
|
||||
# JunctionTools 专用路口编辑工作区
|
||||
|
||||
## 结论
|
||||
|
||||
路口应从主地图的上下文控制柄升级为专用编辑工作区。主地图负责发现、选择和进入;`JunctionTools` 负责高密度的局部几何、拓扑和诊断操作。这不改变“OSM 中心线/拓扑只读”和“约束驱动派生输出”的原则。
|
||||
|
||||
## 入口与范围
|
||||
|
||||
从路口面或诊断进入,路由参数使用语义引用:
|
||||
|
||||
```ts
|
||||
type JunctionRef =
|
||||
| { type: 'node'; id: string }
|
||||
| { type: 'cluster'; id: string }
|
||||
```
|
||||
|
||||
工作区加载活动 revision 中该 junction 的 context:路口面、外部进口、相邻道路的短上下文、车道/connector、步行带、停止线、斑马线、诊断和当前 constraints。保留返回主地图的入口与位置,避免用户失去全局方位。
|
||||
|
||||
## 统一 UI、不同求解器
|
||||
|
||||
普通 node 和复合 cluster 仍共享“进口、角部、控制设施、诊断”的用户心智模型;但 `JunctionTools` 根据 `JunctionRef` 提供不同内部投影:
|
||||
|
||||
- node:按 OSM node 的 incoming/outgoing approaches 和 corners 编辑。
|
||||
- cluster:按对外 arms 编辑;内部短连接不作为用户可拖的普通路口边缘,避免约束彼此冲突。
|
||||
|
||||
这比强迫主地图显示一套通用控制柄更可靠,也比暴露多套产品工具更易理解。
|
||||
|
||||
## 快速拓扑拟合与更新
|
||||
|
||||
此处“拓扑更新”指重新求解**生成道路的可行拓扑**,不修改 OSM 图拓扑:进口横断面、车道分配、connector/movement、路口边界、步行带、停止线、斑马线和标线必须一起重算。
|
||||
|
||||
```text
|
||||
JunctionTools 草稿操作
|
||||
-> 客户端即时 ghost
|
||||
-> 防抖服务端局部 junction solve
|
||||
-> 返回 fit 后的 junction plan、派生 GeoJSON、拓扑诊断
|
||||
-> 当前编辑器局部刷新;返回主地图后复用同一 preview
|
||||
```
|
||||
|
||||
局部解必须校验最小车道宽、连接线包含性、surface 自交、控制设施可放置性与 cluster arm 连续性。无法拟合时返回最后有效几何与结构化诊断;不能把不合法的图形显示成已应用。
|
||||
|
||||
## 与 revision 的关系
|
||||
|
||||
`JunctionTools` 的草稿属于活动工作副本的 `EditSession`,不是独立导出文件。用户可以取消并丢弃草稿,或将有效操作合并到主工作区;之后仍通过普通保存和命名检查点进入 revision 历史。
|
||||
|
||||
## 预览与提交状态
|
||||
|
||||
“预览”“应用”“保存”是三个不同状态,不能把保存当作看见效果的前提:
|
||||
|
||||
```text
|
||||
首次拖拽 -> session draft + 即时 ghost
|
||||
防抖服务端返回 -> JunctionTools 显示权威局部几何/诊断预览
|
||||
应用到工作区 -> 将有效 draft 合并为主工作区的未保存约束;主地图继续显示预览
|
||||
保存 -> 将活动副本写入持久化文档
|
||||
保存检查点 -> 冻结为不可变 revision
|
||||
取消 -> 丢弃未应用的 JunctionTools draft,恢复进入前的工作区状态
|
||||
```
|
||||
|
||||
预览必须包含所有受影响的派生对象:道路面、路口面、步行带、车道中心线、connector/movement、停止线、斑马线与标线,以及拟合失败时的诊断和最后一个有效结果。
|
||||
|
||||
## 会话边界
|
||||
|
||||
一次 `JunctionTools` 会话严格聚焦一个 `JunctionRef`。进入相邻路口前,用户必须应用或取消当前草稿;系统不允许两个路口草稿在同一个局部 solver session 内并存。已应用但未保存的编辑属于主工作区,可在主地图的普通 undo/redo 中管理。
|
||||
|
||||
## 与道路编辑的所有权
|
||||
|
||||
主地图 road editor 只拥有两个 junction reserve 之间的内部 road interval。路口两端的 reserve 在地图上可见但不可由道路区间 handle 覆盖;`JunctionTools` 独占 reserve 内的 approach width、transition、cutback 和 corner 约束。对同一进口,显式 `junction-approach` constraint 优先于道路 profile,solver 在边界自动求连续过渡。
|
||||
|
||||
## 当前阶段的延后边界
|
||||
|
||||
`JunctionTools` 会成为核心竞争力,但当前任务只设计其对象边界、会话、预览和约束合同。高级复合路口模板、多个路口联动编辑、控制设施的单对象创作、协作与全面拓扑创作均延后,避免这些问题遮蔽直接编辑基础链路的验证。
|
||||
+64
@@ -0,0 +1,64 @@
|
||||
# 可复现存盘与 OSM 重导入
|
||||
|
||||
## 问题
|
||||
|
||||
仅让最新的 `native-road-overrides.json` 跟随当前导入 OSM,会使用户无法安全比较“原始 OSM + 精修”和“新的 OSM + 重放精修”。输出 GeoJSON 又不足以解释或再次编辑场景。
|
||||
|
||||
## 建议:不可变 revision,活动工作副本
|
||||
|
||||
工作区有一个可编辑的活动副本;每个 revision 都是可重新编译、可审计的冻结快照。OSM 重导入创建新的候选 revision 或工作分支,永不原地覆盖已保存 revision。
|
||||
|
||||
```text
|
||||
工作区
|
||||
active/ 当前暂存编辑
|
||||
revisions/
|
||||
rev-0001/ 不可变的“导入基线”
|
||||
rev-0002/ 命名检查点
|
||||
rev-0003/ 基于新 OSM 的候选版本
|
||||
```
|
||||
|
||||
每个 revision 至少保存:
|
||||
|
||||
```ts
|
||||
interface RoadRevisionManifest {
|
||||
schema: 'road-workbench-revision/v1'
|
||||
id: string
|
||||
createdAt: string
|
||||
label?: string
|
||||
parentRevisionId?: string
|
||||
source: {
|
||||
osmFile: string
|
||||
osmSha256: string
|
||||
areaConfigFile: string
|
||||
areaConfigSha256: string
|
||||
}
|
||||
documents: {
|
||||
nativeRoadOverrides: string
|
||||
directEdits: string
|
||||
trafficSignals: string
|
||||
}
|
||||
compiler: {
|
||||
packageVersion: string
|
||||
gitCommit?: string
|
||||
geometrySchema: string
|
||||
}
|
||||
outputs?: { manifest: string; compiledSha256: string }
|
||||
}
|
||||
```
|
||||
|
||||
OSM、area config 和各 JSON 文档均在 revision 目录中复制,manifest 保存 digest。派生输出可作为缓存/审阅证据保存,但“复现来源”始终是输入文档和 compiler identity;恢复时应可重新编译验证 digest,并提示编译器版本差异。
|
||||
|
||||
## 对冲突体验的作用
|
||||
|
||||
- 在当前 revision 内修改 OSM 并重导入,不会破坏旧 revision 的可用性。
|
||||
- 用户可以在新 revision 上尝试约束重放并获得精确/可疑/失效状态,同时随时返回旧版本查看原效果。
|
||||
- 确认 rebase 后才将新 revision 设为活动版本;失败也不会丢失已精修场景。
|
||||
- 保存操作记录同样随 revision 冻结,便于审计;活动副本的未保存 undo/redo 不进入不可变 revision。
|
||||
|
||||
## 已确定的创建策略
|
||||
|
||||
- 导入 OSM 自动创建不可变基线 revision。
|
||||
- 用户明确执行“保存检查点”时创建带名称的不可变 revision。
|
||||
- 普通保存、草稿预览和重新编译只更新活动副本,不自动制造 revision。
|
||||
|
||||
这一策略以可审阅的检查点承载长期历史,避免把高频拖拽/保存变成难以浏览的版本噪声。
|
||||
@@ -0,0 +1,53 @@
|
||||
{
|
||||
"id": "direct-manipulation-road-editor",
|
||||
"name": "direct-manipulation-road-editor",
|
||||
"title": "直接操纵道路编辑工作台",
|
||||
"description": "探索类似 Drawtonomy 的直接操纵道路编辑,保持结构化 overrides、可审计性和可重编译性",
|
||||
"status": "completed",
|
||||
"dev_type": "feature",
|
||||
"scope": "road-editor",
|
||||
"package": null,
|
||||
"priority": "P2",
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-08-26",
|
||||
"completedAt": "2026-09-07",
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [
|
||||
"08-26-direct-edit-documents",
|
||||
"08-26-direct-edit-solver-api",
|
||||
"08-26-direct-edit-map-editor",
|
||||
"08-26-direct-edit-junction-tools",
|
||||
"08-27-junction-dominated-roads",
|
||||
"08-28-edit-interaction-polish",
|
||||
"08-28-junction-control-offsets",
|
||||
"08-28-crosswalk-element-editor",
|
||||
"08-31-parameter-panel-binding",
|
||||
"08-31-constraint-range-validation",
|
||||
"08-31-lane-maneuver-override",
|
||||
"09-02-workbench-component-boundaries"
|
||||
],
|
||||
"parent": null,
|
||||
"relatedFiles": [
|
||||
"src/compile/compiler.js",
|
||||
"src/compile/native-road.js",
|
||||
"src/compile/complex-junction.js",
|
||||
"src/compile/layer-manifest.js",
|
||||
"src/geometry/lane-geometry.js",
|
||||
"workbench/server.js",
|
||||
"workbench/client/src/App.tsx",
|
||||
"workbench/client/src/components/MapCanvas.tsx",
|
||||
"workbench/client/src/map/layers.ts",
|
||||
"workbench/client/src/lib/api.ts",
|
||||
"workbench/client/src/types/state.ts",
|
||||
"test/index.js",
|
||||
"test/fixtures.js"
|
||||
],
|
||||
"notes": "父任务:持有需求集、design.md 权威合约、跨子任务验收与第 8 步集成验证。实现落在三个子任务。",
|
||||
"meta": {}
|
||||
}
|
||||
@@ -0,0 +1,3 @@
|
||||
{"file":".trellis/spec/backend/direct-edit-api.md","reason":"检查 preview 零写入、非空约束改变正式编译输出、保存与 rebase 合同。"}
|
||||
{"file":".trellis/spec/frontend/direct-edit-client.md","reason":"检查 baseline 不被元素编辑代码写入、控件由 manifest 驱动且预览时序正确。"}
|
||||
{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"核对 feature -> element -> manifest -> constraint 的完整读写链路。"}
|
||||
@@ -0,0 +1,148 @@
|
||||
# 斑马线元素级编辑器设计
|
||||
|
||||
## 架构边界
|
||||
|
||||
本实验扩展现有直接编辑链路,而非建立画布对象存储:
|
||||
|
||||
```text
|
||||
crosswalk feature 点击
|
||||
-> elementId
|
||||
-> element manifest (anchor + parameters + legal controls)
|
||||
-> native-road-edits/v2 constraint
|
||||
-> resolveDirectEditConstraints
|
||||
-> compileControlMarkings
|
||||
-> preview / save / recompile
|
||||
```
|
||||
|
||||
`elementId` 是选择和分组标识;持久化仍使用稳定语义 anchor 上的 constraint。它不能是 GeoJSON 数组下标、屏幕坐标或临时 UUID。
|
||||
|
||||
## 选择合同
|
||||
|
||||
斑马线的每一条 stripe feature 必须包含 `native_id`、`element_id` 与可回链的 crossing / approach 身份。选择适配层只读取 `element_id`,再向服务器取得选中元素的权威 manifest。客户端不会据条带数量、空间距离或渲染顺序自行聚类。
|
||||
|
||||
元素 manifest 至少包含:
|
||||
|
||||
```ts
|
||||
interface EditableElement {
|
||||
elementId: string
|
||||
kind: 'crosswalk'
|
||||
anchor: { type: 'junction-approach'; nodeId: string; segmentId: string }
|
||||
featureIds: string[]
|
||||
controls: Array<{
|
||||
kind: 'position' | 'length' | 'width'
|
||||
value: { current: number; min: number; max: number; unit: 'meter' }
|
||||
axisAzimuth?: number
|
||||
}>
|
||||
fields: Array<{ key: string; value: number; min: number; max: number; unit: 'meter' | 'count' }>
|
||||
}
|
||||
```
|
||||
|
||||
第一阶段发布 `position` 与 `length` / `width`:位置沿用现有 `junction-crosswalk-inset`,尺寸需要新的回写规则(见「尺寸的语义」)。`rotation` **不在本任务范围**,理由见文末。
|
||||
|
||||
## `elementId` 已经存在
|
||||
|
||||
实测:48 条条带按 `crossing_node_id` 分组恰好得到 8 组、每组 6 条,且没有任何
|
||||
crossing 对应多条道路。唯一性是结构性的——`compileControlMarkings()` 的循环是
|
||||
`for (const crossing of model.crossings)`,每次迭代由单个 `crosswalkCandidate`
|
||||
产出一组。
|
||||
|
||||
因此 **`crosswalk:node/<crossingId>` 就是稳定的组标识**,无需新增编译器字段。
|
||||
条带 `native_id` 形如 `crosswalk:node/-26452:1`,组前缀直接可用;
|
||||
`crossing_node_id` 也已在 feature 属性里。
|
||||
|
||||
客户端据此分组**不构成** PRD 禁止的「按经纬度近似聚类」——它读的是已发布的稳定
|
||||
标识,不是空间猜测。
|
||||
|
||||
> 早期分析曾断言组标识缺失,理由是「同一节点的多个进口共用它」。那是把
|
||||
> **crossing 节点**(`node/-26452`,人行横道)与 **junction 节点**
|
||||
> (`node/1140799725`,路口)混为一谈了。两者不是同一个 id。
|
||||
|
||||
## `affects` 缺失仍是真问题
|
||||
|
||||
上一节不影响这一节。`junctionAffects()`(`direct-edit-solver.js:628`)构造的是
|
||||
`junctionSurfaceId + roadAffects + connectors`,**从不加入 crosswalk 或 stop-line**。
|
||||
实测在有 48 条斑马线的区域,`junction-crosswalk-inset` 手柄的 `affects` 共 59 项,
|
||||
crosswalk 为 **0**。
|
||||
|
||||
成因是求解器手上没有「进口 → crossing」的映射:该关系在编译器的
|
||||
`compileControlMarkings()` 内部由 `arrivalEndpointIds` 与距离阈值算出,从未对外发布。
|
||||
|
||||
后果限于**拖拽高亮会亮错一片**(PRD 第 2 条要求高亮受影响对象)。
|
||||
它**不阻塞选中**,因为选中走的是上一节的组标识。两者是独立的两步。
|
||||
|
||||
## 编辑与预览
|
||||
|
||||
- 选择由 `MapCanvas` 的 feature 事件产生,但选择状态由 App/编辑会话持有,不能写入 baseline source。
|
||||
- 元素控件写入的是 manifest 指定的 constraint kind/value;表单复用同一写入器。
|
||||
- 选中框和控件只是 `editHandles` / `editGhost` 层的临时 UI;权威预览仍由服务端返回,baseline source 不被客户端改写。
|
||||
- 空白点击会清除元素选择;道路选择可继续决定道路级 handle manifest。斑马线元素选中与道路选择可并存,但两组控件不得重叠或竞争同一 pointer 手势。
|
||||
|
||||
## 尺寸的语义
|
||||
|
||||
斑马线的几何目前**全是字面量**(`native-road.js:1264`):
|
||||
|
||||
```js
|
||||
rectangleAt(controlCenter, axis, across, 3, 0.45, -2.25 + index * 0.9)
|
||||
// ↑长 ↑宽 ↑偏移,共 6 条
|
||||
```
|
||||
|
||||
`rectangleAt(center, axis, across, length, width, offset)` 中 `length` 沿 `axis`
|
||||
(行车方向),`width` 沿 `across`(横跨道路)。所以:
|
||||
|
||||
| 用户看到的 | 实际是什么 | 存储形态 |
|
||||
| --- | --- | --- |
|
||||
| 进深(沿行车方向) | 每条条带的 `length`,6 条共用 | 一个数,可直接参数化 |
|
||||
| 跨度(横跨道路) | **条带数 × 间距**,非存储值 | 派生量 |
|
||||
|
||||
跨度是派生量,所以拖四角改跨度必须决定改哪个因子。**已定:固定间距、改条带数。**
|
||||
|
||||
- 条带宽 0.45m 与间隙 0.45m(间距 0.9m)在现实中是标准化的,改间距会让宽路上的
|
||||
斑马线拉得很稀,不符合任何规范。
|
||||
- 代价是跨度手柄按 0.9m **量化跳动**,不是连续的。这是语义诚实的结果,
|
||||
不是手感缺陷;UI 上必须让它看起来是有意吸附的。
|
||||
|
||||
同时修掉一个既有缺陷:**跨度恒为 5.4m,与路宽无关**。20m 宽的路上斑马线也只有
|
||||
5.4m,横不过去。参数化后默认跨度应由路宽推导,而不是写死 6 条。
|
||||
|
||||
## 选中框与抓手
|
||||
|
||||
视觉采用常规 transform gizmo:矩形虚线选框 + 四角空心方块。
|
||||
|
||||
一条硬规矩:**画几个抓手,就得有几个是活的。** 画了拖不动的四角、或转了没反应的
|
||||
旋转柄,正是 `flag.ts` 为 `profile.interval` 立下的反面教材——
|
||||
「一个拖了没效果的控件比没有控件更糟」。长得像 Figma 但只有一半能用,
|
||||
比朴素的圆点更糟,用户会当成 bug 报。
|
||||
|
||||
所以抓手随能力分批出现,而不是先画全再逐个点亮:
|
||||
|
||||
| 抓手 | 语义 | 何时出现 |
|
||||
| --- | --- | --- |
|
||||
| 虚线选框 | 纯反馈,无语义 | 第一阶段 |
|
||||
| 移动 | `junction-crosswalk-inset` | 第一阶段(语义现成) |
|
||||
| 四角方块 | 进深 / 跨度 | 第一阶段(需编译器参数化) |
|
||||
| 旋转柄 | 相对进口轴的偏转角 | **不做** |
|
||||
|
||||
## 旋转为何押后
|
||||
|
||||
`axis` 派生自 `crosswalkCandidate.placement.axis`,即进口方向。要能旋转,
|
||||
需要新增一个「相对进口轴的偏转角」constraint kind。而 `design.md` 的规矩是
|
||||
**新增 kind 的前提是几何阶段必须已经消费它**——先证明 `compileGeometry()` 读取
|
||||
该参数,再画任何手柄。
|
||||
|
||||
偏转角本身是合理的(现实中斑马线确实会相对进口斜置),且用「相对派生轴的角度」
|
||||
表达是语义化的,不违反「不持久化 transform 矩阵」。但它是独立的一轮
|
||||
编译器 + kind + 客户端工作,已明确押后。
|
||||
|
||||
## 数据演进
|
||||
|
||||
位置继续使用已有 `junction-crosswalk-inset`。尺寸需要新的持久化形态,本阶段一并落地:进深与条带数各是一个参数,跨度由 `条带数 × 间距` 派生,间距本阶段不可编辑。具体是新增专属 kind 还是扩展同一 kind 的严格 schema,在第一个门禁(进口↔组映射)通过后定,不预先固化。
|
||||
|
||||
新增任何 kind 前必须先证明 `compileGeometry()` 读它——本项目已经为 `profile.interval` 交付过一个拖了无效果的手柄。
|
||||
|
||||
缺省参数必须字节级保持现有斑马线输出。参数越界、条带间互相重叠或越过可用进口范围均返回 blocking diagnostic,不在客户端静默钳制真实约束。
|
||||
|
||||
## 兼容与回滚
|
||||
|
||||
- 无新 constraint 时,编译输出与当前版本一致。
|
||||
- `directEdit` 关闭时不请求 element manifest、不安装元素选择交互、不产生额外图层。
|
||||
- 第一阶段每个步骤独立提交;回滚元素 UI 或 manifest 不影响既有道路级控制。
|
||||
@@ -0,0 +1,6 @@
|
||||
{"file":".trellis/spec/backend/direct-edit-api.md","reason":"元素 manifest、preview 和持久化必须继续满足直接编辑的服务端合同。"}
|
||||
{"file":".trellis/spec/frontend/direct-edit-client.md","reason":"元素选择、临时控件与表单必须保持 handle/ghost/preview 图层所有权;§11-14 定义了输入通道汇合点、夹值/拒绝分工与聚焦期文本所有权。"}
|
||||
{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"feature 属性、element manifest、constraint schema 与客户端选择状态跨越编译器、API 和 UI。"}
|
||||
{"file":".trellis/spec/guides/code-reuse-thinking-guide.md","reason":"元素控件必须接既有 draftValue/settleValue/abandonGesture,禁止新建第二条预览或 undo 链路。"}
|
||||
{"file":".trellis/tasks/08-26-direct-manipulation-road-editor/design.md","reason":"继承 v2 语义约束、坐标分层、预览和 revision 的权威合同,以及新增 kind 前必须先证明几何阶段消费它的规矩。"}
|
||||
{"file":".trellis/tasks/08-31-parameter-panel-binding/design.md","reason":"参数表单那一半的既有实现与三个通道无关出口的契约。"}
|
||||
@@ -0,0 +1,134 @@
|
||||
# 实施计划
|
||||
|
||||
顺序按**风险递减**排列:每一步都有可独立验证的门禁,失败即停,不进入下一步。
|
||||
|
||||
数据前提:`nantaizihu-9PTsZg`(由桌面 `南台子湖创新谷OSM.osm` 导入)含 10 个
|
||||
`highway=crossing` 节点、8 组 zebra,编译出 48 条斑马线与 8 条停止线。
|
||||
不带 crossing 的 OSM 无法验证本任务任何一步。
|
||||
|
||||
## 0. 建立事实与测试夹具
|
||||
|
||||
- 追踪 `compileControlMarkings()` 的每条 stripe 属性、`native_id` 构成,以及从地图点击到 `onFeature` 的路径。
|
||||
- 添加失败优先的测试:同组 stripe 需要稳定共享 `elementId`,不同 crossing 不得共享;空编辑输出与基线字节一致。
|
||||
- 门禁:能证明一个具体 feature 无歧义回链到一个 junction approach 和 crossing。
|
||||
|
||||
## 1. 元素选择(纯客户端)
|
||||
|
||||
`design.md` 已实测确认 `crosswalk:node/<crossingId>` 就是稳定组标识,
|
||||
条带属性里已有 `crossing_node_id`。**本步不需要改编译器。**
|
||||
|
||||
- 客户端建立 `ElementSelection` 纯状态:从 feature 属性推出组标识,不做空间聚类。
|
||||
- 点击任一条带选中整组、点空白清除;选择状态由 App / 编辑会话持有,不写 baseline source。
|
||||
- 元素选中与道路选择可并存,但两组控件不得竞争同一 pointer 手势。
|
||||
- 验证:客户端 selection 单元测试(同组共享、跨组不共享、重编译后稳定)。
|
||||
- **门禁**:一个具体 feature 无歧义回链到一个组,且组内条带数与编译输出一致。
|
||||
|
||||
## 2. 选中框与移动
|
||||
|
||||
- 渲染矩形虚线选框(框住整组 6 条)+ 移动抓手,接已有 `junction-crosswalk-inset`。
|
||||
- 控件走 `App.tsx` 既有的三个出口 `draftValue()` / `settleValue()` / `abandonGesture()`,**不新建第二条预览或 undo 链路**(见 `.trellis/spec/frontend/direct-edit-client.md` §11)。
|
||||
- 安装时不得影响道路 handle 的 hit-test。
|
||||
- **门禁**:一次非空元素编辑可在正式重编译结果中观察到斑马线位置变化。只交付 UI 不算通过。
|
||||
|
||||
## 3. 修正 `affects`(服务端)
|
||||
|
||||
独立于第 1 步——选中不依赖它,但拖拽高亮依赖。
|
||||
|
||||
- 求解器建立并消费「进口 → crossing」映射,使 `junctionAffects()` 不再遗漏 crosswalk。
|
||||
该关系目前只存在于 `compileControlMarkings()` 内部(`arrivalEndpointIds` + 距离阈值)。
|
||||
- 验证:API 测试。
|
||||
- **门禁**:`junction-crosswalk-inset` 手柄的 `affects` 必须包含它实际移动的那 6 条 crosswalk feature。当前实测为 0。
|
||||
|
||||
## 4. 编译器尺寸参数化
|
||||
|
||||
斑马线几何目前全是字面量(`native-road.js:1264`:长 3m、宽 0.45m、间距 0.9m、6 条)。
|
||||
|
||||
- 进深与条带数成为参数;间距本阶段固定 0.9m 不可编辑;跨度 = 条带数 × 间距,派生。
|
||||
- 默认跨度由路宽推导,修掉「跨度恒为 5.4m 与路宽无关」的既有缺陷。
|
||||
- 无约束时输出与当前版本**字节级一致**(除上述默认跨度修正外,该修正需单独记录并更新基线)。
|
||||
- 越界、条带重叠、超出可用进口范围返回 blocking diagnostic。
|
||||
- **门禁**:先证明 `compileGeometry()` 读取新参数,再画任何抓手。这条规矩来自
|
||||
`profile.interval` 那次教训——求解器写了、几何阶段没读、交付了一个拖动无效果的手柄。
|
||||
|
||||
## 5. 四角尺寸抓手
|
||||
|
||||
- 四角空心方块:一轴改进深(连续),一轴改跨度(按 0.9m 量化吸附)。
|
||||
- 量化必须看起来是有意吸附,不能像卡顿。
|
||||
- 表单与抓手写同一组元素参数,值、单位、范围、诊断一致。
|
||||
- **门禁**:画出来的每个抓手都必须是活的。宁可少画,不可画死的
|
||||
(`direct-edit-client.md` 的 `intervalEditingSupported` 先例)。
|
||||
|
||||
## 6. 复盘
|
||||
|
||||
- 手测:选中、取消、道路级手柄共存、移动钳位、尺寸吸附、表单校验、保存重载、撤销/重做。
|
||||
- 记录哪些结论可推广到停止线/箭头,哪些**不可**——斑马线只改位置与自身尺寸,
|
||||
不改路口形状;`approach-width` / `cutback` / `corner-radius` 是另一个几何类别,
|
||||
本实验不为它们背书(见 `prd.md` 的「试验对象的覆盖边界」)。
|
||||
|
||||
## 明确不做
|
||||
|
||||
- 旋转。需要新增「相对进口轴偏转角」constraint kind 且编译器先消费它,已决定押后。
|
||||
- 条带间距编辑。
|
||||
- 推广到停止线、箭头、信号灯。
|
||||
|
||||
## 验证命令
|
||||
|
||||
```sh
|
||||
npm run format:check
|
||||
npm run test
|
||||
npm run test:client
|
||||
npm run test:client:unit
|
||||
npm run build
|
||||
```
|
||||
|
||||
## 风险文件
|
||||
|
||||
- `src/compile/native-road.js`:斑马线生成与默认输出兼容性;尺寸参数化会动到基线快照。
|
||||
- `src/compile/direct-edit-solver.js`:`junctionAffects()` 是第 1 步的核心;element manifest 与 handle manifest 不得互相污染。
|
||||
- `src/compile/native-road-edits.js`:新增 kind 或扩展 schema 时校验必须同步。
|
||||
- `workbench/server.js`:element manifest 查询与 preview 不得写入磁盘。
|
||||
- `workbench/client/src/App.tsx`、`edit/`、`components/`:元素控件必须接既有三出口;选中框是临时 UI,不得写 baseline layer。
|
||||
- `test/fixtures.js`:默认跨度改由路宽推导会改动 fixture 基线,需显式更新而非静默接受。
|
||||
|
||||
---
|
||||
|
||||
## 交付进度(2026-08-31)
|
||||
|
||||
| 步骤 | 状态 |
|
||||
| --- | --- |
|
||||
| 0 建立事实与测试夹具 | ✅ |
|
||||
| 1 元素选择 | ✅ `edit/element.ts`,浏览器已确认;已推广到停止线 |
|
||||
| 2 选中框与移动 | ✅ 虚线框可直接拖拽 |
|
||||
| 3 修正 `affects` | ⏸ 暂缓——客户端从不读 `affects`,高亮未实现,单独修不可见。应与高亮作为一件事做 |
|
||||
| 4 编译器尺寸参数化 | ✅ `junction-crosswalk-size`,门禁已过,基线已更新 |
|
||||
| 5 四角尺寸抓手 | ⬜ 未开始,见下方设计难点 |
|
||||
| 6 复盘 | 部分:推广分析见 `research/generalising-to-other-markings.md` |
|
||||
|
||||
第 1–2 步之外另修了两处既有缺陷:`MapCanvas` 的陈旧闭包与空白点击不上报,
|
||||
以及 `junction-crosswalk-inset` 的上界(44%~88% 死区,见
|
||||
`08-31-parameter-panel-binding/research/manifest-range-vs-solver.md`)。
|
||||
|
||||
手测确认:选中、虚线框、拖拽均可用。**尚未手测**:框跟随修复后的表现、
|
||||
上界修复后的拖拽手感——两者都需重启工作台进程才能生效。
|
||||
|
||||
## 第 5 步的设计难点(未解决)
|
||||
|
||||
`junction-crosswalk-size` 的值是**一对数** `{ depthMeters, stripeCount }`,
|
||||
而拖拽链路是标量的:`projectHandleValue` 产出一个数,`constraintValueFor`
|
||||
把它包成一个 value。四角抓手需要两个自由度:
|
||||
|
||||
- 一轴改进深(连续,米)
|
||||
- 一轴改跨度(量化,写回 `stripeCount`)
|
||||
|
||||
拖其中一个必须**保留另一个的当前值**,否则每次拖拽都会把未触碰的那半重置为默认。
|
||||
可行方向(未定):
|
||||
|
||||
1. 发两个标量手柄,`draftFor` 在构造 value 时与已有约束合并
|
||||
2. 扩展 `EditHandle` 表达多分量,改动面更大
|
||||
3. 元素控件不走 `draftFor`,自己构造 value——**违反「两条通道汇合于同一出口」**,不推荐
|
||||
|
||||
方向 1 最小,但需要 `draftFor` 能读到该约束的当前值;目前它只从 handle 拿标量。
|
||||
动手前应先定这个,否则会长出第二条 draft 路径。
|
||||
|
||||
另:`junction-crosswalk-size` 已加入 `JUNCTION_KINDS` 但**不在** `CONTROL_KINDS`,
|
||||
所以参数面板不渲染它——它的值是一对数,而面板渲染标量。接入抓手时一并处理。
|
||||
@@ -0,0 +1,83 @@
|
||||
# 斑马线元素级编辑器实验
|
||||
|
||||
## 目标
|
||||
|
||||
验证“元素级编辑器”能取代只显示固定道路参数手柄的交互:用户点击一组斑马线的任一条带后,整组进入选中状态,地图显示该元素的编辑控件,参数表单与地图操作都能预览、保存和撤销同一份结构化编辑。
|
||||
|
||||
斑马线是实验对象,实验通过后才抽象和推广到停止线、箭头、信号灯等元素。
|
||||
|
||||
## 已确认的事实
|
||||
|
||||
- 当前 `junction-crosswalk-inset` 只改变斑马线相对路口的位置;控制手柄属于被选道路的进口,而非具体斑马线。
|
||||
- `compileControlMarkings()` 为一组斑马线生成多条 `crosswalk` GeoJSON feature;每条 feature 的属性目前不足以作为稳定的组级编辑目标。
|
||||
- 浏览器已有 `EditSession`、服务端权威 preview、保存、重编译与撤销链路。编辑数据必须保持语义约束,不得保存派生 GeoJSON 或屏幕坐标。
|
||||
- 当前普通道路级手柄仍服务于横断面参数,不应与元素级选择共用或互相覆盖。
|
||||
- `08-31-parameter-panel-binding` 已交付参数表单那一半:`ParameterPanel` 组件、`edit/parameter.ts` 的文本↔数值/范围判定/单位换算,以及 `App.tsx` 中通道无关的三个出口 `draftValue()`(预览)、`settleValue()`(提交一步 undo)、`abandonGesture()`(放弃)。元素级控件应接入同一组出口,**不要新建第二条预览或 undo 链路**。
|
||||
|
||||
## 范围
|
||||
|
||||
### 第一阶段:元素选择与位置闭环
|
||||
|
||||
1. 点击任意一条斑马线条带,选中整组斑马线;点击空白处或另一道路元素清除或切换选择。
|
||||
2. 后端为每组斑马线发布稳定 `elementId`、元素类型、语义锚点、可编辑参数与受影响 feature ID;客户端不得由 feature 数组位置猜测分组。
|
||||
3. 选中后显示轻量的元素级编辑状态,至少有位置控制;移动只允许沿该进口定义的合法轴和范围,钳位来自服务端 manifest。
|
||||
4. 位置控制和参数表单共同更新既有 `junction-crosswalk-inset` 约束,并复用 preview、保存、撤销与重编译链路。
|
||||
5. 表单显示当前值、单位、合法范围和阻塞性诊断;修改后更新地图预览,保存后重新编译仍为 `exact`。
|
||||
|
||||
### 第二阶段:尺寸与外观闭环(本任务内设计、第一阶段通过后实施)
|
||||
|
||||
1. 选中框提供与斑马线语义相符的长度/宽度调整,不写自由像素缩放。
|
||||
2. 表单可修改斑马线长度、宽度、条带数量和条带间距;地图控件与表单写同一结构化元素参数。
|
||||
3. 编译器消费这些参数生成整组条带,并对不合法组合返回阻塞诊断。
|
||||
|
||||
## 明确不做
|
||||
|
||||
- 不实现通用的任意旋转、自由二维移动、任意缩放或把 transform 矩阵持久化。
|
||||
- 不编辑多组斑马线,不跨进口/跨路口拖放,不改变 OSM 中心线或路口拓扑。
|
||||
- 不在本任务中推广停止线、箭头或信号灯;不提前建立“所有元素”的大而全抽象。
|
||||
- 不移除或改变道路横断面、路口 shape 的现有手柄和所有权。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] 点击一条条带后,整组条带显示为同一选中元素;切换到另一组或空白处时状态正确更新。
|
||||
- [ ] `elementId` 在同一输入、重编译、保存和重新加载后稳定;同组条带共享一个 ID,不同斑马线不共享。
|
||||
- [ ] 移动控件与表单修改位置时,预览只更新该元素及其声明的受影响层;无效输入保留最后一个有效预览并显示诊断。
|
||||
- [ ] 保存、刷新、重新编译后位置不回退,相关约束状态为 `exact`;未保存编辑可以撤销/重做。
|
||||
- [ ] 第二阶段完成后,长度/宽度/条带数量/间距能从表单和地图控件一致地更新,非法尺寸或间距被拒绝而非静默修复。
|
||||
- [ ] 现有道路级手柄仍可独立工作,且未选中斑马线时不显示元素编辑 UI。
|
||||
- [ ] `npm run format:check`、`npm run test`、`npm run test:client`、`npm run test:client:unit`、`npm run build` 通过。
|
||||
|
||||
## 风险与门槛
|
||||
|
||||
- 第一阶段必须先证明 feature -> element -> semantic anchor 的稳定回链,以及非空约束确实改变正式编译输出;两者任一失败时停止,不进入尺寸和外观参数。
|
||||
- 选中框是交互反馈,不能成为第二个几何模型;所有位置、范围和尺寸的权威值由后端 element manifest 给出。
|
||||
- 当前地图 feature 的属性可能缺少足以识别 crossing 的稳定字段。需要先通过编译器补充,不可在客户端按经纬度近似聚类。
|
||||
|
||||
### 试验对象的覆盖边界(2026-08-31 决定)
|
||||
|
||||
本任务的上游动机是**为复杂路口做前置**:普通四岔口已有 20 个手柄分属 4 条 segment,
|
||||
主地图一次只显示当前选中 segment 的手柄,要看全一个路口需依次选中 4 条道路。
|
||||
每参数一个圆点的模型撑不到复杂路口,元素级选中是必需品而非优化。
|
||||
|
||||
已明确决定:**第一次试验只做斑马线,不并入形状类元素**,以控制风险。
|
||||
|
||||
代价必须记录在案——斑马线是**位置类**元素,`design.md` 明确「不改变路口形状,
|
||||
只移动标线,因此不触发路口边界重算」。而复杂路口真正难的是
|
||||
`junction-approach-width` / `junction-cutback` / `junction-corner-radius`:
|
||||
它们改变路口多边形本身,涉及边界连续、面自交、cutback 处截面衔接。
|
||||
|
||||
因此:
|
||||
|
||||
- 本试验通过 **只证明**「选中 + 位置编辑」这条链路可行。
|
||||
- 它 **不证明** 形状类元素的元素级编辑可行,那是另一个几何类别。
|
||||
- 推广到形状类元素前必须单独验证,不得以本试验的结论替代。
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] TBD
|
||||
|
||||
## Notes
|
||||
|
||||
- Keep `prd.md` focused on requirements, constraints, and acceptance criteria.
|
||||
- Lightweight tasks can remain PRD-only.
|
||||
- For complex tasks, add `design.md` for technical design and `implement.md` for execution planning before `task.py start`.
|
||||
+84
@@ -0,0 +1,84 @@
|
||||
# 元素模型能推广到哪些标线
|
||||
|
||||
日期:2026-08-31
|
||||
来源:`08-28-crosswalk-element-editor` 第 1–2 步交付后,对 `nantaizihu-9PTsZg` 的实测。
|
||||
|
||||
## 各元素的分组结构(实测)
|
||||
|
||||
| 图层 | provenance | 分组键 | feature | 组数 | 每组大小 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| `crosswalks` | `native-road-crosswalk/v1` | `crossing_node_id` | 48 | 8 | 恒 6 |
|
||||
| `vehicleStopLines` | `native-road-stop-line/v1` | `crossing_node_id` | 8 | 8 | 恒 1 |
|
||||
| `turnArrows` | `native-road-turn-arrow/v1` | `lane_id` + `maneuver` | 108 | 28 | 3 或 5 |
|
||||
| `directionArrows` | `native-road-direction-arrow/v1` | `lane_id` | 324 | 50 | 2~28 |
|
||||
| `laneSeparators` | `native-road-lane-separator/v1` | `road_id` + 车道对 | 731 | 9 | 26~230 |
|
||||
|
||||
## 关键陷阱:斑马线与停止线共用 `crossing_node_id`
|
||||
|
||||
交集 **8/8**——两者由同一个 `controlFeature()` 构造,`crossing_node_id` 完全重合。
|
||||
只按该字段分组会把一组斑马线和它的停止线并成一个"元素"。
|
||||
|
||||
**必须先按 `provenance` 判类型,再取分组键。** `element.ts` 已如此实现并有测试守着
|
||||
(`rejects a stop line, which shares the same feature builder`)。任何推广都不能绕过这一步。
|
||||
|
||||
## 可编辑性就绪度
|
||||
|
||||
| 元素 | 约束 kind | 编译器是否消费 | 实测响应 | 成本 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 斑马线 | `junction-crosswalk-inset` | ✅ | 已修正上界,全程有效 | **已完成** |
|
||||
| 停止线 | `junction-stop-line-offset` | ✅ | **全程线性,零死区** | **几乎免费** |
|
||||
| 转向箭头 | ❌ 无 | ❌ | — | 新 kind + 编译器 |
|
||||
| 方向箭头 | ❌ 无 | ❌ | — | 新 kind + 编译器 |
|
||||
| 车道分隔线 | v1 overrides,仅样式 | 仅样式 | 位置不可编辑 | 另一类问题 |
|
||||
|
||||
停止线实测:offset `0.5 → 126` 位移 `0 → 125.36m`,增量始终 1:1。
|
||||
**没有斑马线那种死区**,可以直接接入。
|
||||
|
||||
但它有反向的毛病:声明范围 `[0.5, 126.28]`(`approach.length * 0.45`),
|
||||
允许把停止线推到离路口 126 米——而 `native-road.js` 有
|
||||
`STOP_LINE_MAX_APPROACH_DISTANCE_METERS = 25`。范围过宽同样是缺陷,
|
||||
见 `.trellis/spec/backend/direct-edit-api.md` §12。
|
||||
|
||||
## 值得建立的抽象(仅此而已)
|
||||
|
||||
一个按 provenance 索引的小注册表:
|
||||
|
||||
```ts
|
||||
interface ElementSpec {
|
||||
provenance: string;
|
||||
kind: ElementKind;
|
||||
groupKey(properties: Record<string, unknown>): string | null;
|
||||
constraintKind: ConstraintKind;
|
||||
}
|
||||
```
|
||||
|
||||
`element.ts` 现有的 `crosswalkElementIdOf` / `groupMembers` / `elementSelectionFor`
|
||||
改为查表即可,选中、选框、拖拽三条链路无需改动。
|
||||
|
||||
**不要**据此建立"所有元素"的通用协议——PRD 明确禁止
|
||||
(「不提前建立『所有元素』的大而全抽象」)。理由在上表里:
|
||||
分组键的形态各不相同(单字段 / 双字段 / 派生),
|
||||
每组大小从 1 到 230,箭头类连约束 kind 都还不存在。
|
||||
现在能证明的只有「provenance + 分组键 → 组」这一条,注册表恰好只承诺这一条。
|
||||
|
||||
## 推荐顺序
|
||||
|
||||
1. **停止线**——注册表 + 一条 spec 条目。约束现成、编译器已消费、响应已验证。
|
||||
同时暴露注册表是否够用:它的每组只有 1 个 feature,而斑马线是 6 个,
|
||||
能验证分组逻辑不依赖"多 part"这个偶然属性。
|
||||
2. **修 `affects`**(原第 3 步)——目前 `junctionAffects()` 不含任何标线,
|
||||
拖拽高亮会亮错一片。停止线接入后这个问题会更明显。
|
||||
3. **转向箭头**——需要新 constraint kind,且必须先证明 `compileGeometry()` 读它。
|
||||
分组键 `lane_id + maneuver` 已验证(28 组,每组 3 或 5 个 part)。
|
||||
4. **方向箭头**——最贵。分组语义本身待定:按 `lane_id` 是 50 组(编辑间距/整体偏移),
|
||||
按 `lane_id + sequence` 是 324 组(逐个箭头独立摆放)。
|
||||
这是产品决策,不是实现细节,需先定。
|
||||
5. **车道分隔线**——不同类问题。已有 v1 样式 override,缺的是位置,
|
||||
而位置由 `road-lane-divider` 约束管,属道路横断面而非元素级。
|
||||
|
||||
## 与复杂路口的关系
|
||||
|
||||
停止线和转向箭头都是**位置类**元素,与斑马线同属一个几何类别:
|
||||
移动它们不改变路口多边形。所以第 1、3 步不会为形状类元素
|
||||
(`approach-width` / `cutback` / `corner-radius`)提供任何背书——
|
||||
那仍是独立的、未验证的一类,见 `prd.md`「试验对象的覆盖边界」。
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "crosswalk-element-editor",
|
||||
"name": "crosswalk-element-editor",
|
||||
"title": "斑马线元素级编辑器实验",
|
||||
"description": "",
|
||||
"status": "completed",
|
||||
"dev_type": null,
|
||||
"scope": null,
|
||||
"package": null,
|
||||
"priority": "P2",
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-08-28",
|
||||
"completedAt": "2026-09-07",
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": "08-26-direct-manipulation-road-editor",
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {}
|
||||
}
|
||||
@@ -0,0 +1,3 @@
|
||||
{"file":".trellis/spec/backend/direct-edit-api.md","reason":"质量检查需覆盖 preview/save 的版本保护、原子写入及编译状态一致性。"}
|
||||
{"file":".trellis/spec/frontend/direct-edit-client.md","reason":"质量检查需确认 preview layer、baseline 和普通路口编辑行为不回归。"}
|
||||
{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"质量检查需验证候选配置从 API 到编译和 UI 的完整往返。"}
|
||||
@@ -0,0 +1,26 @@
|
||||
# 技术设计
|
||||
|
||||
## 边界
|
||||
|
||||
- 编译层复用 `src/compile/complex-junction.js` 与 `src/compile/native-road.js` 的既有 cluster 几何生成逻辑,不复制几何算法。
|
||||
- 服务层负责读取候选、生成目标 cluster 配置、预览编译和持久化;保存遵守现有 revision/document 版本保护与原子写入约束。
|
||||
- 前端只在 JunctionTools 独立页面消费候选和 cluster 状态,复用现有地图图层工厂与预览层,不污染普通路口 baseline。
|
||||
|
||||
## 数据流
|
||||
|
||||
1. `/api/edit-state` 或现有诊断数据提供候选 cluster 标识、节点集合、道路摘要、建议核心半径及当前启用状态。
|
||||
2. 独立页面展示状态;用户点击启用后创建内存 draft,不立即写文件。
|
||||
3. 预览请求携带 draft cluster 配置,服务端在临时编译上下文中生成局部复杂路口图层并返回 preview 序列号。
|
||||
4. 放弃丢弃 draft 并恢复 baseline;保存经版本校验后原子写入 `nativeRoad.junctionTemplates.clusters`,随后触发正式编译。
|
||||
5. 刷新重新从 edit-state/编译状态读取持久化配置。
|
||||
|
||||
## 兼容性与回滚
|
||||
|
||||
- 没有启用配置时保持现有普通路口输出字节和交互不变。
|
||||
- 保存失败或版本冲突不改变活动配置;预览失败只清除预览并保留 draft 可重试。
|
||||
- 不把候选诊断直接转换为启用配置,避免大范围几何变化。
|
||||
|
||||
## 取舍
|
||||
|
||||
- 首版只提供独立页面入口,避免主地图状态同步和误操作复杂度。
|
||||
- 首版复杂参数只读,先验证渲染质量;后续再以独立约束模型开放编辑。
|
||||
@@ -0,0 +1,4 @@
|
||||
{"file":".trellis/spec/backend/direct-edit-api.md","reason":"复用现有预览、版本校验、原子保存和编译后状态契约。"}
|
||||
{"file":".trellis/spec/frontend/direct-edit-client.md","reason":"保证复杂路口预览不覆盖 baseline,并沿用 JunctionTools 的状态与预览边界。"}
|
||||
{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"该功能跨编译、服务和前端,需要按数据流和契约检查。"}
|
||||
{"file":".trellis/spec/guides/code-reuse-thinking-guide.md","reason":"候选状态、预览图层和保存逻辑必须复用现有实现,避免第二套契约。"}
|
||||
@@ -0,0 +1,16 @@
|
||||
# 执行清单
|
||||
|
||||
1. 梳理现有候选诊断、cluster 配置读取、编辑保存和编译入口,确定最小 API 接口。
|
||||
2. 后端增加候选 cluster 状态投影及 preview/save 所需的专用数据契约,复用现有版本校验和原子保存。
|
||||
3. 前端在独立 JunctionTools 页面增加普通/复杂状态区、启用、预览、放弃、保存和只读提示。
|
||||
4. 接入局部复杂路口图层预览,确保 baseline 图层不被覆盖,且只影响目标 cluster。
|
||||
5. 为候选样本补充后端单测、HTTP 集成测试和前端/E2E 状态流测试。
|
||||
6. 运行类型检查、构建、相关测试和完整质量检查;修复回归后再提交。
|
||||
|
||||
验证命令:
|
||||
|
||||
- `python3 ./.trellis/scripts/task.py validate 09-04-complex-junction-toggle`
|
||||
- `npm run test`
|
||||
- `npm run build`
|
||||
|
||||
回滚点:API 契约、cluster 配置写入、JunctionTools 状态区和 preview 图层分别可独立回退;不得回退用户已有的普通路口编辑修复。
|
||||
@@ -0,0 +1,44 @@
|
||||
# 复杂路口手动切换与独立浏览
|
||||
|
||||
## Goal
|
||||
|
||||
让用户可以针对 `枫树二路.osm` 中的复杂路口候选,在独立 JunctionTools 页面中将该候选从普通路口渲染切换为 `complex-junction-v1`,通过局部预览确认效果,并可放弃或保存。首版解决复杂路口当前普通渲染难看的问题,同时保留普通路口既有编辑能力。
|
||||
|
||||
## Background and Confirmed Facts
|
||||
|
||||
- `/Users/que01/Desktop/枫树二路.osm` 当前编译会产生多组 `complex-junction-candidate` 诊断。
|
||||
- 首个验证候选为节点 `8005332807、8024512135、8024512145、8024512147、8613058676`,节点直径约 41.2m,建议核心半径约 32m,关联道路为硃山湖大道、枫树二路。
|
||||
- 复杂路口几何由 `src/compile/complex-junction.js` 生成;只有 `nativeRoad.junctionTemplates.enabled=true` 且存在对应 cluster 配置时才会启用。
|
||||
- `cluster` 当前在 `src/compile/direct-edit-solver.js` 与 JunctionTools 中为只读,不能通过解除前端限制直接编辑。
|
||||
- 候选检测是 advisory,只产生 `complex-junction-candidate` 诊断,不会自动改变几何。
|
||||
|
||||
## In Scope
|
||||
|
||||
1. 候选复杂路口可进入独立 JunctionTools 页面。
|
||||
2. 页面显示当前渲染模式:普通路口或复杂路口;普通模式提供“启用复杂路口渲染”入口。
|
||||
3. 切换使用候选诊断提供的 cluster 节点和建议核心半径,并只影响该 cluster。
|
||||
4. 切换后提供局部复杂路口几何预览,支持放弃、保存;保存后重新编译,刷新仍保持状态。
|
||||
5. 复杂路口页面保持只读参数状态,并明确提示首版暂不支持复杂路口几何拖拽编辑。
|
||||
6. 切换入口只放在独立页面状态区,不在主地图候选标记上提供快捷切换。
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- 不根据候选自动启用或静默切换。
|
||||
- 不开放复杂路口核心半径、进口宽度、收口距离、圆角等拖拽编辑。
|
||||
- 不修改 OSM 拓扑,不创建或删除道路、信号灯、斑马线、停止线等设施。
|
||||
- 不跨多个 cluster 联合编辑。
|
||||
- 不改变普通路口现有 JunctionTools 行为。
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] 从 `枫树二路.osm` 的目标候选可进入独立 JunctionTools 页面。
|
||||
- [ ] 页面明确显示“当前按普通路口渲染”,并提供“启用复杂路口渲染”。
|
||||
- [ ] 预览只改变目标 cluster 的局部几何,其他路口保持不变。
|
||||
- [ ] 放弃后恢复普通路口渲染;保存并刷新后仍显示复杂路口渲染。
|
||||
- [ ] 复杂路口页面不显示可编辑普通 node 控件,未实现的参数编辑明确为只读。
|
||||
- [ ] 普通路口既有测试、复杂路口相关测试、类型检查和构建通过。
|
||||
|
||||
## Risks and Deferred Decisions
|
||||
|
||||
- 复杂 cluster 配置写入现有 `nativeRoad.junctionTemplates.clusters` 语义;若现有保存 API 不能原子更新该配置,需要在 API 层增加最小专用操作,不能从前端直接写派生 GeoJSON。
|
||||
- 自动识别和自动切换留待首版验证后另行商议。
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "complex-junction-toggle",
|
||||
"name": "complex-junction-toggle",
|
||||
"title": "复杂路口手动切换与独立浏览",
|
||||
"description": "",
|
||||
"status": "completed",
|
||||
"dev_type": null,
|
||||
"scope": null,
|
||||
"package": null,
|
||||
"priority": "P2",
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-09-04",
|
||||
"completedAt": "2026-09-07",
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": null,
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {}
|
||||
}
|
||||
Reference in new issue
Block a user