# 直接编辑文档与 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` 全绿。