wp-acf-and-content-modeling

WordPress ACF 和内容建模技能

概述

用于系统审查依赖 Advanced Custom Fields 和自定义内容架构的 WordPress 项目的技能。核心原则： 健全的 WordPress 内容模型应持久耐用、兼顾查询需求、便于编辑，并且迁移过程可预测。审查重点包括 CPT 和分类法设计、字段组划分、命名一致性、存储策略、ACF JSON 同步，以及元数据过多模式的长期成本。按文件或子系统分组报告发现，并标注严重程度（CRITICAL、WARNING、INFO），尽可能注明行号，并提供具体的修复建议。

适用场景

适用于：

• 审查注册了自定义文章类型、分类法或 ACF 字段组的插件或主题
• 审查 acf_add_local_field_group() 或字段组 JSON 导出文件
• 检查重复器／灵活内容是否适合当前内容需求
• 评估选项页、关系字段、克隆字段或区块字段组
• 调查内容密集型项目中速度缓慢的管理界面或开销较大的 meta_query
• 为编辑型网站、目录、落地页构建器或无头架构规划新的内容模型
• 审查 ACF JSON 同步、字段键偏差，或不同环境之间的可移植性

不适用于：

• 不涉及实质性 ACF／内容建模工作的通用插件架构（使用 wp-plugin-development）
• 纯 REST 路由设计（使用 wp-rest-api-development）
• 与字段建模无关的 Gutenberg 区块实现细节（使用 wp-block-development）
• 与内容架构或元数据访问无关的性能审计（使用 wp-performance-review）
• WooCommerce 领域建模（除非问题确实属于通用 ACF 建模，否则使用 wp-woocommerce-dev）

审查工作流

遵循以下七步工作流。

1. 确定模型边界

   • 实际领域是什么：文章、地点、员工、产品、活动、落地页、设置，还是可复用内容片段？
   • 确定该模型面向单站点、多站点还是无头架构。
   • 在评估实现质量之前，先盘点 CPT、自定义分类法、选项页和字段组。

2. 先检查核心内容实体

   • 验证每个 CPT 都有明确用途，不会无故重复文章或页面的功能。
   • 检查自定义分类法是否比额外的文本字段或元字段更适合建模分类和关系。
   • 标记那些被当作无关内容收纳箱的过载文章类型。

3. 审查字段组架构

   • 检查位置规则、命名惯例、说明、条件逻辑、默认值和必填标记。
   • 检查字段组是否按编辑任务拆分，而不是变成庞大的单体结构。
   • 确认有意使用重复器和灵活内容，而不是用它们代替缺失的实体设计。

4. 扫描 CRITICAL 模式

   • 字段名称或数据结构发生变化，却没有迁移路径。
   • 代码直接依赖特定环境的字段键。
   • 应以关系或分类法建模的内容，却存储为纯文本块。
   • 核心归档或搜索行为严重依赖 meta_query，且没有任何缓解措施。
   • 明显需要独立实体的场景，却使用灵活内容或重复器结构。
   • 将选项页的值视为请求专属内容，却未考虑缓存或失效问题。

5. 检查 WARNING 模式

   • 字段名称含义模糊（title、image、link），且没有领域前缀或上下文。
   • 字段组重复，或克隆的定义在不同环境中逐渐不一致。
   • 关系/文章对象字段的返回格式不一致。
   • 向编辑人员开放的字段说明薄弱、没有默认值，或条件逻辑不明确。
   • ACF JSON 的启用方式不一致，或提交记录不可靠。
   • 重复器过多的落地页可能会变得无法查询、复用或迁移。

6. 记录 INFO 改进建议

   • 自定义分类法可以改善筛选、SEO 或编辑一致性。
   • 选项页可以取代重复的逐页设置。
   • 对于高容量结构化数据，使用自定义表可能更合理。
   • 共享组件可以从克隆字段或可复用区块策略中获益。
   • 字段说明、选项卡和分组可以降低编辑错误率。

7. 根据上下文确定严重程度并报告

   • 企业/编辑型网站：优先考虑治理、迁移安全、查询行为和编辑体验。
   • 营销/落地页构建器：优先考虑可维护性和编辑约束，而非抽象的纯粹性。
   • 无头网站：优先考虑架构稳定性、API 暴露形式和关系建模。
   • 如果发现的问题后续应交由 wp-rest-api-development、wp-performance-review 或 wp-block-development 处理，请添加跨技能备注。

模型级检查

内容类型设计（ACF-01）

CRITICAL

• 将多个无关的业务概念强行放进同一个 CPT，并让 type、layout 或 kind 等标记承担所有区分工作
• CPT 仅用于模拟应属于现有内容类型的字段分组
• 重要的关系型内容存储在序列化数组或长文本字段中，而不是结构化实体中

WARNING

• CPT 标签、支持项或归档行为与编辑意图不符
• 文章类型依赖自定义字段来承载主要标题或别名，而核心标题/别名本应承担这一职责
• 内容的可发现性完全依赖自定义排序/元数据，而非分类法或日期语义

INFO

• 自定义分类法可能比另一个布尔值/选择字段更合适
• 小型可复用文章类型可能简化重复的分区内容或共享落地页片段

分类法设计（ACF-02）

严重

• 值得用分类法管理的分类数据被建模为自由文本字段，导致拼写重复和筛选失效
• 关系语义被迫用重复的文本／选择字段表示，而不是使用分类项或关系字段

警告

• 分类法范围过宽，在同一结构中混杂受众、主题、地点和工作流状态
• 应使用扁平标签时却用了分层分类法，反之亦然
• 为核心实体内容添加了分类项元数据，而这些内容很可能值得拥有独立实体

信息

• 分类法通常可以替代容易出错的编辑器手动输入标签，并提升可查询性

字段命名与架构稳定性（ACF-03）

严重

• 在没有必要的情况下，代码依赖 field_123abc 这样的字段键，而不是稳定的字段名称
• 字段名称更改后没有迁移或向后兼容处理
• 两个无关字段在不同上下文中使用了极其相似的名称，导致模板混淆

警告

• 名称过于笼统（title、cta、copy、image），脱离单个模板后就失去含义
• 不同领域的前缀使用不一致（hero_、event_、team_ 混用且缺乏规律）
• 同一概念字段在不同字段组中的返回格式悄然不一致

信息

• 为相关字段添加领域或组件前缀，以便于 grep 搜索和未来迁移

Repeater 与 Flexible Content 的使用（ACF-04）

严重

• 将 Flexible Content 用作缺乏治理的完整站点构建器，导致内容组合无法测试
• Repeater 存储的数据需要独立 URL、复用、所有权或筛选
• 巨大的嵌套 Repeater 被当作关系型数据表来查询或转换

警告

• Repeater 行没有最小／最大数量限制或编辑器说明
• Flexible Content 布局大量重叠，表明设计系统规范不足
• 深层嵌套使迁移、预览和模板维护变得脆弱

信息

• 对于可复用结构，可考虑使用专用实体、同步模式或基于区块的组合方式

关系字段与返回格式（ACF-05）

严重

• 代码使用关系／文章对象字段时，没有规定稳定的预期返回格式
• 假定双向关系会自动维护，但从未持续一致地维护

警告

• 模板在循环中反复调用 get_field()，而这些值本可一次性规范化
• 关系字段查询没有限制，使编辑人员的选择变得杂乱且容易出错
• 在不同代码路径中随意混用 ID、对象和数组

信息

• 当模板变得重复时，可通过视图模型辅助函数或类似 DTO 的映射器来规范化字段访问

选项页面与全局设置（ACF-06）

严重

• 频繁变化的请求级内容被存储为全局内容，却预期其能因页面／用户／上下文而异
• 关键运行时配置通过 ACF 选项编辑，却没有验证或部署规范

警告

• 全站内容在多个页面重复，而不是集中存储在选项／全局实体中
• 选项页面将营销文案、集成密钥和编辑设置混在同一屏幕中
• 代码假设选项始终存在，从不处理空默认值

信息

• 按职责拆分选项页面，并添加默认值／说明以提高可靠性

ACF JSON 与环境同步（ACF-07）

严重

• 字段组变更只存在于数据库中，没有提交 JSON 或导出途径
• 团队工作流经常覆盖字段定义，因为同步方向不明确

警告

• acf-json 的提交不一致或不完整
• 在生产环境中编辑字段组，却没有推广流程
• 不同环境的本地 JSON 路径配置不一致，且没有文档说明

信息

• 将 acf-json 纳入版本控制，并将仅存在于数据库中的编辑视为临时内容，直至导出

元数据查询与存储性能（ACF-08）

严重

• 主要归档/搜索行为在规模扩大后依赖多个未建立索引的 meta_query 子句
• 通过 LIKE 查询提取重复器/灵活内容中的值，用于业务关键视图
• 数字/日期筛选使用字符串比较语义或不一致的存储格式

警告

• 内容建模会导致每次请求都对 postmeta 执行大量联接
• 每次页面加载时都会从嵌套的 ACF 数据重新计算派生/聚合值
• 查询行为认为 ACF 字段成本低廉，只因管理界面使用方便

信息

• 必要时，将高频查询键提升为分类法、专用查找表或预计算索引

审查启发式

良好的 ACF 特征

• 字段组对应清晰的编辑任务或组件
• CPT 和分类法反映真实的业务实体
• 名称稳定、描述清晰，并带有领域前缀
• 已提交 ACF JSON，并有意进行环境同步
• 关系字段和返回格式已在代码中规范化
• 元数据用法符合网站的规模和查询模式

常见反模式

• “所有内容永远都是带灵活内容的页面”
• “所有内容都是文章元数据，即使它们本应是分类法或专用实体”
• “编辑者可以构建任何内容”，却没有约束或安全默认值
• “我们直接查询重复器内部数据”
• “我们更改了字段名称，并希望模板仍能正常工作”

输出格式

使用以下结构：

# ACF / Content Modeling Review

## Summary
- Scope: plugin/theme/app reviewed
- Modeling maturity: strong / mixed / fragile
- Primary risks: 2-5 bullets

## Critical Findings
- [ACF-XX] Title — file:line or subsystem
  Why it matters
  Recommended fix

## Warning Findings
- [ACF-XX] Title — file:line or subsystem
  Why it matters
  Recommended fix

## Info / Improvement Opportunities
- [ACF-XX] Title — file:line or subsystem
  Suggested improvement

## Modeling Notes
- Entity design observations
- Taxonomy vs meta observations
- Query/storage implications

## Cross-Skill Follow-Up
- Run `/wp-perf-review` if query behavior is the main risk
- Run `/wp-rest-review` if schema exposure or API contracts need review
- Run `/wp-block-review` if field groups power custom blocks heavily

参考文件

仅在需要时加载这些文件：

• references/content-modeling-guide.md
• references/acf-json-and-field-group-guide.md
• references/meta-query-and-performance.md

最后提醒

不要仅仅因为 ACF 在管理界面中可用，就认可对它的使用。应优先选择在网站内容、编辑者和集成数量翻倍后仍易于理解的模型。