Starlight_Lancher/.agents/skills/oil-frontend/references/collection-and-detail-contract.md

列表、详情与表格规则

当任务涉及列表、卡片、详情、表格或批量操作时读取；字段编辑和数据请求由对应规则负责。

列表与详情

列表只回答：

• 有哪些资源；
• 它们有什么决策相关的差异；
• 用户应该打开哪一个。

列表项只保留：

• 资源身份；
• 一个影响判断的状态；
• 完成当前比较所需的最小字段集合；
• 主体点击目标；
• “更多”入口。

详情承载：

• 完整媒体预览；
• 分析、证据和错误原因；
• 关联资源；
• 编辑、保存和确认流程；
• 历史与低频设置。

禁止：

• 把完整分析摘要放进列表；
• 卡片主体和 View 按钮执行同一动作；
• 在卡片页脚平铺重命名、刷新和删除；
• 列表媒体暴露完整播放控件。

卡片列表还是展示表格

按当前任务和对象内容选择，不按页面形式偏好选择：

• 用户需要横向比较同一字段在多个对象间的差异（数值、状态、日期、价格）时，表格的比较效率更高。
• 用户主要通过图片和内容差异识别、挑选对象，字段不适合横向比较时，使用卡片或列表。
• 每行主要内容是长文、完整媒体或复杂预览时，使用卡片或列表，不压缩进表格行。
• 单对象深度创作使用详情页或完整工作区，不使用集合表格。
• 行内操作多于比较信息时，使用列表或卡片承载身份和入口，把完整操作移入详情。
• 两者都可以且既有结构符合本规范时，沿用项目中同类集合页面的结构；既有结构本身导致识别、动作或空间问题时，修复或替换该模式并修改相关页面，不再复制错误。
• 同一项目中同一类对象只保留一种主要集合形态；卡片与表格视图切换只在用户确实需要两种任务模式时提供。

表格信息

一行对应一个真实业务对象。第一个稳定内容列使用统一资源身份组件；复选框、序号等工具列可以位于其前。其他列必须回答：

• 与其他对象有什么决策相关差异；
• 当前处于什么状态；
• 哪个字段需要直接修改；
• 当前可执行什么操作。

没有明确答案的列删除。不要把详情字段逐列搬进表格。

单元格结构

• 一个单元格只承担一种主要职责：识别、比较、状态、编辑或操作。
• 同一行的可编辑单元格使用相同高度、垂直结构和对齐基线。
• 单元格使用稳定、可快速横向扫描的主次层级；新增层级不再帮助比较时移入单行编辑器或详情。
• 单元格出现多个独立操作或完整预览时，移入单行编辑器。
• 禁止在单元格内拼装“预览 + 状态 + 数量 + 操作”的迷你卡片。
• 影响多个字段的动作属于行级操作或编辑器，不得附着在某个字段列中。
• 空资源没有可识别图片时，不保留大缩略图槽或装饰性占位。

表格操作

• 只有存在真实批量动作时才显示多选框。
• 编辑器修改原行对象，返回后状态仍在原行。
• 低频管理操作进入行末“更多”。
• 行点击打开详情时，单元格控件不得同时触发行点击。
• 排序和筛选只用于确实需要比较或缩小范围的字段。
• 状态只在固定列中表达一次。
• 行级动作进入固定操作列，不在字段内容下方形成第二排按钮。
• 展示表格列数超出目标视口的比较能力时，删除低价值列或移入详情。
• 可编辑工作表按任务阶段组织相邻列，并固定身份列与操作列；横向滚动遵循 视口与弹窗规则。
• 集合内媒体只提供轻量预览；播放对象离开当前筛选或分页时停止播放，除非页面提供始终可见的播放控制。

对象跨阶段的更新与派生规则遵循 数据与操作范围规则。

检查

• 不打开详情能否选出目标资源？
• 列表是否泄漏详情内容？
• 是否存在重复查看入口？
• 每一列是否影响比较、状态、编辑或操作？
• 是否为了表格形式而保留无用列？
• 同一行是否出现不同的单元格结构和操作基线？
• 是否存在迷你卡片、第二排控件或不参与判断的辅助文字？
• 是否存在两套重复对象或状态？