woo-guard

Woo Guard

在代码发布前，审查生成或修改过的 WooCommerce 代码。在首次实现后，将以下规则作为一道守护检查来应用。WooCommerce 是一个不断演进的平台——订单存储更换了引擎，结账更换了框架——凭记忆编写的代码，针对的是三年前的 WooCommerce。涉及资金，"在我的演示商店上能运行"并不算达标。

这些规则的存在，是因为 AI Agent 生成的 WooCommerce 代码存在系统性问题：通过 get_post_meta() 读取订单元数据（在 HPOS 商店中会出错）、通过直接写入元数据来更新产品，绕过查找表和钩子、只在 JavaScript 中验证结账数据、使用浮点数计算价格，以及未确认 WooCommerce 已激活就注册 woocommerce_* 钩子。

如何使用此技能

守护检查模式（推荐）：生成或编辑 WooCommerce 代码后，针对差异或目标文件应用这些规则，然后在交付前运行自检。

实时模式（明确指定）：用户在编写 WooCommerce 代码前调用此技能时，在编写过程中应用相同规则，然后在交付前运行自检。

审查模式（用户要求审查或审计 WooCommerce 代码时）：按照 references/review-checklist.md 检查，并生成结构化的问题报告。除非用户要求，否则不要在审查模式下编辑代码。

安全底线——所有 WooCommerce 代码都必须遵守以下规则，并按最高严重级别处理，因为涉及资金：

• 根据上下文，使用正确的 esc_* 函数转义所有输出。
• 对所有请求数据先调用 wp_unslash()，再进行清理，然后才能用于逻辑处理。
• 每次状态变更都必须进行权限检查并验证 nonce。
• 对每个包含变量的查询都使用 $wpdb->prepare()。

如果已安装 wp-guard，请同时运行它，以覆盖完整的 WordPress 层。

首先适配项目

1. 阅读项目的 Agent 指引，以及扩展声明的 WooCommerce 版本范围。发生冲突时，以项目规范为准。
2. 确定此代码必须支持的订单存储模式：HPOS、旧式文章，或两者（默认假设为两者）。
3. 确定使用哪种结账方式：Blocks/Store API、旧式短代码结账，或两者。某种方式的钩子不会在另一种方式中触发。
4. 检查是否对 WooCommerce 活动状态进行了保护：在调用任何 wc_* 函数或注册 woocommerce_* 钩子之前，是否进行了功能检查或使用了 class_exists( 'WooCommerce' )。

规则

订单和产品数据 — 必须修复

1. 订单不是文章。 只能通过 CRUD API 访问订单：wc_get_order()、wc_get_orders()、$order->get_meta()、$order->update_meta_data() + $order->save()。禁止用于订单数据的操作：get_post_meta()、update_post_meta()、使用 post_type => shop_order 的 WP_Query/get_posts()，以及直接通过 $wpdb 联接 postmeta。这些操作在旧式商店中可用，但会在 HPOS 商店中无声失效。详情请参阅：references/hpos-and-crud.md。

2. 使用 CRUD 对象和 getter/setter，然后保存。 产品、客户和优惠券都应通过其 CRUD 对象操作（wc_get_product()、setter、->save()）。直接写入元数据会跳过查找表同步、其他扩展依赖的钩子，以及缓存失效。库存变更应遵循 wc_update_product_stock() 的语义；订单状态变更应通过 $order->update_status() 进行——这些操作会触发商店所需的邮件和钩子。

3. 声明功能兼容性。 任何涉及订单的扩展都必须声明与 HPOS 兼容（FeaturesUtil::declare_compatibility( 'custom_order_tables', … )）；任何涉及结账的扩展都必须声明与 cart_checkout_blocks 兼容（或如实声明不兼容）。缺少声明会导致每位商店所有者都看到一条显示你插件名称的警告横幅。

结账与金额 — 必须修复

4. 结账验证必须在服务器端进行。 对旧版结账，在 woocommerce_checkout_process 中进行验证；对 Blocks 结账，则使用 Store API 扩展架构。JavaScript 验证只改善用户体验，不能保障安全。了解商店使用哪种结账方式；如果扩展声称具备通用兼容性，就要同时接入两种方式。

5. 金额不是浮点数。 存储安全的价格和总额要使用 wc_format_decimal()，显示金额要使用 wc_price()，运算则要遵循 WooCommerce 自身的税费和舍入设置。不要手动处理货币符号，不要对价格使用 number_format()，不要用浮点数比较总额是否相等。

运行时规范 — 应当修复

6. 检查运行时上下文。 在 REST、cron、CLI 和管理后台上下文中，WC()->cart 和 WC()->session 可能为 null，使用前要先检查。Webhook 或支付网关回调中，绝不要假定客户已登录。确认支持的版本范围内存在所用的每个 woocommerce_* 钩子和 wc_* 函数——WooCommerce 会在大版本之间重命名或弃用钩子。

7. 优先使用钩子，而非模板覆盖。 按优先顺序使用：现有的 WooCommerce 钩子/筛选器 → woocommerce_locate_template 筛选器 → 主题级覆盖。插件内附带的模板覆盖会将某个 WooCommerce 版本的文件副本固定下来，并在模板更新时导致问题——代码审查时务必指出。

8. 后台任务要能适应订单量增长。 批处理任务、同步和 Webhook 扇出都应通过 Action Scheduler（随 WooCommerce 捆绑提供）执行，而不是使用原始 WP-Cron 循环。处理程序必须具备幂等性——在实际商店中，订单事件可能触发多次。

交付前自检

1. 在差异中搜索 get_post_meta、update_post_meta、post_type => 'shop_order'：其中是否有任何一项用于处理订单？（规则 1）
2. 是否有任何商品/订单/客户写入操作绕过了 CRUD 对象的 save()？（规则 2）
3. 扩展是否声明兼容 HPOS（以及相关情况下的 checkout-blocks）？（规则 3）
4. 每条结账规则是否都在服务器端执行，并适用于商店实际使用的结账方式？（规则 4）
5. 是否存在浮点运算、硬编码货币符号或对金额使用 number_format() 的情况？（规则 5）
6. 是否有可能在 REST/cron/CLI 中运行的 WC()->cart/WC()->session 访问？是否有未经验证的钩子名称？（规则 6）
7. 插件中是否附带任何模板文件？（规则 7）
8. 安全底线：所有输出是否都已转义，所有请求输入是否先移除转义再清理，所有状态变更是否都经过能力检查和 nonce 验证，所有可变查询是否都已预处理？

如果任何一项不符合要求，请先修复，再展示给用户。

报告格式（审查模式）

**Rule N violation** in `path/file.php:<line or function>`
- What: <one sentence>
- Risk: <HPOS breakage / skipped hooks / money error / checkout bypass — one phrase>
- Fix: <one sentence>

按文件分组，优先列出规则 1–5 的问题。如果某个文件没有问题，就不要提及。

严重性指南

• 必须修复： 规则 1–5 — 商店故障、业务逻辑被跳过、金额错误
• 应当修复： 规则 6–8 — 上下文导致崩溃、更新脆弱、任务无法随规模增长而正常运行

参考资料

• references/hpos-and-crud.md — HPOS 背景、CRUD 模式、兼容性声明、违规对照表
• references/checkout-and-money.md — 旧版与 Blocks 结账、Store API 验证、价格与货币处理
• references/review-checklist.md — 审查模式的结构化检查流程
• references/sources.md — WooCommerce 开发者文档 URL；仅在需要引用时阅读

此技能不涉及的内容

• 不覆盖安全底线以外的完整 WordPress 层——如果已安装 wp-guard，i18n 和资源/查询规范由其负责。
• 不审查商店配置、主题样式或支付服务商账户设置。
• 不决定定价或业务逻辑——它负责规范 WooCommerce 代码的交付方式，而不是商店销售的商品。