4.1 KiB
4.1 KiB
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.jsonv1，描述区域 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
- 契约与目录边界：冻结 manifest v1 schema、发布目录结构、资产角色和坐标定义。
- 资产包发布阶段：从现有 Cesium 导出与压缩结果收集、校验并写入独立包目录。
- 下游消费证明：Cesium / Three.js 示例仅依赖 manifest 与包内容，并覆盖主场景和按类别加载。
- 质量门与迁移：增加结构、路径隔离、坐标和加载验证；保留旧预览输出并记录迁移规则。
Key Decision
- 发布包根目录固定为
outputs/<area-id>/package/。该目录是可整体复制给下游项目的唯一 发布边界；GLB 和 manifest 直接生成或移动到这里，避免与工作目录再保留一套大模型副本。 本项目的预览页可通过包内相对路径读取发布资产，但 HTML/runtime 本身不属于发布包。
Out Of Scope
- 交通流、车辆行为、信号相位控制、路口调度和其他运行时仿真。
- 在本任务中扩展 OSM 到建筑、路灯、标志、植被等资产覆盖率或生成质量。
- 删除既有
outputs/<area>/中由用户保留的历史调试产物。