62 lines
4.1 KiB
Markdown
62 lines
4.1 KiB
Markdown
# Reusable asset package contract
|
||
|
||
## Goal
|
||
|
||
将当前面向 Cesium 预览的区域输出升级为可由多个下游项目稳定消费的静态资产包。资产包
|
||
必须有版本化 manifest、仅使用包内相对引用，并明确发布资产与本项目调试/预览产物的边界。
|
||
|
||
## Confirmed Facts
|
||
|
||
- `blender/export_cesium.py` 已生成 `<area>.json`，包含主 GLB、roads/buildings/
|
||
vegetation/water 分层 GLB、WGS84 anchor、ENU 坐标约定、heading correction 和 OSM bounds。
|
||
- 该 JSON 同时包含桌面绝对 `source_osm` / `source_geojson` 路径、Cesium 代码片段，以及
|
||
动态信号灯和倒计时预览资产；因此不是可发布的下游契约。
|
||
- `outputs/<area>/` 还包含 QGIS、GeoJSON、Blender、Cesium HTML/runtime、车辆巡航和自检文件；
|
||
它是构建工作目录，不是干净的发布目录。
|
||
- 当前默认 Cesium GLB 已在构建末端压缩，且 metadata 中的资产 URL 使用同目录相对文件名。
|
||
- 项目目标是生成可复用资产；交通仿真、跟车和信号调度属于下游运行时能力，不属于资产包首版。
|
||
|
||
## Requirements
|
||
|
||
- R1：定义一个版本化 `manifest.json` v1，描述区域 ID、WGS84 anchor、ENU 轴向与 heading
|
||
correction、WGS84 bounds、发布资产、语义类别和包内相对路径。
|
||
- R2：资产包只含可复用的静态交付资产；主场景和道路、建筑、植被、水体等分层模型必须有
|
||
明确的角色、加载语义和默认行为。
|
||
- R3：manifest 和包内文件不得包含桌面绝对路径、构建临时目录、Cesium HTML/runtime、
|
||
QGIS、GeoJSON、`.blend`、车辆巡航或动态交通信号调度依赖。
|
||
- R4：在不破坏现有区域预览、诊断和构建中间产物的前提下，增加明确的资产包发布阶段。
|
||
- R5：提供 Cesium 与 Three.js 的最小加载示例，均从 manifest 读取包内相对 URL，并按相同的
|
||
WGS84/ENU 契约放置主场景或分层资产。
|
||
- R6：定义发布资产、可选静态资产和本项目仅检查产物的分类规则，并由测试验证。
|
||
- R7：完整构建后的资产包应可独立复制到其他项目，而无需本仓库的 `outputs` 目录结构或本地路径。
|
||
|
||
## Acceptance Criteria
|
||
|
||
- [ ] 目标区域生成一个可独立分发的资产包目录，其中仅有 manifest 和 manifest 引用的发布资产。
|
||
- [ ] manifest 的 schema version、坐标契约、bounds、所有资产类别和 URL 可由程序校验。
|
||
- [ ] 所有 manifest URL 都是安全的包内相对路径；不得含绝对路径、`..` 或未声明文件。
|
||
- [ ] 主 GLB 与每个发布分层资产都能在 Cesium 和 Three.js 示例中按 manifest 正确放置与加载。
|
||
- [ ] 车辆、巡航路线、Cesium preview HTML/runtime、QGIS/GeoJSON/`.blend` 和动态信号调度资产
|
||
不会进入发布包。
|
||
- [ ] 既有 `outputs/<area>/` 预览工作流继续可用，现有非交互 build 命令保持兼容。
|
||
- [ ] 发布包缺文件、manifest 路径越界、坐标字段无效或资产类别不合法时，构建/校验非零退出。
|
||
|
||
## Proposed Delivery Phases
|
||
|
||
1. 契约与目录边界：冻结 manifest v1 schema、发布目录结构、资产角色和坐标定义。
|
||
2. 资产包发布阶段：从现有 Cesium 导出与压缩结果收集、校验并写入独立包目录。
|
||
3. 下游消费证明：Cesium / Three.js 示例仅依赖 manifest 与包内容，并覆盖主场景和按类别加载。
|
||
4. 质量门与迁移：增加结构、路径隔离、坐标和加载验证；保留旧预览输出并记录迁移规则。
|
||
|
||
## Key Decision
|
||
|
||
- 发布包根目录固定为 `outputs/<area-id>/package/`。该目录是可整体复制给下游项目的唯一
|
||
发布边界；GLB 和 manifest 直接生成或移动到这里，避免与工作目录再保留一套大模型副本。
|
||
本项目的预览页可通过包内相对路径读取发布资产，但 HTML/runtime 本身不属于发布包。
|
||
|
||
## Out Of Scope
|
||
|
||
- 交通流、车辆行为、信号相位控制、路口调度和其他运行时仿真。
|
||
- 在本任务中扩展 OSM 到建筑、路灯、标志、植被等资产覆盖率或生成质量。
|
||
- 删除既有 `outputs/<area>/` 中由用户保留的历史调试产物。
|