woo-guard

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Woo Guard

You are reviewing generated or changed WooCommerce code before it ships. Apply the rules below as a guard pass after the first implementation pass. WooCommerce is a moving platform — order storage changed engines, checkout changed frameworks — and code written from memory targets the WooCommerce of three years ago. With money on the line, "works on my demo store" is not a standard.

These rules exist because AI agents produce WooCommerce code with systematic failures: order meta read through

get_post_meta()

(broken on HPOS stores), products updated by direct meta writes that skip lookup tables and hooks, checkout validated only in JavaScript, prices computed in floats, and

woocommerce_*

hooks registered before confirming WooCommerce is active.

你需要在代码上线前审查生成或修改的WooCommerce代码。在首次实现完成后，将以下规则作为校验环节执行。WooCommerce是一个不断迭代的平台——订单存储引擎、结账框架都已更新——仅凭记忆编写的代码往往适配的是三年前的WooCommerce版本。由于涉及资金交易，“在我的演示店铺中可用”不能作为合格标准。

这些规则的存在是因为AI Agent生成的WooCommerce代码存在系统性缺陷：通过

get_post_meta()

读取订单元数据（在HPOS店铺中会失效）、直接写入元数据来更新商品（会跳过查找表和钩子）、仅通过JavaScript验证结账流程、用浮点数计算价格，以及在确认WooCommerce激活前就注册

woocommerce_*

钩子。

How to use this skill

如何使用该技能

Guard-pass mode (recommended): after WooCommerce code has been generated or edited, apply the rules to the diff or target files, then run the self-check before delivery.

Live mode (explicit): when the user invokes this skill before writing WooCommerce code, apply the same rules while writing, then run the self-check before delivery.

Review mode (the user asks you to review or audit WooCommerce code): walk references/review-checklist.md and produce a structured findings report. Do not edit code in review mode unless asked.

Security floor — these hold in all WooCommerce code, at maximum severity, because money is on the line:

Escape all output with the context-correct
```
esc_*
```
function.
```
wp_unslash()
```
then sanitize all request data before it touches logic.
Capability check plus nonce on every state change.
```
$wpdb->prepare()
```
for every query containing a variable.

If wp-guard is installed, run it alongside for the full WordPress layer.

校验模式（推荐）：在生成或编辑WooCommerce代码后，针对差异文件或目标文件应用以下规则，然后在交付前执行自检。

实时模式（显式调用）：当用户在编写WooCommerce代码前调用该技能时，在编写过程中应用相同规则，然后在交付前执行自检。

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

安全底线——以下规则适用于所有WooCommerce代码，属于最高优先级，因为涉及资金交易：

使用上下文匹配的
```
esc_*
```
函数转义所有输出内容。
在处理逻辑前，先通过
```
wp_unslash()
```
处理所有请求数据，再进行清理。
每次状态变更都要进行权限检查并验证nonce。
所有包含变量的查询都要使用
```
$wpdb->prepare()
```
。

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

Adapt to the project first

先适配项目需求

Read the project's agent instructions and the extension's declared WooCommerce version range. Project conventions win on conflict.
Determine the order storage mode this code must support: HPOS, legacy posts, or both (the default assumption is both).
Determine the checkout in play: Blocks/Store API, legacy shortcode checkout, or both. Hooks for one do not fire in the other.
Check whether WooCommerce activity is guarded: feature checks or
```
class_exists( 'WooCommerce' )
```
before any
```
wc_*
```
call or
```
woocommerce_*
```
hook.

阅读项目的Agent指令以及扩展声明的WooCommerce版本范围。若规则与项目约定冲突，以项目约定为准。
确定代码必须支持的订单存储模式：HPOS、传统帖子模式，或两者兼容（默认假设为两者兼容）。
确定当前使用的结账系统：Blocks/Store API、传统短代码结账，或两者兼容。针对一种系统的钩子不会在另一种系统中触发。
检查WooCommerce相关操作是否有防护：在调用任何
```
wc_*
```
函数或注册
```
woocommerce_*
```
钩子前，是否进行了功能检查或
```
class_exists( 'WooCommerce' )
```
判断。

The Rules

核心规则

Order and product data — must fix

订单与商品数据——必须修复

Orders are not posts. Access orders only through the CRUD API:
```
wc_get_order()
```
,
```
wc_get_orders()
```
,
```
$order->get_meta()
```
,
```
$order->update_meta_data()
```
+
```
$order->save()
```
. Forbidden on order data:
```
get_post_meta()
```
,
```
update_post_meta()
```
,
```
WP_Query
```
/
```
get_posts()
```
with
```
post_type => shop_order
```
, and direct
```
$wpdb
```
joins on postmeta. These work on legacy stores and silently break on HPOS stores. Details: references/hpos-and-crud.md.
CRUD objects, getters/setters, then save. Products, customers, and coupons go through their CRUD objects (
```
wc_get_product()
```
, setters,
```
->save()
```
). Direct meta writes skip lookup-table sync, skip the hooks other extensions rely on, and skip cache invalidation. Stock changes go through
```
wc_update_product_stock()
```
semantics; order state changes through
```
$order->update_status()
```
— which fire the emails and hooks the store expects.
Declare feature compatibility. Any extension touching orders declares HPOS compatibility (
```
FeaturesUtil::declare_compatibility( 'custom_order_tables', … )
```
); any extension touching checkout declares
```
cart_checkout_blocks
```
compatibility (or incompatibility, honestly). A missing declaration shows every store owner a warning banner with your plugin's name on it.

订单不是帖子。仅通过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
```
，以及直接通过
```
$wpdb
```
关联postmeta表。这些方式在传统店铺中可用，但在HPOS店铺中会静默失效。详情：references/hpos-and-crud.md。
优先使用CRUD对象、getter/setter方法，然后保存。商品、客户和优惠券操作需通过对应的CRUD对象（
```
wc_get_product()
```
、setter方法、
```
->save()
```
）完成。直接写入元数据会跳过查找表同步、其他扩展依赖的钩子，以及缓存失效处理。库存变更需遵循
```
wc_update_product_stock()
```
的逻辑；订单状态变更需通过
```
$order->update_status()
```
——该方法会触发店铺预期的邮件通知和钩子。
声明功能兼容性。任何涉及订单的扩展都需声明HPOS兼容性（
```
FeaturesUtil::declare_compatibility( 'custom_order_tables', … )
```
）；任何涉及结账的扩展都需声明
```
cart_checkout_blocks
```
兼容性（如实声明不兼容也可）。缺失兼容性声明会向所有店铺所有者显示带有插件名称的警告横幅。

Checkout and money — must fix

结账与金额处理——必须修复

Checkout validation is server-side. Validate at
```
woocommerce_checkout_process
```
(legacy) or through Store API extension schemas (Blocks). JavaScript validation is UX, never security. Know which checkout the store runs and wire both when the extension claims general compatibility.
Money is not a float. Prices and totals go through
```
wc_format_decimal()
```
for storage-safe values,
```
wc_price()
```
for display, and WooCommerce's own tax/rounding settings for arithmetic. No hand-rolled currency symbols, no
```
number_format()
```
on prices, no float equality on totals.

结账验证需在服务端完成。在
```
woocommerce_checkout_process
```
（传统模式）或通过Store API扩展 schema（Blocks模式）进行验证。JavaScript验证仅用于提升用户体验，绝不作为安全校验手段。需明确店铺使用的结账系统，若扩展声明为通用兼容，则需同时适配两种系统。
金额不能用浮点数处理。价格和总计需通过
```
wc_format_decimal()
```
转换为适合存储的值，通过
```
wc_price()
```
进行展示，并使用WooCommerce内置的税费/四舍五入设置进行计算。禁止手动设置货币符号、对价格使用
```
number_format()
```
、对总计进行浮点数相等判断。

Runtime discipline — should fix

运行时规范——建议修复

Guard the runtime context.
```
WC()->cart
```
and
```
WC()->session
```
are null in REST, cron, CLI, and admin contexts — check before touching them. Never assume a logged-in customer in webhook or gateway callbacks. Verify every
```
woocommerce_*
```
hook and
```
wc_*
```
function exists in the supported version range — WooCommerce renames and retires hooks across majors.
Hooks over template overrides. Prefer, in order: existing WooCommerce hooks/filters → the
```
woocommerce_locate_template
```
filter → a theme-level override. A template override shipped inside a plugin freezes a copied file at one WooCommerce version and breaks on template updates — flag it in review, always.
Background work scales with order volume. Batch jobs, syncs, and webhook fan-out go through Action Scheduler (bundled with WooCommerce), not raw WP-Cron loops. Handlers are idempotent — order events fire more than once in real stores.

防护运行时上下文。
```
WC()->cart
```
和
```
WC()->session
```
在REST、cron、CLI和后台上下文中为null——使用前需进行检查。绝不要假设Webhook或网关回调中存在已登录客户。需验证所有
```
woocommerce_*
```
钩子和
```
wc_*
```
函数在支持的版本范围内是否存在——WooCommerce会在大版本更新中重命名或弃用钩子。
优先使用钩子而非模板覆盖。优先级顺序为：现有WooCommerce钩子/过滤器 →
```
woocommerce_locate_template
```
过滤器 → 主题层面的模板覆盖。插件中附带的模板覆盖会将复制的文件固定在某个WooCommerce版本，在模板更新时会失效——审查时需始终标记此类问题。
后台任务需适配订单量规模。批量任务、同步操作和Webhook分发需通过Action Scheduler（WooCommerce内置组件）完成，而非原生WP-Cron循环。处理程序需具备幂等性——实际店铺中订单事件可能会多次触发。

Self-check before delivery

交付前自检

Grep your diff for
```
get_post_meta
```
,
```
update_post_meta
```
,
```
post_type => 'shop_order'
```
: any of them touching orders? (Rule 1)
Any product/order/customer write that bypasses a CRUD object's
```
save()
```
? (Rule 2)
Does the extension declare HPOS (and checkout-blocks, if relevant) compatibility? (Rule 3)
Is every checkout rule enforced server-side, for the checkout(s) the store actually runs? (Rule 4)
Any float arithmetic, hardcoded currency symbol, or
```
number_format()
```
on money? (Rule 5)
Any
```
WC()->cart
```
/
```
WC()->session
```
access that can run in REST/cron/CLI? Any unverified hook name? (Rule 6)
Any template file shipped in the plugin? (Rule 7)
Security floor: every output escaped, every request input unslashed then sanitized, every state change capability-checked and nonce-verified, every variable query prepared?

If any answer is wrong, fix it before showing the user.

在代码差异中搜索
```
get_post_meta
```
、
```
update_post_meta
```
、
```
post_type => 'shop_order'
```
：是否有任何操作涉及订单？（规则1）
是否存在绕过CRUD对象
```
save()
```
方法的商品/订单/客户写入操作？（规则2）
扩展是否声明了HPOS（以及结账区块，若相关）兼容性？（规则3）
每个结账规则是否针对店铺实际使用的结账系统在服务端强制执行？（规则4）
是否存在浮点数运算、硬编码货币符号或对金额使用
```
number_format()
```
的情况？（规则5）
是否存在可能在REST/cron/CLI环境中执行的
```
WC()->cart
```
/
```
WC()->session
```
访问操作？是否存在未验证的钩子名称？（规则6）
插件中是否附带了模板文件？（规则7）
安全底线：所有输出是否已转义？所有请求输入是否先经过
```
wp_unslash()
```
处理再清理？所有状态变更是否已进行权限检查和nonce验证？所有包含变量的查询是否已通过
```
$wpdb->prepare()
```
处理？

若任何问题的答案为“是”，需在交付给用户前修复。

Reporting format (review mode)

审查模式报告格式

**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>

Group by file, lead with Rules 1–5 findings. If a file is clean, don't mention it.

**规则N违规** 位于 `path/file.php:<行号或函数名>`
- 问题描述：<一句话说明>
- 风险：<HPOS失效/跳过钩子/金额错误/结账绕过——一句话概括>
- 修复方案：<一句话说明>

按文件分组，优先展示规则1-5的问题。若文件无问题，无需提及。

Severity guide

严重程度指南

Must fix: Rules 1–5 — broken stores, skipped business logic, wrong money
Should fix: Rules 6–8 — context crashes, update fragility, jobs that die at scale

必须修复：规则1-5——会导致店铺失效、业务逻辑跳过、金额计算错误
建议修复：规则6-8——会导致上下文崩溃、更新脆弱、大规模任务失败

References

参考资料

references/hpos-and-crud.md — HPOS background, CRUD patterns, compatibility declaration, violation table
references/checkout-and-money.md — legacy vs Blocks checkout, Store API validation, price and currency handling
references/review-checklist.md — structured walk-through for review mode
references/sources.md — WooCommerce developer documentation URLs; read only when citing

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

What this skill does not do

该技能不包含的内容

Cover the full WordPress layer beyond the security floor — i18n and asset/query discipline are wp-guard's jurisdiction when it is installed.
Review store configuration, theme styling, or payment provider account setup.
Decide pricing or business logic — it guards how WooCommerce code ships, not what the store sells.

除安全底线外，不覆盖完整的WordPress层面检查——国际化、资源/查询规范等内容在安装wp-guard后由其负责。
不审查店铺配置、主题样式或支付服务商账户设置。
不决定定价或业务逻辑——仅保障WooCommerce代码的交付规范，不涉及店铺售卖内容。