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,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;不使用绝对像素作为核心契约,不自动提交。