3.5 KiB
3.5 KiB
实施计划
对应父任务 implement.md 的第 0、2、3 步。每步一个提交，门禁不过就停。
1. 测试基础设施
- 目标：先建验证能力，避免后续"写完没法测"。
- 范围：
package.json增加固定版本vitest与test:client:unit脚本；建立客户端纯逻辑测试目录。不碰产品代码。 - 验证：
npm run test:client:unit（空套件通过）、npm run format:check、npm run test、npm run test:client、npm run build。 - 门禁：新脚本可跑通且不影响任何既有脚本。
- 回滚点：仅
package.json与测试目录，revert 无副作用。
2. v2 文档与 schema 校验
- 目标：
native-road-edits/v2的读写与结构校验。 - 范围：
src/compile/下新增文档模块：6 个 kind、4 种锚点、anchorSnapshot、ConstraintStatus、documentVersion、operations。仅结构与取值范围校验。 - 验证：
npm run test新增 fixture——文档往返无损；boundaryIndex非整数或<1被拒；非法 station（超出0..1、start>=end）被拒；未知 kind 被拒；kind 与锚点类型不匹配被拒；provenance 指向未记录的 operation 被拒；每次写入documentVersion递增 1。 - 注意：
boundaryIndex >= laneCount不属于 schema 校验——车道数是模型信息，schema 层无从得知。按design.md，该越界在重放时由求解器判定并转stale，归direct-edit-solver-api。 - 门禁：校验错误信息能指出具体约束 id 与字段，不是笼统失败。
- 回滚点：纯新增模块，无调用方，revert 无影响。
3. 存储布局、惰性迁移与 revision
- 目标：
active/、revisions/、内容寻址 OSM 副本落地，既有目录可平滑接入。 - 范围：目录布局读写；读取入口触发的惰性迁移，把当前
source.osm+ overrides + signals + area config 冻结为rev-0001；命名检查点创建；revision 恢复读取；RoadRevisionManifest写入。 - 验证：
npm run test新增 fixture——只含旧文件的目录被打开后生成rev-0001且既有文件字节不变；内容相同的 OSM 重复导入不产生第二份副本；命名检查点冻结后可完整恢复读取；manifest digest 与实际文件一致。 - 门禁：迁移对既有
workbench-data/import-*只增不改；revert 后旧代码仍能打开这些目录。 - 回滚点：revert 后
active/与revisions/只是残留目录，旧代码忽略它们。
4. area config 快照
- 目标：切断编译对外部区域配置文件的运行期依赖。
- 范围：活动副本与每个 revision 各写一份
area-config.snapshot.json；编译改读快照；base.areaConfigSha256指向快照。 - 验证：
npm run test新增 fixture——冻结 revision 后修改外部 area config，重新编译该 revision 结果不变；快照缺失时报明确错误而非静默读外部文件。 - 门禁：无 v2 文档时编译输出与快照一致。注意：仓库现有
test/baseline/*.json已过期（contract为native-road-package/v1，当前为v1.1，18 个文件 hash 全部不符），且test/fixtures.js:26只断言文件存在、从不比对内容，仓库内也没有生成器。因此本步须先从当前 main 重新生成快照并接上真实比对，再谈"不变"。 - 回滚点：revert 后编译回到读外部配置文件；已写快照被忽略。
步骤依赖
1 → 2 → 3 → 4 是硬顺序。第 4 步的 baseline 比对是本子任务能否交付的总门禁：无 v2 约束时编译输出必须与当前 main 完全一致。