cat-catalog-schema-yaml

name	cat-catalog-schema-yaml
description	生成、解释和修改 Cat 项目的 `priv/config/catalog_schema.yaml`。当任务涉及 Catalog schema、Class / Property 定义、ClassProperty 绑定、Property.constraint、Class.subject_page_layout、claim_display、subject_explore_config，或需要为新领域生成可同步的 Catalog YAML 时使用。

Cat Catalog Schema YAML

这个 skill 只服务一个目标：正确生成和维护 priv/config/catalog_schema.yaml。

它是一份 Catalog 数据模型配置文件，声明系统里有哪些 Class、有哪些 Property，以及每个 Class 绑定哪些 Property。它也承载 Class 级页面展示配置，比如 subject_page_layout.claim_display 与 subject_explore_config。

开始前

生成或修改 YAML 前，先读取：

1. priv/config/catalog_schema.yaml：了解现有 class / property / 绑定关系，避免重复或覆盖既有语义
2. docs/skills/cat-catalog-schema-yaml/references/catalog-schema-reference.md：查看字段规则、默认值、常见配置和校验命令

必要时再查这些 PRD：

• docs/prds/catalog/data_model.md：Class、Property、constraint、layout、explore config 的权威字段说明
• docs/prds/catalog/commands.md：导入导出命令和 dry-run 语义
• docs/prds/catalog/overview.md：Catalog 与 Subjects / Web 的关系
• docs/prds/subjects/ui.md：claim_display 在前台详情页的展示分流语义

负责什么

• 新增或修改 classes
• 新增或修改 properties
• 维护 classes[].properties 绑定顺序和纠错配置
• 维护 properties[].constraint
• 维护 classes[].subject_page_layout
• 维护 classes[].subject_explore_config
• 生成可被 mix catalog.sync_catalog_schema --dry-run 校验通过的 YAML

不负责什么

• 不生成 priv/config/class_ingestors_schema.yaml；涉及 steam / wikidata provider 时使用 cat-class-ingestors-schema
• 不创建 Subject 内容数据
• 不把 Subject 固有字段建成 Property；例如条目名称、简介、别名、封面分别属于 subjects.label、subjects.description、subjects.aliases、subjects.cover_file_id
• 不写数据库主键 id
• 不把 Class 级展示策略写进 Property.constraint
• 不做任意低代码整页布局；subject_page_layout 只控制固定槽位

生成流程

1. 先读现有 priv/config/catalog_schema.yaml，找出目标 idname 是否已存在。
2. 先判断用户要求的字段是否已经是 Subject 固有字段；固有字段不要新增到根级 properties，也不要绑定到 classes[].properties。
3. 先设计根级 properties，再设计 classes[].properties 绑定。
4. 复用已有 Property，除非用户明确要求新建不同语义的 Property。
5. 为每个 Class 补齐默认字段：
   • description: ''
   • is_primary
   • correction_enabled
   • mark_enabled
   • mark_config
   • subject_page_layout
   • subject_explore_config
   • properties
6. 为每个 Property 补齐默认字段：
   • description: ''
   • datatype
   • constraint
7. 按前台展示需求配置 subject_page_layout.claim_display，确保引用的 property_idnames 已绑定当前 Class 且不重复。
8. 如需反查模块，配置 main_extra_modules[].type=reverse_subjects，并确认目标 Class 上的目标 Property 是 datatype=subject 且允许引用当前 Class。
9. 如需类型列表页筛选，配置 subject_explore_config，只引用当前 Class 已绑定且宽表可查询的 Property。
10. 编辑完成后运行 dry-run 校验：

mix catalog.sync_catalog_schema priv/config/catalog_schema.yaml --dry-run

输出要求

• 保持 YAML 根结构只有 classes 与 properties。
• 不写数据库 id、class_id、property_id。
• 不为 封面、简介 这类 Subject 固有字段创建重复 Property；封面应使用 cover_file_id，简介应使用 description。
• idname 是稳定接口，不随便重命名已有 idname。
• classes[].properties 的顺序就是 ClassProperty 的 display_index 顺序。
• vote_threshold 必须是正整数，默认使用 3。
• correction_mode 使用 disabled、report 或 vote。
• 缺少业务信息时先用最小合法配置，不要虚构难以校验的关联、筛选或外部导入映射。

常见默认配置

最小 Class：

correction_enabled: true
description: ''
idname: 图书
is_primary: true
label: 图书
mark_config: {}
mark_enabled: false
properties: []
subject_explore_config:
  filter_rows: []
  show_keyword_search: false
subject_page_layout:
  main_extra_modules: []
  version: 1

最小 Property：

constraint: {}
datatype: string
description: ''
idname: 作者
label: 作者

处理 claim_display

当用户说 hero 信息太多、属性要放到相册 / clips / sidebar 时，把配置放在 classes[].subject_page_layout.claim_display，不要放进 Property 或 ClassProperty。

固定槽位：

• hero_info：核心短属性，max_items 控制折叠态首屏显示项数，未设置时前端默认首屏显示 10 项，剩余 hero 项继续通过“展开更多”查看
• meta_clips：tag 或短枚举属性
• main_widgets：主栏 widget，例如 property_gallery
• sidebar_widgets：侧栏 widget，例如 property_list；前台渲染在固定 sidebar 模块（如分类、标记、评分分布、信息获取）下方
• overflow：承接未命中固定槽位且默认进入 sidebar 的属性，以及 clips 超限项，当前默认进固定 sidebar 模块下方的 sidebar_widget

校验与收尾

• 修改文件后优先跑 mix catalog.sync_catalog_schema priv/config/catalog_schema.yaml --dry-run。
• 如果只生成片段给用户而不写文件，明确说明尚未跑 dry-run。
• 如果 dry-run 报 invalid_subject_page_layout_definition，优先检查 claim_display 重复 property、未绑定 property、未知 slot/type、非法 limit。
• 如果 dry-run 报 invalid_property_constraint_definition，优先检查 datatype 与 constraint 块是否匹配。