Files
Starlight_Lancher/.claude/skills/oil-frontend/references/resource-recognition-contract.md

3.0 KiB
Raw Blame History

资源识别规则

当任务涉及图片、对象身份、资源选择器或相邻对象区分时读取;列表结构和编辑流程由对应规则负责。

上层模型

集合界面的信息流按以下顺序设计:

识别对象 → 比较差异 → 判断状态 → 执行动作 → 查看详情

不要从数据库字段或现有组件出发决定展示内容。先判断用户需要如何区分对象,再选择最小信息集合。

最小识别单元

按以下优先级组合资源身份:

  1. 视觉身份头像、封面、缩略图、Logo、产品图或媒体帧
  2. 主名称:用户实际用于称呼和搜索的名称;
  3. 区分字段:在同名或相似资源间最有辨识度的一个字段;
  4. 有效状态:会影响选择、判断或操作的状态。

能用图片和名称准确区分时,不再增加次级信息。只有在相邻对象仍可能混淆或状态会改变选择时,才继续增加信息。

禁止用以下内容充当主要身份:

  • 原始数据库 ID
  • 无法阅读的长文件名;
  • 所有对象都相同的类型标签;
  • 装饰性图标;
  • 截断后彼此相同的文本;
  • 只显示状态而不显示对象。

图片优先

资源存在有辨识度的图片时:

  • 在列表、表格、选择器选项和已选结果中使用;
  • 对同一资源使用一致裁切和比例;
  • 使用真实缩略图,不用通用媒体图标代替;
  • 加载失败时使用稳定的兜底图片,并保留名称;
  • 不为没有识别价值的对象强行生成装饰图。

图片不能是唯一身份。始终保留可读名称。

选择器

选择器首先是资源识别器,不是字符串下拉框。

选项

每个选项使用:

  • 图片或视觉身份;
  • 主名称;
  • 必要区分字段;
  • 仅在影响可选性时显示状态。

不要只显示名称,除非名称在当前集合中天然唯一且清晰。

已选结果

收起后的触发器必须继续显示足够身份信息,让用户无需重新打开选择器就能确认选择:

  • 保留图片;
  • 保留主名称;
  • 名称不足以区分时保留区分字段;
  • 不只显示内部值、占位符或勾号。

搜索

  • 搜索覆盖界面上用于识别的名称与区分字段。
  • 结果高亮匹配信息,但不改变资源身份结构。
  • 数据量较大时提供搜索;不要要求用户浏览长列表。
  • 无结果时说明搜索条件未匹配,不把它误写成资源集合为空。

共享组件

建立统一资源身份组件。组件内部负责图片、兜底内容、主名称、区分字段和截断规则;使用组件的页面只传资源数据和使用场景,不传局部视觉样式。

审查问题

  • 不打开详情,能否区分相邻资源?
  • 移除某字段后是否仍能正确识别?
  • 是否遗漏了已有且更有辨识度的图片?
  • 图片是否真实参与识别?
  • 是否展示了所有对象都相同的信息?
  • 选择器收起后能否确认当前对象?
  • 同一资源在不同位置是否保持相同身份结构?