# 后续计划：drawtonomy 扩展 PoC

前置任务：`08-25-road-compiler-extraction` 的 Phase 0-3 完成并完成验收。
评估依据：父任务归档前的 `design.md` §4 决策记录 D1 / D2 / D3。

## Goal

在**编译器仓库内**实现一个 drawtonomy 扩展：把编译产物注入其浏览器编辑器，
回读快照后走其开源导出器产出 OpenDRIVE / Lanelet2。

定位是 **PoC，不进关键路径**。目的是验证「编译器当 scene generator +
drawtonomy 当编辑器与工业格式后端」这条链路是否值得投入。

## 前提认知（已核实）

必须先明确，否则会做错方向：

- **drawtonomy 编辑器闭源**，克隆仓库只有 SDK / dev-server / mcp-server。
  README 卖点里的 topology-aware lanes、lane tool、intersection templates、
  Map→lanes 全部不在开源代码内。
- **它不做 raw OSM 推导**。`exporter/osmParser.ts` 是 Lanelet2 解析器
  （车道左右边界已显式）。整个 exporter 目录 grep `highway` 命中 1 次且是
  车道类型字符串。→ **不能替代本编译器**，只能做下游。
- **junctionTools 不能做成扩展**：无 canvas/overlay 能力、无工具注册、
  **无任何 change 事件推送**（`ExtensionClient.handleMessage` 入站只有
  `ext:init` / 5 个 `*-response` / `ext:error`，读取全靠轮询）。
  → junction 编辑留在自有 workbench。
- **`drawtonomy-dev-server` 是 drawtonomy.com 的缓存代理**（TTL 1 小时），
  非自托管。宿主协议会漂（manifest 有 `minHostVersion`）。→ 不进关键路径。

## Requirements

### R4.1 扩展：编译产物 → 编辑器

- manifest capabilities：`shapes:write`、`ui:panel`、`snapshot:read`、`ui:notify`
- 面板调编译器的本地 HTTP 服务（`road-workbench` 已经是一个 HTTP 服务）取产物
- 车道边界 → `createLaneWithBoundaries(leftPoints, rightPoints, opts)` → `addShapes()`
- 坐标转换：本项目 WGS84/ENU（米）→ drawtonomy 画布像素。
  沿用其 `drawtonomy_origin_lat/lon` + `latLonToCanvas` 约定
- ⚠️ **借它的结构，不借它的坐标系**：其 `BaseShape.x/y` 是画布像素
  （`z` 注释明确写 "world units — NOT canvas pixels like x/y"）。
  编译器内部坐标系不得因此改变

### R4.2 回读 → 工业格式导出

- `requestSnapshot()` 取回快照
- 本地跑其开源 `exportToOpenDrive` / `lanelet2`（Apache-2.0）
- 产出 `.xodr` / `.osm`(Lanelet2)，用其 `validateOpenDrive` 自校验
- Lanelet2 是 Autoware 的输入格式 —— 对本项目 V2X 方向有实际价值

### R4.3 许可与依赖合规

- drawtonomy SDK 是 Apache-2.0：借用代码需保留 NOTICE / 署名
- 若依赖 drawtonomy.com 托管服务，需查其服务条款（app 非 Apache-2.0）
- ESM/CJS 互操作：SDK 是 ESM+TS，编译器是 CJS。
  本阶段可**局部**引入构建步骤，但仅限扩展目录，不得污染编译器核心
  （父任务 C2 的边界）

### R4.4 归属

扩展代码放**编译器仓库**，不放宿主 —— 符合父任务「独立维护」目标。

## Acceptance Criteria

- [ ] AC4.1 扩展能把一个区域的编译产物注入 drawtonomy 编辑器并正确显示车道
- [ ] AC4.2 编辑器内手改后回读快照，能导出通过 `validateOpenDrive` 的 `.xodr`
- [ ] AC4.3 能导出 Lanelet2 `.osm`
- [ ] AC4.4 编译器核心未引入构建步骤（构建仅限扩展目录）
- [ ] AC4.5 编译器内部坐标系未因适配画布像素而改变
- [ ] AC4.6 Apache-2.0 署名 / NOTICE 已按要求保留
- [ ] AC4.7 结论记录：这条链路是否值得继续投入，写入任务 `research/`

## 启动条件

- 道路编译器独立化父任务（Phase 0-3）已完成验收。
- 编译器仓库、稳定 CLI 与版本化输出契约已可用。
- 此任务不阻塞道路编译器抽离或渲染分离的交付。

## 明确不做

- junctionTools 做成扩展（API 不支持，见前提认知）
- 把 drawtonomy 放进生产构建链路
- 用 drawtonomy 替代编译器（D1 已否决）
- 自建通用白板编辑器

## 后续可能（不属本阶段）

父任务 design §4 的 D3 列了三项值得从 drawtonomy 借用的东西，
它们与本阶段独立，应各自开任务：

- `odrGeometryFit.ts` 的拟合器 → 替掉手调的
  `approachWidthMultiplier=1.45` / `coreRadiusMeters=28`，改为对 `referenceFile`
  拟合、残差作质量指标
- validator 的 mutation-proven 方法 → 给现有 31 条诊断规则建触发证明
- validator 的分层命名空间（`xml.*` / `ref.*` / `junction.*` / `geom.*`）
  → 替代当前平铺的 31 条规则