42 lines
2.8 KiB
Markdown
42 lines
2.8 KiB
Markdown
# Split area build orchestration
|
||
|
||
## Goal
|
||
|
||
将区域构建入口收敛为阶段调度器，把车辆路线、车辆 glTF 和 Cesium preview 组装移到职责明确的模块，降低后续修改预览功能时触碰 QGIS/Blender/Cesium 调度逻辑的风险。
|
||
|
||
## Confirmed Facts
|
||
|
||
- `scripts/build-area.js` 负责阶段调度，但其 440-928 行还包含 preview manifest、OSM 路线解析、路线几何、车辆 glTF 建模、HTML 模板和转义。
|
||
- `preview` 已有独立 manifest ownership；`cesium` 调用 preview 生成，但 standalone `--stages preview` 必须继续有效。
|
||
- preview HTML 向浏览器运行时注入 `areaId`、GLB、metadata、route 和 vehicle model 文件名；HTML / script JSON 使用不同转义函数。
|
||
- 车辆路线和车辆 glTF 是预览辅助产物，不改变主 GLB；其内容仍属于 preview manifest 输出。
|
||
- 本任务只验证南台子，不能改动 `hanyang-block` 或主动重跑重型阶段。
|
||
|
||
## Requirements
|
||
|
||
1. 新建纯 Node 模块承载 OSM 到车辆路线的解析与几何计算，保持 route JSON 的字段、排序、lane offset、时间戳语义和 deterministic coordinates 不变。
|
||
2. 新建纯 Node 模块承载 preview 车辆 glTF 生成，保持 glTF schema、mesh/material 名称和二进制布局不变。
|
||
3. 新建 preview assembly 模块承载 runtime 文件复制、HTML 模板与安全转义；`build-area.js` 仍拥有 preview 阶段依赖检查、文件写入顺序和 manifest 写入。
|
||
4. 主入口不再定义以上预览/车辆实现细节，只通过模块 API 组装 preview 阶段。
|
||
5. 不改变 CLI、stage 名称/aliases、stdout marker、manifest 字段、输出路径、默认行为或浏览器运行时。
|
||
6. 对抽出的纯逻辑补 Node 测试，验证路线与 vehicle glTF 结构；通过南台子 preview 阶段和 diagnostics/check 确认真实产物仍有效。
|
||
|
||
## Acceptance Criteria
|
||
|
||
- [x] `build-area.js` 不再含路线解析、车辆 glTF mesh 构建、preview HTML 模板或转义实现。
|
||
- [x] 新模块在不依赖 Blender/QGIS 的 Node 测试中覆盖路线和车辆 glTF 关键结构。
|
||
- [x] 南台子 `--stages preview` 成功，preview manifest 仍 fresh，route / vehicle / HTML 文件可读且配置文件名不变。
|
||
- [x] `diagnose:area` 和 `check:area` 对南台子仍通过。
|
||
- [x] 所有修改脚本通过 Node 语法检查、`git diff --check`，且不运行 `hanyang-block`。
|
||
|
||
## Out Of Scope
|
||
|
||
- 不改变车辆路线算法、车模型外观、预览 HTML/UI、Cesium runtime 或 GLB 导出。
|
||
- 不拆分 QGIS、Blender、Cesium 或 compression 的阶段实现。
|
||
- 不新增前端构建系统或运行时依赖。
|
||
|
||
## Key Decisions
|
||
|
||
- 这是保守纯重构；输出内容和 manifest 契约比文件行数更重要。
|
||
- preview assembly 依赖注入 filesystem/path/manifest 所需值，避免模块反向读取区域配置或启动外部进程。
|