04-runtime-asset-manifest-and-versioning.md 4.5 KB
运行时资产 manifest 与版本策略
Type: grilling Status: resolved Labels: wayfinder:grilling Blocked by: 01, 02
Question
正式素材如何进入驾驶舱运行时并可追溯？裁定原始设计包与运行时资源的目录边界、语义 key 命名、文件格式和尺寸、manifest 结构、hash/版本、缓存失效、BASE_URL/qiankun 路径、资源加载失败记录，以及是否允许远程资源。
结论必须让组件、地图服务和设备资产选择层通过稳定语义入口消费资源，不允许各处散落蓝湖导出文件路径。
进度
- 已认领（
Status: claimed），前置票 01/02 已 resolved。 - 第一轮已裁定：Q1=B（原始设计包独立归档，仓库保存运行时资源、manifest、来源与校验信息）；Q2=A（manifest 是唯一权威入口）；Q3=A（资源统一进入
public/cockpit，通过BASE_URL访问）；Q4=A（条目记录语义 key、运行时路径、蓝湖来源、格式/尺寸、hash/版本、状态、适用对象/状态、fallback key）；Q5=B（生产默认禁止远程资源，审批例外除外）；Q6=B（语义 key 稳定，物理文件名可带版本/hash）；Q7=B（按条目 fallback key 回退并记录失败原因，不影响其他资源）。 - 第二轮已裁定：Q8=C（人工发布版本 + 条目内容 hash）；Q9=A（生产物理文件名带内容 hash）；Q10=B（manifest 与资源原子发布，整包校验失败回退上一版/内置基线）；Q11=B（环境仅覆盖资源根路径和受控版本，不改变语义 key、状态语义和 fallback）；Q12=B（manifest 短缓存/协商缓存，hash 资源长期不可变缓存）；Q13=B（统一运行时资产诊断状态，提供宿主
data-*/调试面板消费，生产隐藏内部路径但保留失败类别和语义 key）；Q14=B（远程例外必须登记来源、允许域名、CORS/安全策略、缓存、超时和 fallback，未登记 URL 拒绝）。 - 第三轮已裁定：Q15=B（校验 schema、发布版本、条目完整性、语义 key 唯一性、路径安全、hash 格式、fallback 引用和允许远程域名）；Q16=B（核心资源组/版本兼容或整包校验失败时整包回滚，普通非核心资源按条目 fallback）；Q17=B（显式 fallback key 优先，fallback 失败后有限链回退内置通用资源并记录各级失败）；Q18=B（开发/测试显示完整诊断，生产只暴露语义 key、失败类别、回退状态和用户提示）；Q19=B（issue 记录摘要并产出独立 manifest/版本规格，不直接改业务代码）。
- 讨论已收敛，已落盘 Answer 与独立规格。
Answer
已形成独立规格：运行时资产 manifest 与版本策略规格。核心决策如下：
- 原始蓝湖设计包独立归档；仓库只保存运行时资源、manifest、来源和校验信息。
- manifest 是唯一权威入口；组件、地图服务和设备资产选择层不直接引用物理路径。
- 资源统一进入
public/cockpit，通过BASE_URL/宿主注入路径解析，兼容 qiankun，不硬编码/cockpit/...。 - 条目记录稳定语义 key、运行时路径、蓝湖来源、格式/尺寸、发布版本、内容 hash、正式/临时/推导/降级状态、适用对象/状态、核心标记和 fallback key。
- 生产默认不加载远程资源；远程例外必须登记来源、允许域名、安全策略、缓存、超时和 fallback。
- 发布使用人工版本 + 内容 hash；生产物理文件名带 hash。manifest 短缓存/协商缓存，hash 资源长期不可变缓存。
- manifest 与资源原子发布；schema、完整性、key 唯一、路径安全、hash、fallback 引用和远程域名均需校验。
- 核心资源组、版本兼容或整包校验失败时回滚上一版/内置基线；普通非核心资源按条目 fallback。
- fallback 先走显式 fallback key，再走有限链和内置通用资源，各级失败均可诊断。
- 开发/测试暴露完整诊断；生产仅暴露语义 key、失败类别、回退状态和用户提示，不暴露内部路径/敏感配置。
真实状态与下一步
- 状态：已完成并关闭。
- 交付物：
specs/04-runtime-asset-manifest-and-versioning.md。 - 下一步：已通过
/to-spec发布同一张地图上的 运行时资产 manifest 与版本策略规格（ready-for-agent）；后续推进监测点与监测设备位置符号映射和字体授权与缺失资源降级。