Starlight_Lancher/.agents/skills/oil-frontend/references/state-and-loading-contract.md

状态与加载规则

当任务涉及 loading、refreshing、empty、error、processing、异步确认或后台长任务时读取；数据归属和操作范围由数据与操作范围规则负责。

状态矩阵

范围	Loading	Empty	Error	Processing	Ready
应用启动 / 路由	品牌全局加载组件	不适用	全局恢复入口	不适用	应用骨架
页面 / 集合	与最终布局同构的顶部骨架	原因 + 一个恢复动作	错误说明 + 重试	单项状态留在对象上	正常内容
面板 / 弹窗	局部骨架并保持尺寸	局部空状态	局部重试	状态文字和必要进度	正常详情
按钮提交	共享按钮 loading 状态	不适用	就近错误反馈	防重复提交	成功结果
长任务单项	不使用持续 spinner	不适用	失败原因 + 恢复动作	等待 / 处理中	完成

状态词汇

• loading：首次获取当前区域的数据，尚无可保留内容。
• refreshing：当前区域已有可保留内容，正在获取新的查询结果。
• ready：当前区域已有可使用内容。
• empty：资源集合本身为空。
• filtered-empty：资源集合可能存在，但当前筛选或搜索没有匹配结果。
• processing：当前区域的操作正在执行。
• queued：长任务已被接受，正在等待执行。
• error：当前区域加载或操作失败，并需要解释或恢复动作。

界面文案可以本地化，但状态判断、组件属性和验证报告统一使用以上词汇。

硬性规则

• 禁止大面积 spinner、旋转环和无内容遮罩。
• 禁止把页面加载误做成居中的空状态。
• 禁止让有限骨架占满剩余视口并漂在内容区中央。
• 禁止让骨架复制与最终布局无关的通用矩形。
• 禁止用 spinner 长期表达后台任务状态。
• 禁止同时显示 loading 与 empty，或 processing 与 “no results”。
• 禁止把 loading 放入 EmptyState 或复用空状态容器。
• 同一对象和同一范围只显示一种加载反馈。
• 禁止在每个页面自行实现加载动画。
• 禁止异步确认一提交就关闭弹窗，再让用户从未变化的底层界面猜测请求是否完成。

全局加载

全局加载只负责应用初始化或路由级切换。使用唯一共享组件，保持品牌信号和稳定位置。全局组件自行拥有视觉，不复用按钮、列表或单项任务的局部进度组件。页面不得覆写其视觉，也不得把它替换为集合骨架。

加载结构由谁负责

• 共享骨架原语只负责颜色、圆角和动画，不负责猜测页面结构。
• 被加载的共享业务组件或布局组件负责骨架的页面结构、数量、尺寸和排列。
• 骨架复用最终组件对应的内容区域、相对比例和内容轨道，不复制会造成额外滚动的最小宽度、固定高度或完整数据量。
• 禁止让万能加载器根据粗粒度布局名称猜测页面结构。
• 可以由共享业务组件提供 loading 状态或同目录骨架组件；禁止使用组件的页面重新发明动画。

页面与集合骨架

骨架必须：

• 位于最终内容出现的位置；
• 保留最终页面中稳定存在的 Header、Toolbar、表头和容器，只替换尚未返回的数据；
• 由最终资源卡片、列表行、表格行或面板结构组合；
• 保持内容轨道宽度；
• 从顶部开始；
• 高度由占位内容决定，不用剩余视口高度把有限行数拉成整屏；
• 不得产生最终内容之外的滚动；宽表骨架压缩展示当前视口可见的列，不复刻完整表格的最小宽度；
• 在数据到达后不产生明显布局位移。

加载范围

情况	呈现
首次加载且没有旧数据	与最终内容同构的骨架
刷新、筛选或翻页且已有数据	保留同一已提交查询快照，在触发控件或容器上表达 refreshing；列表与总数在新响应完成后一起更新
按钮提交	按钮自身的 loading 状态
单个资源加载	只更新对应资源、媒体槽或状态位置
后台长任务	对象状态和必要进度，不持续占用操作控件

不要因为局部请求清空整个页面，也不要为同一请求同时显示活动图标、骨架、进度条和状态文字。

按钮加载

按钮加载由共享操作组件拥有。组件需：

• 保持原按钮宽度；
• 保留或稳定表达原动作；
• 禁用重复提交；
• 使用紧凑、非旋转或品牌一致的进度信号。

禁止在使用组件的位置手工插入加载动画、改内边距或写临时宽度。

异步确认弹窗

删除、移除、撤销、发布、保存等需要等待请求结果的确认动作，必须遵守同一生命周期：

1. 提交后保持弹窗、确认对象和影响说明不变，确认按钮进入共享 loading 状态并阻止重复提交。
2. 请求没有真实取消能力时，处理中禁用取消、关闭、点击遮罩和 Escape 关闭；不能让弹窗消失后请求仍在后台继续。
3. 只有请求成功且原界面的可见状态已经提交或刷新后，才关闭弹窗。不得先关闭弹窗，再等待列表、详情或状态可能更新。
4. 请求失败时保持弹窗和原对象，恢复确认按钮，并在弹窗内或紧邻操作的位置显示可恢复的错误；不得要求用户重新找到对象并再次打开确认流程。
5. 只有动作明确转为可观察的 queued / processing 长任务，且原界面已经显示对应对象状态时，弹窗才可以在任务最终完成前关闭。

这套生命周期由共享确认弹窗和负责业务请求的数据流共同保证。页面不得只关闭本地弹窗状态而丢弃仍在处理的对象，也不得用全页 busy 代替确认按钮的局部反馈。

后台任务

后台长任务应成为对象生命周期：

queued → processing → ready | error

列表显示短状态；详情显示解释、进度、错误和恢复动作。状态变化不得要求用户靠观察 spinner 猜测。