feat(junction): add structure and standards contract

This commit is contained in:
que01 committed 2026-09-07 14:11:44 +08:00
1 parent 8d6f531377
commit 61cf276745
13 files changed
+843 -1

No files matched your search

@@ -0,0 +1,127 @@
# 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`、修改产品代码或创建实现提交。