3.9 KiB
3.9 KiB
本地构建控制台
Goal
提供一个在本机 localhost 运行的图形控制台,使用户无需记忆命令行即可选择或导入道路构建输入、执行现有构建管线、查看进度并打开 Cesium 预览。
Confirmed facts
- 当前唯一的交互入口是
scripts/interactive-build.js:它枚举config/areas/*.json、选择阶段后调用scripts/build-area.js。 build-area.js是构建、Blender/Cesium 子进程、package 发布和 preview 写入的唯一所有者;控制台必须调用它,不能复制阶段实现。- native 区域配置通过
nativeRoadPackage引用native-road-package/v1.1ZIP;导入器会验证 ZIP 契约和areaId,并将其安全解压到私有 pipeline cache。 - Blender 与本地文件系统不能由纯静态浏览器页面直接访问,因此入口必须由本机服务配合浏览器 UI 组成。
- 现有配置及其
outputs/<area>/_pipeline/stages/*.manifest.json是历史输入和构建历史的可读取事实源,不能另建会漂移的重复数据库。
Requirements
- R1: 以 localhost 页面作为首版交付方式;命令行入口继续可用。
- R2: 首页自动枚举并导入
config/areas/*.json,以区域卡片呈现可复用配置、输入摘要、最近构建状态、预览与发布包入口。 - R3: 用户可从界面选择 OSM 与 native-road ZIP,读取 ZIP 的
areaId和契约信息,并在构建前给出 OSM/ZIP/区域 ID 的明确校验反馈。 - R3.1: 成功导入的 OSM 与道路 ZIP 复制到项目托管输入目录;新配置引用托管副本,保证可复现且不依赖
/tmp或用户外部路径。 - R4: 保持首版简单:构建前仅可选择项目已有的植被/树木风格;Cesium 预览中可选择车辆模型。两者分别影响静态场景与演示运行时。
- R5: 用户可选构建阶段并启动现有 build-area 管线,看到实时阶段状态、日志、产物链接与可行动的失败说明。
- R6: 对历史配置的修改默认另存为新配置;覆盖已有配置必须是显式确认操作。
- R6.1: 控制台提供单项清理与批量清理,仅处理它创建的托管输入和本项目生成的区域输出;绝不删除用户在项目外选择的原始文件。首版清理统一移入系统废纸篓,保留恢复机会。
- R6.2: 清理范围分为两级,且单项、批量均适用:
清理构建产物仅移除区域输出并保留配置和托管输入;移除区域将区域配置、控制台托管输入和区域输出一并移入废纸篓。批量操作必须先展示受影响区域和文件数,再允许确认。 - R7: 产品内置首次使用引导:说明 OSM、道路 ZIP、模型选项、构建阶段、预览入口和 Blender/Node 环境检查,不以外部 README 代替。
Out of scope
- 改写道路编译器、ZIP 契约、Blender 几何或 Cesium 预览运行时。
- 远程部署、多用户协作、云端构建或将本机文件上传到第三方服务。
- 第一阶段打包为 macOS
.app;待 localhost 工作流验证后再评估。
Acceptance criteria
- 用户可在浏览器中启动、选择历史区域并重新执行一次已有构建,无需手写 CLI 参数。
- 用户可导入 OSM 与有效道路 ZIP,且在启动 Blender 前看到 ZIP contract / areaId / 文件缺失的校验结果。
- 用户可保存为新的区域配置而不改变原配置;显式覆盖有确认保护。
- 页面可展示构建阶段、实时日志、成功后的 preview URL 与
package/manifest.json。 - 首次使用者可仅依照页面引导完成一次输入、构建和预览,并理解失败时下一步怎么做。
Technical notes
- native-road ZIP 的
areaId与区域配置id必须相等;控制台应从 ZIP 读取并锁定该 ID,避免提供必然失败的可编辑字段。 - 控制台管理的输入需要有可判定 ownership 的目录/记录,才能安全实施区域级清理;历史配置引用的外部路径始终视为只读、非托管输入。