que01
93f09e399e
Planning: parent design.md becomes the single authoritative contract (constraint model with 6 kinds, handle manifest, coordinate/unit layering, preview sequencing, storage layout and lazy migration, area config snapshot, API contract). Work is split into four independently verifiable child tasks with per-step gates and rollback points. Test infra: pin vitest 4.1.11, add test:client:unit for client pure logic, extend prettier globs to root *.ts so vitest.config.ts is checked. Add .gitignore: the repo had none, so inputs/, outputs/, workbench-data/ and the client build output were untracked rather than ignored. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
40 lines
3.2 KiB
Markdown
40 lines
3.2 KiB
Markdown
# 实施计划
|
||
|
||
对应父任务 `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` 或 `>=laneCount`）被拒；非法 station（超出 `0..1`、`start>=end`）被拒；未知 kind 被拒；每次写入 `documentVersion` 递增 1。
|
||
- 门禁：校验错误信息能指出具体约束 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 完全一致。
|