docs(task): record complex junction editing roadmap
This commit is contained in:
1 parent
bba3ebe4b0
commit
bd8b55e58b
44 files changed
+955
No files matched your search
@@ -0,0 +1,3 @@
|
||||
{"file": ".trellis/spec/backend/direct-edit-api.md", "reason": "Solver, preview/save/rebase and persistence contracts."}
|
||||
{"file": ".trellis/spec/frontend/direct-edit-client.md", "reason": "Shared gesture, session, preview and UI ownership contracts."}
|
||||
{"file": ".trellis/tasks/09-08-complex-junction-editing/research/implementation-audit.md", "reason": "Verified source gaps and reusable implementation boundaries."}
|
||||
@@ -0,0 +1,32 @@
|
||||
# 技术设计
|
||||
|
||||
## 架构
|
||||
|
||||
从复杂几何生成器提取共用的 cluster 外部拓扑解析,输出显式 JunctionRef、道路臂、组成车行道、相邻角部、设施及来源映射。正式编译、编辑 manifest 和结构投影消费同一份拓扑,前端只做显示与选择。
|
||||
|
||||
流程:cluster 配置 + baseline model → 外部拓扑 → v2 约束解析 → effective cluster plan → complex geometry → structure / manifest / diagnostics → EditSession。预览与保存复用候选求值;保存成功后沿用显式重新编译并刷新状态的流程。
|
||||
|
||||
## 对象与约束
|
||||
|
||||
- 引用使用 `{type: 'node'|'cluster', id}`。兼容既有 node 请求,新增显式 cluster 选择,禁止猜测无类型 ID;同时传多个选择应拒绝。
|
||||
- Arm 身份来自 cluster ID 与稳定来源成员集合,不能来自数组下标、地图编号或浮点 heading;一臂可含多条有方向的车行道。车行道保留 node/segment/road 来源,目标宽度不包含中央分隔或人行道。
|
||||
- Corner 身份由有序相邻臂对定义,来自环向几何排序;同一源拓扑下输入排序变化不改变 ID。拓扑指纹区分重排和真正成员变化。
|
||||
- 设施采用语义对象标识;一组条纹对应一个 crossing 对象,停止线关联到对应来向 crossing,信号关联使用显式来源,不用字符串包含推断。
|
||||
- 拟新增 cluster 专用 anchor(junctionRef + object kind/key + 必要车行道来源),扩展 v2 validator、客户端联合类型、replay 和 resolver。旧 node anchor 继续原样读取,不能复用 nodeId 字段塞入 cluster ID。
|
||||
- 约束优先级:对象局部覆盖 > cluster 该参数默认值 > 编译基线。恢复继承禁用局部约束并记录操作;不删除仍被历史引用的约束。默认宽度作用于各外部车行道;道路臂批量操作明确列出组成车行道与影响范围,不把多个分离车行道的总宽当作单条路宽。
|
||||
|
||||
## 几何消费与校验
|
||||
|
||||
cluster effective plan 是复杂生成器的显式输入,不回写所有成员 node plan。宽度影响道路边界及必要连接;收口沿对应外部车行道中心线计距;角部圆角只作用于对应相邻边界。复杂核心、过街、人行道和连接面的联动由生成器统一生成。
|
||||
|
||||
候选求值先验证文档,再用相同 cluster 配置解析、编译并收集诊断。保存必须在任何候选写入之前拒绝 solver 或 compiled geometry error;warning 允许保存。不存在对象、越界、自交、过街越出可用路幅及断开的必要连接应给出对象级诊断,不能静默钳制输入或回退成看似成功的普通路口。
|
||||
|
||||
## 会话与兼容
|
||||
|
||||
App 继续负责跨域保存与重编译,组件不直接调 API。复用现有 EditSession、PreviewRequester 和手柄系统。请求带有作用域身份及序列校验,切换作用域放弃正在进行的手势并使旧响应失效;保持全局文档中其他对象的约束。地图实例不能因右栏或路口切换重建。
|
||||
|
||||
旧 node 文档几何保持一致。复杂编辑能力按参数发布,只有 anchor、求解、geometry、manifest、保存和 UI 都通过验收后才标记可编辑。高级设施没有实现的自由编辑能力保持只读。
|
||||
|
||||
## 风险与回滚
|
||||
|
||||
现有角度聚类和内部连线排除规则需要真实样本验证;歧义对象不开放编辑。几何校验会增加保存成本,应记录耗时及预览 degraded 状态。参考几何继续只读,不作为编辑真值。每个子任务独立提交;回滚先关闭对应能力入口,保留已保存约束的可读性及显式 unsupported 诊断,禁止静默丢弃文档。
|
||||
@@ -0,0 +1,3 @@
|
||||
{"file": ".trellis/spec/backend/direct-edit-api.md", "reason": "Solver, preview/save/rebase and persistence contracts."}
|
||||
{"file": ".trellis/spec/frontend/direct-edit-client.md", "reason": "Shared gesture, session, preview and UI ownership contracts."}
|
||||
{"file": ".trellis/tasks/09-08-complex-junction-editing/research/implementation-audit.md", "reason": "Verified source gaps and reusable implementation boundaries."}
|
||||
@@ -0,0 +1,30 @@
|
||||
# 执行计划
|
||||
|
||||
## 开始前
|
||||
|
||||
- [ ] 向用户展示最终规划并取得本轮实现范围确认;随后逐个启动子任务,父任务仅统筹。
|
||||
- [ ] 读取各子任务上下文及 trellis-before-dev;记录工作区状态,不覆盖已有改动。
|
||||
- [ ] 使用 research/implementation-audit.md 作为现状索引;不要把历史测试结论当本轮结果。
|
||||
|
||||
## 顺序与闸门
|
||||
|
||||
1. 01 交付确定性结构与身份;未通过重排、多 cluster 隔离、内部连线排除测试,不启动宽度编辑。
|
||||
2. 02 交付真实宽度变化和保存闭环;同阶段完成版本保护、编译诊断保存拒绝及最小失效保护,不能推迟到 05。
|
||||
3. 03 交付收口和圆角,证明局部影响范围及统一值/覆盖/恢复继承。
|
||||
4. 04 交付过街、停止线、既有信号编辑的选择与事务衔接。
|
||||
5. 05 完成拓扑生命周期与异步竞态矩阵,不重复构建事务系统。
|
||||
6. 06 做跨阶段形态矩阵及真实样本人工确认,记录结果后更新 spec、提交、归档。
|
||||
|
||||
## 验证命令
|
||||
|
||||
针对每个切片先运行相关脚本:`node test/junction-structure.js`、`node test/junction-projection.js`、`node test/direct-edit-solver.js`、`node test/native-road-edits.js`、`node test/workbench-edit-api.js`。
|
||||
|
||||
跨层切片运行 `npm run test:client`、`npm run test:client:unit` 和 `npm run build`。最终运行 `npm test`、`npm run test:e2e`、`npm run format:check`。只有新增改动、失败或未解决风险时重复已通过检查。环境失败与功能失败分开记录;需要端口或沙箱外能力时按环境权限处理,不把未运行检查报为通过。
|
||||
|
||||
## 交付证据
|
||||
|
||||
- [ ] 每个子任务 acceptance 关联具体测试/样本/浏览器步骤,记录命令和结果。
|
||||
- [ ] 最终证明非空编辑改变目标几何,preview / save + compile 一致且 refresh 保留。
|
||||
- [ ] 保存拒绝与 409 路径验证文件内容及版本未变化;预览验证文件内容和 mtime 未变化。
|
||||
- [ ] 验证普通路口和编辑关闭状态;记录真实样本剩余限制。
|
||||
- [ ] 更新 frontend/backend 契约,完成 Trellis 质量检查及任务归档,不能用文档完整代替实现完成。
|
||||
@@ -0,0 +1,45 @@
|
||||
# 复杂路口编辑能力闭环
|
||||
|
||||
## 目标
|
||||
|
||||
让用户在 JunctionTools 内像编辑简单路口一样,选择复杂路口的道路臂、角部和过街设施,通过数字输入或地图拖拽修改、预览、撤销、保存,重新编译和刷新后仍能看到相同结果。
|
||||
|
||||
## 已确认背景
|
||||
|
||||
昨天已完成候选与成员点选择、地图编号、外部形态识别、复杂几何生成、结构/设施展示与诊断。复杂路口仍是只读聚合视图,尚未接入完整编辑事务。现有 6 个子任务原为规划占位,本轮补齐正文。代码证据见 research/implementation-audit.md。
|
||||
|
||||
## 需求
|
||||
|
||||
- R1:按实际对外道路臂和相邻角部编辑;内部节点布局不能代替最终形态,地图和列表必须指向同一个对象。
|
||||
- R2:支持对外车行道宽度、进口收口距离、角部圆角的局部修改、路口统一默认值和恢复继承;局部覆盖优先,设置统一默认值不能静默覆盖局部修改。
|
||||
- R3:支持复杂路口过街退距及停止线偏移,选中一组斑马线时作为一个设施编辑;信号灯复用已有可编辑字段和保存机制,不扩大到新信号配时系统。
|
||||
- R4:输入和拖拽共用预览、撤销/重做及保存链路;打开另一对象或路口时不能残留前一对象的预览。
|
||||
- R5:保存后重编译和刷新结果一致;版本冲突、无效几何和失效对象必须明确提示,不能部分应用或静默改绑。
|
||||
- R6:调整参与节点、重新导入或重编译时保留可追踪的编辑,失效和歧义编辑可定位、可复核,不能污染其他路口。
|
||||
- R7:简单路口原有编辑能力、参考图层和普通地图使用不能回归;不支持的复杂形态明确只读及原因。
|
||||
|
||||
## 范围边界
|
||||
|
||||
本轮交付完整的上述编辑闭环,按子任务逐步开放。导流岛、中央分隔和人行道转角应正确展示和关联,可随几何联动;任意顶点编辑、新增/删除这些设施、道路拓扑绘制、新信号配时和自动套用参考几何不在本轮范围。
|
||||
|
||||
## 验收
|
||||
|
||||
- [ ] A1 / R1:十字、T 字、偏置十字、多臂的地图选择、结构列表和实际外部拓扑一致;成员/道路数组重排不改变对象身份。
|
||||
- [ ] A2 / R2:单臂宽度、收口和单角圆角只影响目标及必要相邻连接;统一值、局部覆盖、恢复继承结果可解释。
|
||||
- [ ] A3 / R3:过街及停止线编辑不误选相反行车方向或相邻设施;既有信号编辑可在复杂路口定位并保存。
|
||||
- [ ] A4 / R4–R5:拖拽、输入、撤销、重做、保存、重编译、刷新都得到同一目标值与几何;无效候选保存不改写文件。
|
||||
- [ ] A5 / R5–R6:旧版本返回 409;拓扑变更后原对象不可解析时显式失效,迟到预览不能覆盖新作用域。
|
||||
- [ ] A6 / R7:简单路口回归通过;不支持形态没有无效手柄;编辑关闭时没有编辑图层和请求。
|
||||
|
||||
## 子任务与依赖
|
||||
|
||||
| 子任务 | 可验收交付 | 前置 |
|
||||
| --- | --- | --- |
|
||||
| 09-08-cj-01-identity | 权威外部结构、稳定标识、作用域与能力契约 | 无 |
|
||||
| 09-08-cj-02-width | 宽度输入/拖拽到持久化的首个闭环,包含保存几何校验 | 01 |
|
||||
| 09-08-cj-03-geometry | 收口、圆角及局部覆盖 | 02 |
|
||||
| 09-08-cj-04-facilities | 过街、停止线及既有信号编辑衔接 | 03 |
|
||||
| 09-08-cj-05-lifecycle | 成员变更、重放、切换与事务完整性 | 04;最低版本/失效保护已在 01、02 实现 |
|
||||
| 09-08-cj-06-acceptance | 形态矩阵、浏览器和真实样本集成验收 | 01–05 |
|
||||
|
||||
第 1 阶段已完成只读结构、稳定身份、作用域和地图选择,并通过验收;其余阶段尚未启动,复杂参数编辑尚未开放。
|
||||
@@ -0,0 +1,21 @@
|
||||
# Implementation evidence (2026-09-08)
|
||||
|
||||
Baseline: `bba3ebe`, branch `feat/direct-edit-documents`. This is a source review; historical test results are not new verification results.
|
||||
|
||||
| Evidence | Current behavior | Required consequence |
|
||||
| --- | --- | --- |
|
||||
| `src/compile/direct-edit-solver.js:1159` | Cluster effective plans flatten member approaches and merge corner dictionaries; `readOnly: true` at line 1213. | Build authoritative external-arm/corner identities before permitting writes. Do not broadcast a node constraint across a cluster. |
|
||||
| `src/compile/complex-junction.js:36` | Geometry discovers external approaches, groups carriageways by heading, and classifies shape. | Reuse/extract this topology for the editor and compiler; avoid a second frontend topology algorithm. |
|
||||
| `src/compile/junction-projection.js:40` | Projection takes the first complex core and an endpoint-derived node, and makes corners from road array order. | Explicit junction scope, geometric adjacency, and deterministic identities are prerequisites. |
|
||||
| `src/compile/junction-structure.js:32` | Normalization only retains declared arm fields. | Explicitly preserve provenance/capabilities; adding fields only to the projection input will lose them. |
|
||||
| `workbench/server.js:323` | Selection parser supports segment and junction, without an explicit cluster branch. | Add unambiguous cluster selection while preserving existing node requests. |
|
||||
| `workbench/server.js:334` | Edit-state solver context lacks cluster configuration; structure projection is not selection scoped. | State, preview, save, rebase and formal compile need the same cluster context. |
|
||||
| `workbench/server.js:366` | Preview compiles geometry and returns compiled plus solver diagnostics. | Use the same candidate evaluation for save. |
|
||||
| `workbench/server.js:436` | Save rejects solver errors but does not compile candidate geometry before persistence. | Reject compiled geometry errors before any candidate document write. |
|
||||
| `workbench/client/src/junction/workspace.ts:49` | Only editable node descriptors pass canEditJunction. | Gate cluster editing on backend capability after the complete path exists. |
|
||||
| `workbench/client/src/hooks/useDirectEditSession.ts:39` | Selection uses a node junction ID. | Carry explicit JunctionRef through request/response and session scoping. |
|
||||
| `src/compile/complex-junction.js:94` | Complex core, crossing and stop-line placement use cluster geometry rules. | Node plan updates alone do not prove complex geometry consumption. |
|
||||
|
||||
Existing reusable assets: v2 document and EditSession, gesture history, numeric parameter input, handle/ghost/preview layers, version conflict protection, cluster membership UI, compiler shape classification and reference layer. Existing structure/facility display is not evidence that those objects are writable.
|
||||
|
||||
Research boundaries: no new editor engine; no automatic inference of shape from node count; no claim of full geometric validity based solely on unit tests. Runtime geometry and geographic fixtures must be checked in implementation.
|
||||
@@ -0,0 +1,33 @@
|
||||
{
|
||||
"id": "complex-junction-editing",
|
||||
"name": "complex-junction-editing",
|
||||
"title": "复杂路口编辑能力闭环",
|
||||
"description": "复杂路口道路臂、角部和过街设施的编辑、预览、保存与拓扑生命周期闭环;父任务统筹六个可验收切片。",
|
||||
"status": "planning",
|
||||
"dev_type": "fullstack",
|
||||
"scope": "junction",
|
||||
"package": null,
|
||||
"priority": "P2",
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-09-08",
|
||||
"completedAt": null,
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [
|
||||
"09-08-cj-01-identity",
|
||||
"09-08-cj-02-width",
|
||||
"09-08-cj-03-geometry",
|
||||
"09-08-cj-04-facilities",
|
||||
"09-08-cj-05-lifecycle",
|
||||
"09-08-cj-06-acceptance"
|
||||
],
|
||||
"parent": null,
|
||||
"relatedFiles": [],
|
||||
"notes": "第 1 阶段已实现并验收:稳定结构/身份/作用域及地图选择;其余 5 个子任务保持 planning。",
|
||||
"meta": {}
|
||||
}
|
||||
Reference in new issue
Block a user