当生成或修改 WooCommerce 扩展、支付物流、结账…

在 WooCommerce 代码生成、编辑或审查后，按规则守卫式检查 diff/目标文件并自检，覆盖订单/商品、结账/金额、运行时与后台任务。

适用场景

解决思路

1. 选择模式：guard-pass 模式下，在代码已生成或修改后，对 diff 或目标文件套用规则，交付前运行自检；live 模式下，在写 WooCommerce 代码时套用同一套规则，交付前运行自检；review 模式下，走 references/review-checklist.md 并输出结构化发现报告，除非被要求否则不改代码。
2. 所有 WooCommerce 代码执行安全底线：所有输出用上下文正确的 esc_* 函数转义；所有请求数据先 wp_unslash() 再 sanitize；每次状态变更做 capability check 加 nonce 验证；每个含变量的查询用 $wpdb->prepare()。
3. 如果安装了 wp-guard，则同时运行它，以覆盖完整 WordPress 层。
4. 先读项目 agent 指令和扩展声明的 WooCommerce 版本范围，冲突时项目约定优先。
5. 确定该代码必须支持的订单存储模式：HPOS、legacy posts 或两者；默认假设两者都要支持。
6. 确定涉及的结账方式：Blocks/Store API、legacy shortcode checkout 或两者；一种结账的钩子不会在另一种触发。
7. 检查 WooCommerce 活动是否被保护：在任何 wc_* 调用或 woocommerce_* 钩子注册前做 feature check 或 class_exists( 'WooCommerce' )。
8. 规则1：订单不是文章。只通过 CRUD API 访问订单：wc_get_order()、wc_get_orders()、$order->get_meta()、$order->update_meta_data() + $order->save()。订单数据禁用 get_post_meta()、update_post_meta()、WP_Query/get_posts() 且 post_type => 'shop_order'，以及对 postmeta 的直接 $wpdb join。
9. 规则2：使用 CRUD 对象、getter/setter，然后 save。Products、customers、coupons 走各自 CRUD 对象，如 wc_get_product()、setter、->save()。直接 meta 写入会跳过 lookup-table 同步、其他扩展依赖的钩子和缓存失效。库存变更走 wc_update_product_stock() 语义；订单状态变更走 $order->update_status()，以触发店铺期望的邮件和钩子。
10. 规则3：声明功能兼容性。任何接触订单的扩展声明 HPOS 兼容：FeaturesUtil::declare_compatibility( 'custom_order_tables', … )；任何接触结账的扩展声明 cart_checkout_blocks 兼容或不兼容，诚实声明。缺少声明会让每个店主看到带插件名的警告横幅。
11. 规则4：结账校验在服务端。legacy 在 woocommerce_checkout_process 校验；Blocks 通过 Store API extension schemas 校验。JavaScript 校验只是 UX，永远不是安全边界。确认店铺实际运行的结账方式；若扩展声称一般兼容，则两者都要接线。
12. 规则5：金额不是浮点数。价格和总额用 wc_format_decimal() 得到存储安全值，用 wc_price() 显示，用 WooCommerce 自己的 tax/rounding 设置做运算。禁止手写货币符号、对价格用 number_format()、对总额做浮点相等比较。
13. 规则6：保护运行时上下文。WC()->cart 和 WC()->session 在 REST、cron、CLI、admin 上下文中为 null，接触前先检查。在 webhook 或 gateway 回调中绝不假设已登录客户。确认每个 woocommerce_* 钩子和 wc_* 函数在支持的版本范围内存在；WooCommerce 跨大版本会重命名和移除钩子。
14. 规则7：优先钩子而不是模板覆盖。优先级：已有 WooCommerce hooks/filters → woocommerce_locate_template filter → 主题级覆盖。插件内附带模板覆盖会把复制文件冻结在某个 WooCommerce 版本，模板更新时破坏；审查中始终标出。
15. 规则8：后台工作随订单量扩展。批处理任务、同步、webhook fan-out 走 Action Scheduler（WooCommerce 自带），不要用原始 WP-Cron 循环。处理器必须幂等，因为真实店铺中订单事件会触发多次。
16. 需要细节时查阅 references/hpos-and-crud.md 了解 HPOS、CRUD、兼容声明和违规表；references/checkout-and-money.md 了解 legacy vs Blocks、Store API 校验、价格和货币处理；references/review-checklist.md 用于 review 模式结构化走查；references/sources.md 仅在引用时读取 WooCommerce 开发者文档 URL。
17. 交付前自检1：grep diff 中的 get_post_meta、update_post_meta、post_type => 'shop_order'；是否有任何一处接触订单？
18. 交付前自检2：是否有任何 product/order/customer 写入绕过 CRUD 对象的 save()？
19. 交付前自检3：扩展是否声明 HPOS 兼容；如相关是否声明 checkout-blocks 兼容？
20. 交付前自检4：每条结账规则是否在实际运行的结账方式上由服务端强制执行？
21. 交付前自检5：是否有浮点运算、硬编码货币符号或对金额用 number_format()？
22. 交付前自检6：是否有 WC()->cart/WC()->session 访问可能运行在 REST/cron/CLI？是否有未验证的钩子名？
23. 交付前自检7：插件中是否附带了模板文件？
24. 交付前自检8：安全底线：每个输出是否转义，每个请求输入是否先 unslash 再 sanitize，每次状态变更是否 capability check 加 nonce，每个变量查询是否 prepare？
25. 若自检任何一项答案不对，在展示给用户前修复。
26. review 模式报告格式：按文件分组，格式为 **Rule N violation** in `path/file.php:<line or function>`；包含 What（一句话）、Risk（HPOS breakage / skipped hooks / money error / checkout bypass 等一个短语）、Fix（一句话）。Rules 1–5 发现优先；文件干净则不提及。
27. 按严重度处理：Must fix 为 Rules 1–5（破坏店铺、跳过业务逻辑、金额错误）；Should fix 为 Rules 6–8（上下文崩溃、更新脆弱、规模化时任务失败）。

适用边界 · 注意事项

• 不用于不涉及 WooCommerce API 的 WordPress 代码；那类代码应使用 wp-guard。
• 不用于通用代码审查、测试审查、商店配置或后台界面问题；这些应分别使用 clean-code-guard、test-guard 或直接处理。
• 不覆盖完整 WordPress 层、主题样式、支付提供商账户设置，也不决定定价或业务逻辑。