osmWorkflow/.trellis/tasks/08-25-rc-p1-package-boundary/prd.md

Phase 1：包边界（不换仓库）

父任务：.trellis/tasks/08-25-road-compiler-extraction/ 技术设计：父任务 design.md §2（模块清单 / K1 拆分建议）

Goal

在当前仓库内建立 packages/road-compiler/，移入编译器全部模块， 把对 readAreaConfig 的耦合换成窄输入契约，产物对 Phase 0 基线逐字节一致。

本阶段不换仓库。 目的是把"改坏了编译器"与"拆坏了仓库"分成两个可归因的步骤 （父任务 D4）。

Requirements

R1.1 目录与模块搬迁

在 packages/road-compiler/ 内建立结构，移入父任务 design.md §2.1 列出的全部文件 （约 3400 行核心 + workbench）。

搬迁后 scripts/lib/ 下不应再留下这些文件的副本 —— 并存会导致 "改了一份忘了另一份"的静默不一致。

R1.2 窄输入契约

• 编译器入口只接受父任务 design.md §1.1 定义的 RoadCompilerInput
• 编译器内不得出现 require("area-config")、不得读 config/areas/*.json、 不得从 areaId 推导任何路径
• 宿主 scripts/lib/area-config.js 新增 toRoadCompilerInput(area) 做映射
• 三个 CLI（compile / check / workbench）改为接受显式参数或 input JSON

R1.3 K1：traffic-signals.js 拆分 🔴

全案唯一需要细读再动的地方。 按父任务 design.md §2.3：

• 随编译器走：OSM 信号节点提取 + 信号文档 schema
• 留宿主：readTrafficSignalFeatures（build-osm2streets-qgis.js）、 readTrafficSignals（build-area.js）
• 待判定：buildTrafficSignals（test-preview-assets.js）—— 需读代码确认归属
• 拆完后宿主从编译器包 import schema（宿主→编译器是允许方向）

动手前必须先产出一份「函数 × 使用方」矩阵，确认无遗漏。

R1.4 K3：参考文件路径约定

config/areas/fengshu-er-road.json 的 junctionTemplates.clusters[].referenceFile 是指向宿主仓库的绝对路径。

• 定义解析约定：相对 config 文件所在目录，或由宿主在 toRoadCompilerInput() 中解析为绝对路径后传入
• 倾向后者：编译器只接受已解析的绝对路径，不做路径推导（符合 R1.2）
• config 内改为相对路径，宿主负责解析

R1.5 K5：自带测试 fixture

• test-native-road.js:167 读 inputs/osm/枫树二路.osm
• 该文件（或裁剪版）复制进 packages/road-compiler/test/fixtures/
• 测试改为读包内 fixture，不再访问宿主 inputs/
• 目标：编译器包 npm test 不依赖宿主任何目录

R1.6 宿主侧接线保持不变

• build-area.js 本阶段继续 in-process require（子进程改造留到 Phase 2）
• npm run road:compile / road:check / road:workbench 行为对用户不变
• blender/ 完全不改

Acceptance Criteria

• AC1.1 三区域 road-parity --compare 对 Phase 0 基线全绿
• AC1.2 npm run test:native-road、npm run test:road-workbench 通过
• AC1.3 npm run build:area 三区域完整跑通（含 blender / cesium 阶段）
• AC1.4 grep -rn "area-config\|config/areas" packages/road-compiler/ 无命中
• AC1.5 packages/road-compiler/ 内 npm test 不访问宿主 inputs/ 或 outputs/
• AC1.6 scripts/lib/ 下无搬迁文件的残留副本
• AC1.7 K1 的「函数 × 使用方」矩阵已产出并归档到 research/
• AC1.8 compiled.json 结构未变（父任务 AC7 / C1）

依赖与顺序

• 前置：Phase 0 必须完成且基线可靠
• 阻塞：Phase 2
• 与 Phase 3、4 无直接依赖，但它们都在 Phase 2 之后

风险

风险	缓解
K1 拆分遗漏某个使用方 → 运行时才炸	先做矩阵，再动代码；grep -rn 全仓验证
搬迁过程中相对 require 路径改错	分小步 commit，每步跑 parity
workbench/app.js 的 OpenLayers import map 指向宿主 node_modules	本阶段仍在同仓库，可暂不处理；记入 Phase 2（K4）
一次性大搬迁难以归因	按模块分批：先纯函数（lane-geometry / gaode-reference），再 complex-junction，最后 native-road 与 CLI

Out of Scope

• 换仓库（Phase 2）
• layer manifest（Phase 3）
• IR / pass manager 重构（父任务 C1）
• 引入 TypeScript 或构建步骤（父任务 C2）