Files
road-compiler/.trellis/tasks/archive/2026-09/09-07-junctiontools-standards/implement.md
T

128 lines
8.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# JunctionTools 行业规范化实施计划
## 实施原则
按“先理解、再选择、后编辑、最后扩展设施”推进。每一阶段都应可独立验证、单独回退,且只在该阶段通过质量门禁后提交。除已稳定的 direct-edit 参数外,不提前把未完成验证的规范规则变成保存门禁。
## Stage 0:数据契约、规范来源与回归基线
**交付物**
- 定义 `junctionStructure`、对象键、`selectedObjectKey`、覆盖状态、诊断和参考比较的 TypeScript/服务端契约。
- 创建 `cn-urban-default` 的版本、来源、适用条件、项目覆盖规则和“建议/警告/硬不变量”分层;数值不明的条目先以配置占位和 fixture 表达,不散落硬编码。
- 盘点现有 simple/complex 编译输出、direct-edit 约束、信号与参考 GeoJSON 的字段归属,明确复用点和兼容字段。
- 固化最小真实样例:普通四臂、T 字、偏置十字、多臂、单行/单车道道路以及带/不带参考 GeoJSON 的样例。为每类保存基线形态、有效道路臂和设施计数。
**验收与测试**
- 契约单测覆盖对象键稳定性、T 字不产生第四臂、单行道路不产生假想对向车行道。
- fixture 断言内部 `2×1/2×2` 布局不会作为最终形态文案。
- 输出一份规范来源清单,明确哪些规则是项目建议、哪些是保存不变量。
**提交边界**:`test(junction): add standards fixtures and structure contract`。仅新增契约/fixture/测试,不改用户可见保存行为。
## Stage 1:统一只读结构与标准面板
**交付物**
- 编译层从 simple 与 complex 结果构造同一 `junctionStructure`,发布道路臂、角部、横道、停止线、已存在信号和形态摘要。
- 服务端将结构、当前标准档和 `pass/warning/blocking` 诊断纳入 state、预览响应与 debug 投影。
- JunctionTools 顶栏、左侧对象树和右侧只读标准面板接入结构,使用可读道路名或“道路 1/2”回退,不显示内部 ID。
- 诊断可定位到一个对象并在局部画布中高亮;字段级问题先能聚焦再谈阻塞保存。
**验收与测试**
- simple、complex、T 字、偏置和多臂 fixture 的对象清单、数量和标签通过单测。
- 客户端单测验证列表、地图与参数上下文共用同一 `selectedObjectKey`。
- 手工验证独立工作区不渲染无关主地图要素,信号存在时可见。
**提交边界**:`feat(junction): expose unified structure and standards diagnostics`。问题可通过关闭新面板或回退结构字段恢复旧工作区。
## Stage 2:选择模型与全局/局部覆盖交互
**交付物**
- 完成左栏、中心局部画布、右栏和底栏的信息架构;地图点击、列表、手柄和诊断定位严格映射到同一对象。
- 为道路臂、角部和设施实现“使用全局值 -> 单独调整 -> 恢复全局值”的通用交互及可读影响范围。
- 完成当前对象重置、全草稿放弃、撤销/重做与选择切换后的草稿一致性;区分进入时基线和预览基线。
- 将手柄方向、表单单位、上下键步进和范围提示统一到现有 direct-edit 约束。
**验收与测试**
- 点击同一对象的多个几何片段仍进入同一个表单;选择切换不能遗留旧对象字段。
- 只修改局部覆盖时只影响选定对象;恢复全局后重新继承全局预览。
- 重置当前对象与放弃草稿分别恢复正确范围,版本冲突路径保持现有行为。
- 覆盖现有“拖左向右”方向回归的四个方位及复杂路口样例。
**提交边界**:`feat(junction): add object selection and scoped overrides`。可回退为现有参数面板,不改底层几何。
## Stage 3:已稳定道路、角部与过街参数的规范化编辑
**交付物**
- 将现有进口宽度、进口退让(替代不清晰的 `cutback` 文案)、角部圆角、斑马线退让/尺寸、停止线偏移接入对象表单和地图手柄。
- 为车道/道路臂宽度、横道全宽覆盖、停止线-横道方向/净距、角部净空、步行连续性和核心/角部多边形有效性提供校验器。
- 将明确的几何不变量设为 `blocking`;项目建议和适用规范范围按 `pass/warning` 表达。阻塞时高亮实际字段与几何,不弹出孤立 alert。
**验收与测试**
- 每条规则至少有通过、警告、阻塞 fixture;阻塞保存、警告可预览保存、诊断可定位。
- T 字、单行和单车道 fixture 证明无虚构设施/对向道路假设。
- 保存、预览、撤销/重做、草稿放弃、版本冲突和现有普通路口回归通过。
**提交边界**:`feat(junction): validate stable geometry controls`。如配置或校验发现问题,先将规则降为诊断,保留硬几何不变量。
## Stage 4:参考 GeoJSON 叠加与差异比较
**交付物**
- 接入原始与转换后坐标信息、显示/隐藏、透明度和空间匹配比较。
- 呈现中心、bbox、面积、方向和未匹配原因,且明确参考数据只读。
- 为高置信度空间匹配设计建议对象,但本阶段不得写入草稿或自动修改几何。
**验收与测试**
- GCJ-02 转换、缺失文件、不同 geometry 类型、匹配/未匹配和关闭参考层都有测试。
- 叠加开关不改变编译输出、revision 或保存请求;原始 `type` 不出现在可编辑字段中。
**提交边界**:`feat(junction): add reference geometry comparison`。出错时完全关闭参考层即可回退。
## Stage 5:高级设施和形态适配
**交付物**
- 基于真实样例逐项接入导流岛、中央分隔、非机动车过街、无障碍连续路径和信号几何关联。
- 每项设施必须有对象模型、可读标签、选择/高亮、覆盖语义、适用形态和独立的几何校验;不得由 `2×1/2×2` 或道路数量硬编码决定。
- 建立“形态适配矩阵”:T 字、十字、偏置十字、多臂、单行和单车道下哪些设施可出现、不可出现或需手动确认。
**验收与测试**
- 每种新设施至少一个真实 OSM fixture、一个不适用形态 fixture 和一个保存/回退案例。
- 信号仅作为已有对象与几何关联展示,未实现相位编辑前不承诺控制逻辑。
**提交边界**:每一设施类别独立提交,例如 `feat(junction): add median and island facilities`,避免把未成熟设施与基本编辑器绑定。
## 每阶段质量门禁
1. 运行相关 Node/编译单测与客户端单测,增加 fixture 前先说明其覆盖的形态和不变量。
2. 运行 `npm run test`、`npm run test:client:unit -- --run`、`npm run test:client`、`npm run format:check`、`npm run build`。
3. 对会影响交互或地图图层的阶段再运行 `npm run test:e2e`,并人工检查局部画布、对象高亮、手柄方向、上下键、草稿/放弃/冲突和普通/复杂路口回归。
4. 每阶段提交前执行 Trellis 全面检查;只提交该阶段的代码、测试与文档,`test-results/` 保持未跟踪。
## 风险与回退点
| 风险 | 控制方式 | 回退 |
| --- | --- | --- |
| 规范数值被误认为全国统一法定阈值 | profile 必须记录来源、版本、适用条件和项目覆盖项 | 将规则留为建议/警告,移除保存门禁 |
| 新结构与旧草稿不一致 | 同一编译快照生成 structure、diagnostics、handles 和 preview | 客户端降级到既有描述/参数面板 |
| 复杂形态生成虚构对象 | effective-arm 分类为唯一输入,fixture 覆盖 T 字/单行/多臂 | 对不支持形态回退普通路口渲染 |
| 参考数据错误影响成果 | 参考层只读、独立开关、绝不直接写草稿 | 完全隐藏参考层,不影响 native 输出 |
| 高级设施超出可靠输入 | 每类设施单独交付,先建立真实样例和适配矩阵 | 关闭该设施分组,保留基础对象 |
## 启动前检查
- [ ] PRD、设计和实施计划已由用户按最新版本确认。
- [ ] 为当前执行阶段建立真实的 `implement.jsonl` 与 `check.jsonl` 上下文条目。
- [ ] 读取后端与前端相关规范,并将 Stage 0 的相关文件与测试范围列入任务上下文。
- [ ] 不在用户确认前执行 `task.py start`、修改产品代码或创建实现提交。