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

来源票：[运行时资产 manifest 与版本策略](../issues/04-runtime-asset-manifest-and-versioning.md)

## 目标

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

## 资产边界

- 原始蓝湖设计包独立归档，用于设计追溯和重新导出。
- 仓库运行时只保存已确认进入发布的资源、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 再补资源。

## 发布校验与回滚

构建期和运行时均校验：

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

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

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

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

## Fallback 规则

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

## 远程资源例外

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

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

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

## 诊断状态

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

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

## 验收证据

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