road-compiler/.trellis/tasks/archive/2026-08/08-26-direct-edit-documents/prd.md

直接编辑文档与 revision 基础

父任务：.trellis/tasks/08-26-direct-manipulation-road-editor。需求来源与权威合约在父任务的 prd.md / design.md。

目标

建立 native-road-edits/v2 文档、活动工作副本、不可变 revision 与 area config 快照，使后续求解、预览和编辑能力有可复现的持久化基础。本子任务不含任何 UI，也不含约束求解。

顺序依赖

无前置。是 direct-edit-solver-api、direct-edit-map-editor、direct-edit-junction-tools 三者的前置：它们依赖本任务定义的文档 schema、documentVersion 与快照读取路径。

范围

• vitest 依赖与 test:client:unit 脚本（后续子任务的验证基础）。
• native-road-edits/v2 文档读写与 schema 校验：6 个约束 kind、4 种锚点、anchorSnapshot、5 态 ConstraintStatus、documentVersion。
• workbench-data/import-<id>/ 内的 active/、revisions/、内容寻址 osm/<sha256>.osm 布局。
• 既有 import 目录的惰性迁移：首次打开时冻结 rev-0001，不移动或重写既有文件。
• area-config.snapshot.json 的写入与读取；编译与预览改读快照。
• 命名检查点创建与 revision 恢复读取。

不做

• resolveDirectEditConstraints 与任何几何求解（属 direct-edit-solver-api）。
• 预览、保存、rebase 的 HTTP 端点（属 direct-edit-solver-api）。
• 任何客户端改动。
• v1 native-road-overrides.json 的迁移或格式变更。

验收标准

• vitest 与 test:client:unit 可跑通空套件，且不影响既有 test / test:client / build。
• v2 文档往返读写无损；schema 校验拒绝越界 boundaryIndex、非法 station 与未知 kind。
• 每次成功写入使 documentVersion 递增 1。
• 只含旧文件的既有 workbench-data/import-* 目录，在新代码下可正常打开且未被改写，并生成 rev-0001。
• 内容相同的 OSM 重复导入不产生第二份副本。
• 冻结 revision 后修改外部 area config，重新编译该 revision 结果不变。
• 快照缺失时给出明确错误，不静默回退到读外部配置文件。
• npm run format:check、npm run test、npm run test:client、npm run build 全绿。