docs(tasks): plan junction tools delivery

This commit is contained in:
que01 committed 2026-09-03 12:28:47 +08:00
1 parent 6a0736517f
commit 8c99bb7340
14 files changed
+211 -60

No files matched your search

@@ -1,21 +1,34 @@
# 设计
# 总体设计
技术合约不在本文重复定义。权威定义见父任务 `.trellis/tasks/08-26-direct-manipulation-road-editor/design.md` 的以下小节:
## 边界
- 「约束模型」— `junction-approach-width`、`junction-cutback`、`junction-corner-radius` 三个 kind 与其锚点。
- 「编辑所有权」— junction reserve 独占、`junction-approach-width` 优先于道路 profile、单 `JunctionRef` 会话。
- 「Handle manifest」— 手柄字段与 `reserves`。
- 「预览时序与延迟预算」— 防抖、`previewSeq` 仲裁、`degraded`。
- 「上线与回滚形态」— `directEdit` 开关。
`JunctionTools` 是主地图之外的局部编辑器。主地图只负责显示派生热区和进入入口;编辑器负责一个 `JunctionRef` 的上下文、草稿、预览、应用、保存和取消。
会话状态、四态语义与所有权边界的完整推导见父任务 `research/junction-tools.md`。
## 数据流
## 本子任务的局部决定
`compiled model/junctionPlans` → `junction descriptors` → `hotspot layer` → `JunctionRef` → `junction session` → `semantic constraints` → `/api/edit-preview` → affected layers → apply/save → active document/revision。
- 工作区是独立路由,不是主地图上的浮层面板:路口编辑是高密度局部操作,叠在主地图上会与道路手柄争夺命中区。
- 复用 `direct-edit-map-editor` 的 `EditSession`、ghost/preview source 与命令栈,不新建第二套编辑基础设施。差异只在加载的上下文范围与可用 kind。
- 草稿属于活动工作副本的 session,不是独立导出文件。因此「取消」只需丢弃 session,不涉及文件回滚。
- 「应用到工作区」不写盘:合并后的约束是活动副本的未保存状态,交给主地图的普通 undo/redo 管理。这样保存路径只有一条。
- 会话互斥用显式守卫实现:存在未处理草稿时切换 `JunctionRef` 直接拒绝并提示,不做自动应用或自动丢弃——两者都会让用户丢失意图。
- 本期只实现 `JunctionRef.type === 'node'`。`cluster` 分支保留类型但入口置灰,避免把 cluster 降级成多个互相冲突的普通路口编辑。
- 单个角部圆角:本期只允许编辑一个 corner,多角部批量编辑属后续任务。
热区是派生显示对象,不新增持久化 schema。node 使用 node id,cluster 使用 cluster id 加 arm/corner 锚点。所有长度使用米,位置锚定 station 或 OSM node。
## 编辑器分层
- `junction-detection`:纯逻辑识别 descriptor、状态和热区几何。
- `junction-workspace`:路由、上下文加载、session 四态和主地图返回。
- `junction-solver`:把 node/cluster 约束归一为 effective plan,供普通与复杂几何共同消费。
- `junction-facilities`:设施联动、诊断汇总和发布前检查。
- OpenLayers 仅作为显示/输入 adapter,不能直接写正式编译 source。
## 首期决策约束
- `JunctionRef` 首期只允许 `type: 'node'` 进入可编辑 session;`cluster` 和 `candidate` descriptor 可展示但不可写入。
- 工作区与主地图共享 undo/redo 栈;一次“应用到工作区”是一个历史边界,拖拽过程只产生 draft/preview。
- 工作区离开由显式守卫控制:有未处理草稿时必须应用、放弃或取消离开;不得静默处理草稿。
- 保存请求必须携带打开时的文档/编译版本。版本不一致返回冲突,保留本地草稿,不做强制覆盖或隐式 rebase。
- 阶段 B 的求解写入仅覆盖三种既有 junction constraint;车道、connector 和设施在此阶段只作为派生上下文与诊断输入。
- 设施编辑只允许修改已有设施的语义 override,不新增或删除设施身份。
- 诊断接口必须提供稳定 `code` 和 `severity`,几何非法为 `blocking`,非致命设施问题可为 `warning`。
- JunctionTools 通过独立路由承载 `JunctionRef`,路由变化不得重建 `MapCanvas`,返回时恢复主地图视角和选择快照。
## 兼容与回滚
阶段 A/B 可挂在现有编辑开关下;未进入 JunctionTools 时主地图行为不变。cluster 几何统一前不得开放 cluster 写入。任何阶段失败都可回退到只读热区或现有普通路口编辑,不影响 v1 overrides、v2 文档和导出包。
@@ -1,41 +1,10 @@
# 实施计划
# 执行计划
对应父任务 `implement.md` 的第 7 步。每步一个提交,门禁不过就停。
1. 完成 RoadRunner 对标和本项目需求基线,冻结术语、范围、验收。
2. 实现纯逻辑 junction descriptor 与热区显示;普通 node 可进入,candidate/cluster 状态明确。
3. 建立独立 JunctionTools 路由与上下文快照,闭合 draft/apply/save/cancel 和返回主地图。
4. 统一 node/cluster 的 effective junction plan,让宽度、cutback、圆角真正驱动同一套几何预览。
5. 接入车道、connector、斑马线、停止线、信号灯的联动诊断和发布校验。
6. 运行全量服务端、客户端、E2E、导出契约测试,完成用户复核后再提交。
前置:`direct-edit-solver-api`(junction 三个 kind 的求解与预览端点)与 `direct-edit-map-editor`(`EditSession`、ghost/preview source、命令栈)均已交付。
## 1. 工作区路由与上下文加载
- 目标:能进能回,且不丢全局方位。
- 范围:单 `JunctionRef` 路由(本期只走 `node`,`cluster` 入口置灰);从路口面或诊断进入;加载该路口的编辑上下文(路口面、进口、相邻道路短上下文、车道/connector、步行带、停止线、斑马线、诊断、当前约束);返回主地图并恢复位置。
- 验证:`npm run test:client`、`npm run build`;手测——从路口面进入、从诊断进入、返回后主地图位置与选中态保持。
- 门禁:`cluster` 入口置灰且有原因提示,不落到 node 分支。
- 回滚点:纯新增路由,`directEdit` 开关关闭即隐藏入口。
## 2. 会话状态机与互斥守卫
- 目标:四态语义先于几何落地,避免后续用几何调试状态。
- 范围:`draft` / `applied` / `saved` / `cancelled` 的纯逻辑;未处理草稿时切换 `JunctionRef` 的拒绝守卫;取消复原。复用 `EditSession`,不新建第二套命令栈。
- 验证:`npm run test:client:unit` —— draft → 应用后成为主工作区未保存约束;取消后活动副本无残留;存在未处理草稿时切换被拒绝且草稿不丢;应用后的编辑可被主地图 undo/redo 撤销。
- 门禁:切换拒绝路径有测试;不存在自动应用或自动丢弃草稿的分支。
- 回滚点:纯逻辑模块,revert 后回到第 1 步的只读工作区。
## 3. 三项可拖能力与完整预览
- 目标:进口宽度、cutback、单角部圆角真正可编辑,预览覆盖全部受影响对象。
- 范围:三类手柄的渲染与拖拽;首次拖拽即 ghost;防抖后服务端局部权威预览;预览覆盖道路面、路口面、步行带、车道中心线、connector/movement、停止线、斑马线、标线;拟合失败返回最后有效几何加结构化诊断。
- 验证:`npm run test:client:unit`(手柄事件到三个 kind 的约束值投影)、`npm run test`(局部求解与全量编译对同一约束集结果一致)、`npm run test:client`、`npm run build`;手测——三项各自可拖;预览包含上述全部对象;制造拟合失败时不把非法图形显示成已应用。
- 门禁:预览对象清单逐项核对通过;失败态显示最后有效几何而非空白或非法图形。
- 回滚点:按 kind 分批提交,可单独回退某一类手柄。
## 4. 闭环验证
- 目标:与主工作区和持久化链路接通。
- 范围:应用回主地图、保存、重新编译的完整往返;`expectedDocumentVersion` 复用主地图已实现的冲突处理。
- 验证:`npm run format:check`、`npm run test`、`npm run test:client`、`npm run test:client:unit`、`npm run build`;手测——应用后返回主地图显示同一几何;保存后重新编译几何不变且约束状态 `exact`。
- 门禁:`prd.md` 全部验收标准勾选。
- 回滚点:revert 后回到第 3 步的预览-only 状态。
## 步骤依赖
1 → 2 → 3 → 4 硬顺序。第 2 步先于第 3 步是刻意的:会话四态若在几何可拖之后才做,取消与互斥的缺陷会被误当成求解问题。
每一步先写纯逻辑测试,再接 UI;不使用绝对像素作为核心契约,不自动提交。
@@ -1,10 +1,69 @@
# 最小 JunctionTools
# JunctionTools 路口编辑工作区
父任务:`.trellis/tasks/08-26-direct-manipulation-road-editor`。需求来源与权威合约在父任务的 `prd.md` / `design.md`。
## 目标
用专用工作区承载路口编辑,验证单一普通路口的进口宽度、cutback 与单个角部圆角,闭合"预览 → 应用到工作区 → 保存 → 取消"四态。这是路口能力的最小可信切片,不是完整路口编辑器。
用地图上的可识别路口区域作为入口,进入专用的局部 JunctionTools 工作区,在不破坏主地图编辑状态的前提下逐步承载路口几何、进口、控制设施和诊断编辑。远景参考 MATLAB RoadRunner 的路口局部编辑体验,但首期只建立可靠的识别、热区、进入/返回和单路口编辑基础,不追求一次实现完整路口建模。
## 当前产品设想
- 主地图识别普通路口和已配置的复杂路口 cluster,并以可点击热区表达,而不是依赖点击某一条道路或控制柄。
- 点击热区后进入独立 JunctionTools 编辑器,聚焦路口局部上下文;返回主地图时保留原地图视角、选中对象和未保存编辑。
- 编辑器逐步扩展为路口专用工作区:进口宽度、cutback、角部圆角、路口面、车道/connector、斑马线、停止线和诊断在同一 session 中协调。
- 所有编辑复用现有 direct-edit 文档、preview、revision、undo/redo 和导出契约,不建立第二套持久化几何。
## RoadRunner 对标拆解
RoadRunner 的路口能力不能简化成几个拖拽手柄。对本项目有价值的能力可拆成四层:
1. 路口识别与入口:从相交道路形成可识别的 junction 对象,并在场景中提供明确的选择目标。
2. 局部工作区:聚焦一个路口,显示进口、边界、车道、连接关系、标线和诊断,编辑完成后回到整体场景。
3. 几何与拓扑编辑:调整进口宽度、路口边界、转角圆角、车道连接和车道数,并让派生几何保持连续、合法。
4. 设施与验证:在路口上下文中布置或调整停止线、斑马线、信号灯等设施,并对冲突、自交、车道宽度和连接状态给出反馈。
本项目的映射不是复制 RoadRunner 内部实现:OSM 中心线和拓扑是只读输入,GeoJSON 是派生输出;可持久化的对象必须是 node/cluster 锚定的语义约束。当前代码已经具备 cluster candidate 检测、complex-junction 几何生成、三类 junction 约束和 preview/save/revision 基础,但缺少“热区 → JunctionTools 工作区”的产品层闭环。
## 分阶段方向
- 阶段 A:派生路口热区和识别状态(普通 node、已确认 cluster、候选 cluster),点击后进入/返回工作区。
- 阶段 B:单路口局部上下文和现有 `junction-approach-width`、`junction-cutback`、`junction-corner-radius` 编辑闭环。
- 阶段 C:车道/connector、斑马线、停止线、信号灯的联动编辑和冲突诊断。
- 阶段 D:cluster 多节点、多进口、多角部及更接近 RoadRunner 的拓扑创作能力。
阶段 A 不应把热区写成新的几何事实;它应由编译模型和 junction plan 派生,避免出现 UI 有路口而编译器不认的第二套数据。
## 本轮已决边界
- 首期只有普通 `node` 可编辑;已确认 `cluster` 只读,`candidate cluster` 只展示识别结果与诊断。
- 阶段 B 只开放进口宽度、cutback、单角部圆角;车道/connector 先展示并诊断,不开放拓扑写入。
- 设施首期允许移动或修改已有斑马线、停止线、信号灯,但不允许创建或删除设施。
- “应用到工作区”形成一个 undo 步骤,并进入主地图共用历史栈;连续拖拽不逐帧进入 undo。
- 离开工作区前必须选择应用并返回、放弃并返回或留在工作区,不自动应用或自动放弃。
- 保存时若编译模型或文档版本变化,拒绝保存并保留草稿,要求重新加载后处理,不自动覆盖或自动 rebase。
- candidate 不得在本轮被确认或转化为持久化 cluster。
- 自交、越界、最小车道宽度等几何非法诊断为 `blocking`;可修复的设施缺失或间距问题可为 `warning`。
- JunctionTools 使用独立 URL 路由,例如 `/junction/:type/:id`,支持刷新、浏览器返回和深链接。
## 总体约束
- OSM 节点、道路中心线和基础拓扑只读;编辑保存语义约束,不保存派生 GeoJSON。
- 普通 node 与复杂 cluster 使用不同的 `JunctionRef` 锚点,不把 cluster 降级成多个普通 node。
- 热区、路口边界和可编辑对象必须来自同一份编译状态;候选识别不能静默改变几何。
- 路口编辑必须复用现有 preview、active document、revision、版本冲突保护和 undo/redo。
- 无效几何不得替换最后有效预览;必须返回结构化诊断。
- 路口 session 与主地图 session 互斥,切换对象前必须应用或取消草稿。
- 导出包契约保持 `native-road-package/v1.1` 不变。
## 子任务地图
1. `09-02-junction-requirements-research`:RoadRunner 能力、用户流程、术语和需求验收基线。
2. `09-02-junction-detection-hotspot`:node/cluster/candidate 识别、热区派生模型和点击入口。
3. `09-02-junction-tools-workspace`:独立工作区路由、上下文加载、返回和 session 状态机。
4. `09-02-junction-geometry-editor`:进口宽度、cutback、圆角、车道/connector 的统一求解与预览。
5. `09-02-junction-facilities-validation`:斑马线、停止线、信号灯联动、诊断和最终发布验证。
依赖顺序为 1 → 2 → 3 → 4 → 5;每个子任务独立验收,父任务负责跨任务契约和最终集成。
## 顺序依赖
@@ -13,7 +72,8 @@
## 范围
- 单 `JunctionRef`(`{type:'node'|'cluster', id}`,本期只走 `node`)的工作区路由与返回主地图的上下文保持。
- 路口识别结果和热区入口的最小交互。
- 单 `JunctionRef`(`{type:'node'|'cluster', id}`)的工作区路由与返回主地图的上下文保持;首期只有 `node` 进入可编辑 session,`cluster` 与 candidate 只读。
- 加载该路口的编辑上下文:路口面、进口、相邻道路短上下文、车道/connector、步行带、停止线、斑马线、诊断与当前约束。
- 三项可拖能力:进口宽度、cutback、单个角部圆角。
- session draft:首次拖拽即 ghost,防抖后服务端权威局部预览。
@@ -24,9 +84,10 @@
- cluster 的高级编辑与复合路口模板编排。
- 多个路口的联合会话或联动编辑。
- 控制设施的逐个手工布置。
- 控制设施的新建、删除和身份创建;首期只允许修改已有设施的语义参数。
- 主地图道路区间的编辑(属 `direct-edit-map-editor`)。
- OSM 图拓扑的修改。
- 一次性实现 RoadRunner 级别的完整路口建模、任意拓扑创作或多路口联合编辑。
## 验收标准
@@ -18,7 +18,13 @@
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"children": [
"09-02-junction-requirements-research",
"09-02-junction-detection-hotspot",
"09-02-junction-tools-workspace",
"09-02-junction-geometry-editor",
"09-02-junction-facilities-validation"
],
"parent": "08-26-direct-manipulation-road-editor",
"relatedFiles": [],
"notes": "",
@@ -0,0 +1 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
@@ -0,0 +1,3 @@
# Design
设施层只保存现有语义文档;JunctionTools 汇总设施约束、受影响图层和阻塞诊断,发布前复用导出契约校验。
@@ -0,0 +1 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
@@ -0,0 +1,20 @@
# 路口设施与验证闭环
## Goal
在 JunctionTools 中协调斑马线、停止线、信号灯及发布前诊断,形成可复核的路口交付闭环。
## Requirements
- 设施编辑复用现有元素语义和交通信号文档,不复制 GeoJSON。
- 设施必须受所属进口/路口几何约束,越界时给出结构化诊断。
- 发布前展示受影响对象、阻塞问题、文档版本和导出契约状态。
- 保存、取消、撤销/重做和导出行为与主地图保持一致。
- 首期只允许修改已有斑马线、停止线和信号灯的语义位置或参数,不允许创建或删除设施。
- 自交、越界和几何不可解为 `blocking`;设施缺失或间距不足等非致命问题可为 `warning`,UI 依赖稳定诊断 code/severity。
## Acceptance Criteria
- [ ] 设施联动 preview 包含斑马线、停止线和信号灯派生对象。
- [ ] 非法设施位置不会替换最后有效预览。
- [ ] 保存后导出包契约不变,完整回归测试通过。
@@ -0,0 +1,26 @@
{
"id": "junction-facilities-validation",
"name": "junction-facilities-validation",
"title": "路口设施与验证闭环",
"description": "",
"status": "in_progress",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-09-02",
"completedAt": null,
"branch": null,
"base_branch": "main",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": "08-26-direct-edit-junction-tools",
"relatedFiles": [],
"notes": "",
"meta": {}
}
@@ -0,0 +1 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
@@ -0,0 +1,3 @@
# Design
建立 node/cluster 共用的 effective junction plan;solver 是唯一语义来源,`complex-junction.js` 只消费求解结果并生成派生图层。
@@ -0,0 +1 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
@@ -0,0 +1,20 @@
# 路口几何与拓扑编辑
## Goal
让 node/cluster 的路口编辑约束由同一套 effective plan 驱动,避免参数和复杂路口几何脱节。
## Requirements
- 统一进口宽度、cutback、角部圆角的 node/cluster 锚点和求解输入。
- 预览覆盖道路面、路口面、步行带、车道中心线、connector/movement 和控制设施。
- 最小车道宽度、边界连续、自交和 connector 越界必须阻塞并保留最后有效预览。
- cluster 不得被静默拆成多个 node 编辑。
- 阶段 B 仅允许普通 node 写入三项既有约束;cluster 仅验证只读 effective plan,不开放写入。
- 车道和 connector 在本阶段作为预览、诊断和影响对象展示,不提供拓扑创建、删除或重连。
## Acceptance Criteria
- [ ] 三类约束在 node 和已确认 cluster 上均有可验证的 effective plan。
- [ ] 乱序 preview、失败拟合和保存重编译有测试。
- [ ] 同一约束集的 preview 与正式编译结果一致。
@@ -0,0 +1,26 @@
{
"id": "junction-geometry-editor",
"name": "junction-geometry-editor",
"title": "路口几何与拓扑编辑",
"description": "",
"status": "in_progress",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-09-02",
"completedAt": null,
"branch": null,
"base_branch": "main",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": "08-26-direct-edit-junction-tools",
"relatedFiles": [],
"notes": "",
"meta": {}
}