8.2 KiB
8.2 KiB
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,避免把未成熟设施与基本编辑器绑定。
每阶段质量门禁
- 运行相关 Node/编译单测与客户端单测,增加 fixture 前先说明其覆盖的形态和不变量。
- 运行
npm run test、npm run test:client:unit -- --run、npm run test:client、npm run format:check、npm run build。 - 对会影响交互或地图图层的阶段再运行
npm run test:e2e,并人工检查局部画布、对象高亮、手柄方向、上下键、草稿/放弃/冲突和普通/复杂路口回归。 - 每阶段提交前执行 Trellis 全面检查;只提交该阶段的代码、测试与文档,
test-results/保持未跟踪。
风险与回退点
| 风险 | 控制方式 | 回退 |
|---|---|---|
| 规范数值被误认为全国统一法定阈值 | profile 必须记录来源、版本、适用条件和项目覆盖项 | 将规则留为建议/警告,移除保存门禁 |
| 新结构与旧草稿不一致 | 同一编译快照生成 structure、diagnostics、handles 和 preview | 客户端降级到既有描述/参数面板 |
| 复杂形态生成虚构对象 | effective-arm 分类为唯一输入,fixture 覆盖 T 字/单行/多臂 | 对不支持形态回退普通路口渲染 |
| 参考数据错误影响成果 | 参考层只读、独立开关、绝不直接写草稿 | 完全隐藏参考层,不影响 native 输出 |
| 高级设施超出可靠输入 | 每类设施单独交付,先建立真实样例和适配矩阵 | 关闭该设施分组,保留基础对象 |
启动前检查
- PRD、设计和实施计划已由用户按最新版本确认。
- 为当前执行阶段建立真实的
implement.jsonl与check.jsonl上下文条目。 - 读取后端与前端相关规范,并将 Stage 0 的相关文件与测试范围列入任务上下文。
- 不在用户确认前执行
task.py start、修改产品代码或创建实现提交。