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

设计

技术合约不在本文重复定义。权威定义见父任务 .trellis/tasks/08-26-direct-manipulation-road-editor/design.md 的以下小节：

• 「约束模型」— RoadConstraintKind 6 个取值、SemanticAnchor 4 种锚点、transition、boundaryIndex 范围、station 语义。
• 「文档、活动副本与 revision」— RoadEditDocument、RoadConstraint、ConstraintStatus 5 态表。
• 「存储布局与迁移」— 目录结构、惰性迁移、内容寻址与留存策略。
• 「area config 所有权」— 快照规则与 areaConfigSha256。
• 「编译器几何版本变更」— recheck 策略。
• 「上线与回滚形态」— 服务端纯增量、v1 文件不动。

本子任务的局部决定

• 文档读写与 schema 校验放在编译器侧（src/compile/ 下新增模块），不放在 workbench/server.js：预览、正式编译与 CLI 导出都要用它，放服务器会造成第二套实现。
• 校验只做结构与取值范围，不做几何可行性。几何不变量（最小车道宽、外缘不交叉等）属求解器职责，见 direct-edit-solver-api。
• 惰性迁移在读取入口触发，不提供独立迁移命令：既有 import 目录数量少，且迁移是纯增量创建，失败可重试。
• ConstraintStatus 在本子任务只落地存储与校验；实际重放匹配逻辑属 direct-edit-solver-api。本任务的测试用手工构造的 status 值覆盖读写路径。
• 内容寻址采用 sha256，与 RoadRevisionManifest.source.osmSha256 同一摘要，避免两套 hash。