运行时资产 manifest 与版本策略规格

来源票：运行时资产 manifest 与版本策略

目标

让正式蓝湖资源在驾驶舱运行时中具备稳定语义入口、可追溯来源、可重复部署、可安全缓存、可诊断失败并可回滚。组件、地图服务和设备资产选择层不得散落蓝湖导出文件路径。

资产边界

原始蓝湖设计包独立归档，用于设计追溯和重新导出。
仓库运行时只保存已确认进入发布的资源、manifest 和来源/校验元数据。
运行时资源统一进入驾驶舱自有 public/cockpit 资源边界。
默认生产不加载蓝湖、设计公司对象存储或任意外部 CDN 资源；远程 URL 只能通过登记和审批成为例外。
不改变现有 mode、panelId、地图图层、状态语义、拾取、定位、聚合和面板联动。

Manifest 权威模型

Manifest 是运行时资源的唯一权威入口。组件、地图服务和设备资产选择层只依赖语义 key 或其封装入口，不直接依赖物理文件路径。

每个条目至少包含：

稳定的语义 key；
运行时相对路径或登记过的远程 URL；
原始蓝湖来源画板和设计交付标识；
文件格式、像素尺寸、透明背景/密度等运行时属性；
所属发布版本和内容 hash；
状态：正式、临时、推导或降级；
适用业务对象、模式和状态；
显式 fallback key；
是否核心资源；
远程例外所需的域名和安全策略信息。

语义 key 稳定，物理文件名允许带内容 hash。组件不因设计公司重新导出或文件改名而改变业务引用。

目录与路径

资源发布到 public/cockpit 或其构建产物对应目录。
资源 URL 必须基于 import.meta.env.BASE_URL 或等效宿主注入基址解析。
禁止硬编码 /cockpit/...，必须兼容当前相对 publicPath 与 qiankun 注入路径。
环境可以覆盖资源根路径和受控发布版本，但不能覆盖语义 key、状态语义或 fallback 关系。

版本与缓存

每次发布有人工可读的发布版本。
每个资源条目同时记录内容 hash。
生产物理文件名使用内容 hash，支持长期不可变缓存和旧版本共存。
Manifest 使用短缓存或协商缓存，以便快速发现新发布；hash 资源使用长期不可变缓存。
Manifest 与资源必须作为同一个发布包原子更新，不允许先更新 manifest 再补资源。

发布校验与回滚

构建期和运行时均校验：

manifest schema；
发布版本字段；
条目完整性；
语义 key 唯一性；
路径安全性；
hash 格式；
fallback key 引用存在性；
远程 URL 是否属于允许域名。

以下情况触发整包回滚到上一版或内置基线：

manifest schema 或完整性校验失败；
核心资源组不可用；
发布版本不兼容；
资源与 manifest 的原子发布校验失败。

普通非核心资源失败不触发整包回滚，按条目 fallback 运行。

Fallback 规则

优先使用 manifest 条目指定的显式 fallback key。
fallback 自身失败时，继续有限回退链，最终使用内置通用资源。
每一级失败都记录语义 key、失败类别和最终回退状态。
不允许用错误业务语义的资源互相替代：品牌、点位状态、设备状态和事件等级必须各自保持语义边界。
不能访问蓝湖原始 URL 作为隐式重试或生产回退。

远程资源例外

允许远程资源前，必须登记：

来源系统和责任方；
明确允许的域名；
CORS/安全策略；
缓存策略；
请求超时；
失败 fallback key；
版本和可追溯标识。

未经 manifest 登记的远程 URL 一律拒绝加载。

诊断状态

提供统一的运行时资产诊断状态，供宿主 data-* 读数和调试面板消费。至少区分：manifest 不可用、条目缺失、路径不安全、hash/版本不匹配、远程域名未登记、资源加载失败、fallback 生效、最终通用资源生效。

开发/测试：可显示完整路径、hash、版本和内部错误。
生产：只暴露语义 key、失败类别、回退状态和用户可理解提示，不暴露内部路径或敏感配置。

验收证据

manifest schema、语义 key 唯一性、fallback 引用、路径安全和远程域名校验均有自动化测试。
资源与 manifest 不一致时可以拒绝该发布包并回滚。
hash 文件名在更新后不复用旧内容，manifest 短缓存能够发现新版本。
单个非核心资源失败不会阻塞驾驶舱，其 fallback 可被宿主读数观察。
核心资源组失败会回滚到上一版或内置基线。
/cockpit 与 qiankun 宿主下均能解析资源路径。
生产诊断不泄露内部路径，但能显示语义 key、失败类别和回退结果。