chore(task): archive 08-04-split-area-build-orchestration
This commit is contained in:
@@ -0,0 +1 @@
|
||||
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||
@@ -0,0 +1,24 @@
|
||||
# Split area build orchestration design
|
||||
|
||||
## Module Boundaries
|
||||
|
||||
```text
|
||||
scripts/lib/vehicle-route.js OSM XML -> preview route object
|
||||
scripts/lib/vehicle-model.js -> vehicle glTF object
|
||||
scripts/lib/area-preview.js HTML/template + runtime file copy + preview summary
|
||||
scripts/build-area.js dependency checks, writes, stage timing, manifest ownership
|
||||
```
|
||||
|
||||
`vehicle-route.js` and `vehicle-model.js` are pure Node modules. `area-preview.js` may use Node filesystem and path, but receives all names/paths through arguments; it must not import area config, stage manifest or spawn processes.
|
||||
|
||||
## Preview Flow
|
||||
|
||||
`build-area.writeCesiumPreview()` continues to ensure GLB/metadata, establish timing, write route/model/runtime/HTML in the existing order, and write `preview.manifest.json`. It delegates route construction, vehicle construction, support copy and HTML generation to the three modules.
|
||||
|
||||
## Compatibility
|
||||
|
||||
Public CLI and all generated filenames remain unchanged. The route's `generatedAt` naturally changes on each generation and is not a stable parity field; route segments, vehicle glTF structure and preview config are the stable contract. No Blender/GLB parity run is needed because no Blender or GLB generation code changes.
|
||||
|
||||
## Rollback
|
||||
|
||||
Restore the extracted functions to `build-area.js` and delete the three modules; no data migration or output cleanup is required.
|
||||
@@ -0,0 +1 @@
|
||||
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||
@@ -0,0 +1,20 @@
|
||||
# Split area build orchestration implementation plan
|
||||
|
||||
1. Extract vehicle route helpers into `vehicle-route.js`; add unit coverage using fixture OSM.
|
||||
2. Extract vehicle glTF builder into `vehicle-model.js`; assert schema, mesh/material counts and data URI.
|
||||
3. Extract preview support-file copy, HTML template, escaping and summary into `area-preview.js`.
|
||||
4. Replace `build-area.js` bodies with imports/calls while preserving preview manifest ownership and ordering.
|
||||
5. Run Node syntax/unit tests, then only the nantaizi `preview`, diagnose and quality gate commands.
|
||||
6. Update pipeline/preview specs and changelog; inspect diff for accidental stage or output changes.
|
||||
|
||||
## Validation
|
||||
|
||||
- `node --check scripts/build-area.js`
|
||||
- `node --check scripts/lib/vehicle-route.js`
|
||||
- `node --check scripts/lib/vehicle-model.js`
|
||||
- `node --check scripts/lib/area-preview.js`
|
||||
- `npm run test:preview-assets`
|
||||
- `npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages preview`
|
||||
- `npm run diagnose:area -- --config config/areas/nantaizi-lake-innovation-valley.json`
|
||||
- `npm run check:area -- --config config/areas/nantaizi-lake-innovation-valley.json`
|
||||
- `git diff --check`
|
||||
@@ -0,0 +1,41 @@
|
||||
# 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 所需值，避免模块反向读取区域配置或启动外部进程。
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "split-area-build-orchestration",
|
||||
"name": "split-area-build-orchestration",
|
||||
"title": "Split area build orchestration",
|
||||
"description": "Extract vehicle route, vehicle model, and preview assembly from build-area.js without changing area outputs.",
|
||||
"status": "completed",
|
||||
"dev_type": null,
|
||||
"scope": null,
|
||||
"package": null,
|
||||
"priority": "P2",
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-08-04",
|
||||
"completedAt": "2026-08-04",
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": null,
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {}
|
||||
}
|
||||
Reference in New Issue
Block a user