wp-woocommerce-dev

Name: wp-woocommerce-dev
Author: jorgerosal

github.com/jorgerosal测试与质量11176 次安装20 周前更新

代码仓库

关于 wp-woocommerce-dev

面向 WooCommerce 扩展和商店集成开发者的代码审查技能，重点检查 HPOS 兼容的数据访问、支付代码安全、钩子、模板和性能模式。

主要功能

01检查 HPOS 兼容性
02审查 WooCommerce CRUD 用法
03核查支付网关安全措施
04检查钩子与模板覆盖
05识别查询和后台任务风险

适用场景

01审计扩展对 HPOS 的支持
02审查支付网关实现
03检查模板覆盖及钩子保留情况
04查找低效的购物车或商品查询模式

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jorgerosal/wordpress-skills --skill wp-woocommerce-dev

安装后在 Claude Code 中输入/wp-woocommerce-dev确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/

wc-extension-guide.md

wc-performance-guide.md

wc-template-guide.md

详细介绍

WooCommerce 开发审查技能

概述

系统化审查 WooCommerce 8.2+ 至当前 10.x 版本的开发。**核心原则：**WooCommerce 经历了根本性的架构转变——自 WC 8.2（2023 年 10 月）起，新商店默认启用 HPOS（高性能订单存储），要求所有扩展仅使用 CRUD API。在现代 WooCommerce 安装中，直接访问订单文章的方式已无法正常工作。

扩展必须使用 WC_Data CRUD 模式（wc_get_order()、wc_get_orders()、WC_Order 方法）、使用 Action Scheduler 进行后台处理，并优先使用钩子而非模板覆盖，以便于维护。支付网关绝不能存储或记录原始银行卡数据。购物车片段必须按需加载。模板覆盖必须保留所有操作钩子。

审查会验证 HPOS 兼容性、支付网关安全性（仅代码层面，不包括 PCI 合规审计）、WooCommerce 钩子使用、模板覆盖质量和性能模式。自动检测 WooCommerce 上下文（扩展、主题集成、支付网关、配送方式、自定义商品类型、WC Blocks 集成），并据此调整审查指南。审查结果按文件分组，列出行号、严重性标签（CRITICAL/WARNING/INFO）以及 BAD/GOOD 代码示例对照。

**注意：**此技能涉及所有先前技能——安全（支付数据处理）、插件架构（将 WC 作为扩展）、区块（WC Blocks）、主题（模板覆盖）和性能（购物车片段、查询）。全文提供交叉引用。

适用场景

适用于：

WooCommerce 扩展架构审查
HPOS 兼容性审计（检查 declare_compatibility，仅使用 CRUD 的验证）
支付网关代码审查（WC_Payment_Gateway 模式、安全反模式）
配送方式审查（WC_Shipping_Method、calculate_shipping）
自定义商品类型审查（WC_Product 扩展、数据存储）
WooCommerce 钩子使用分析（订单生命周期、商品数据、购物车／结账）
模板覆盖评估（钩子保留、版本跟踪）
购物车片段性能分析（检测是否全站加载）
Action Scheduler 模式审查（与 wp_cron 反模式比较）
WooCommerce REST API 扩展审查
WC Blocks 集成检查（Store API、Additional Checkout Fields API）
Webhook 安全审查（签名验证）

不适用于：

通用插件架构（使用 wp-plugin-development）
仅限安全的审计（使用 wp-security-review 进行全面分析）
WC 以外的区块开发（使用 wp-block-development）
不涉及 WC 集成的纯主题审查（使用 wp-theme-development）
仅限性能的审查（使用 wp-performance-review）
PCI 合规审计（不在范围内——属于基础设施层面）
商店设置或托管配置（不在范围内）

代码审查工作流

按照以下八个步骤开展系统化的 WooCommerce 审查：

1. 根据文件结构检测 WooCommerce 上下文

扩展／插件：

主插件文件中包含 WC 依赖检查（插件头信息中包含 WooCommerce）
通过 before_woocommerce_init 钩子声明 HPOS 兼容性
最常见的上下文——全面审查 HPOS、CRUD 和钩子

主题集成：

主题中包含 woocommerce/ 目录及模板覆盖
侧重模板覆盖，并优先提供使用钩子的指导
主题模式可交叉参考 wp-theme-development

支付网关：

扩展 WC_Payment_Gateway 的类
加强安全审查（绝不存储原始银行卡数据，检查 HTTPS）
适用时验证 Webhook

配送方式：

扩展 WC_Shipping_Method 的类
审查 calculate_shipping()、配送区域支持和费率计算

自定义商品类型：

扩展 WC_Product 的类
审查数据存储、商品类型注册和类层次结构

WC Blocks 集成：

Store API 使用情况、结账区块扩展点
Additional Checkout Fields API（WC 8.6+）
进行概览级审查；深入审查区块模式时建议使用 wp-block-development

2. 检查 HPOS 兼容性（WOO-16）

缺失时为严重问题：

在 before_woocommerce_init 钩子中调用 declare_compatibility()
查找模式：使用 FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true ) 的 add_action( 'before_woocommerce_init', ... )

严重违规：

使用 post_type='shop_order' 的 get_posts() 或 WP_Query
对订单数据使用 get_post_meta() / update_post_meta()
直接使用 $wpdb 查询 wp_posts / wp_postmeta 中的订单数据

警告级违规：

使用 post_type='product' 的 WP_Query（未来可能造成兼容性问题——计划推出自定义商品表）

良好模式：

wc_get_order( $order_id )
wc_get_orders( array( 'status' => 'completed', 'limit' => 10 ) )
$order->get_meta( 'key' )、$order->update_meta_data( 'key', $value )、$order->save()

兼容模式注意事项：

代码应同时兼容 HPOS 和旧版模式
只能使用 CRUD API——它们会处理这两种存储模式

3. 检查数据访问模式（WOO-02、WOO-17）

商品访问：

良好：wc_get_product( $id )、WC_Product_Query
警告：使用 post_type='product' 的 WP_Query（改用 wc_get_products()）
严重：直接使用 $wpdb 查询商品表

订单访问：

良好：wc_get_order( $id )、wc_get_orders()
严重：使用 post_type='shop_order' 的 get_posts()
严重：直接使用 $wpdb 查询订单数据

WC_Data 模式：

所有 WooCommerce CRUD 对象的基类
数据存储负责处理持久化（基于文章的存储与 HPOS 表）
修改后始终调用 ->save()

4. 检测到支付网关时（WOO-03、WOO-19、WOO-20）

严重违规：

在数据库或会话中存储未加密的卡号/CVV
在 error_log() 或 debug.log 中记录银行卡数据
通过 HTTP（非 SSL）传输银行卡数据

警告级违规：

在代码中硬编码 API 凭据（应使用设置项）
处理支付前未检查 is_ssl()
未验证 Webhook 签名

process_payment() 验证：

必须返回包含 'result' 和 'redirect' 键的数组
使用 $order->payment_complete( $transaction_id )，不要手动更改状态
切勿访问未经处理的 $_POST 银行卡数据——应使用令牌化

交叉参考：

通用安全模式请参阅 wp-security-review
此技能仅关注 WooCommerce 特有的支付反模式

5. 检查 WooCommerce 钩子的使用情况（WOO-05、WOO-06、WOO-07、WOO-08）

生命周期钩子：

woocommerce_before_cart、woocommerce_after_cart
woocommerce_checkout_process、woocommerce_checkout_create_order
woocommerce_thankyou
woocommerce_order_status_changed

商品数据钩子：

使用 woocommerce_product_options_* 添加管理字段
使用 woocommerce_process_product_meta 保存

结账字段钩子：

使用 woocommerce_checkout_fields 添加字段
使用 woocommerce_checkout_update_order_meta 保存

购物车钩子：

使用 woocommerce_add_cart_item_data 添加自定义购物车数据
使用 woocommerce_cart_calculate_fees 添加费用
使用 woocommerce_check_cart_items 进行验证

订单状态转换：

使用 woocommerce_order_status_{status} 处理特定状态变更
使用 $order->set_status() 并附上备注，不要直接更改文章状态

6. 检查模板覆盖（WOO-10、WOO-11、WOO-12、WOO-13）

严重违规：

模板覆盖中删除了 do_action() 钩子
这会破坏插件集成，导致其他扩展无法挂接钩子

警告级违规：

模板版本过旧（@version 注释不匹配）
可能遗漏 WC 更新，导致显示问题

信息类建议：

如果模板覆盖的位置存在钩子，建议改用钩子

优先使用钩子的原则：

关键要点：强烈建议优先使用钩子，而不是覆盖模板
只有在万不得已时才覆盖模板
始终保留原始模板中的所有 do_action() 调用

交叉参考：

通用模板模式请参阅 wp-theme-development

7. 检查性能模式（WOO-15、WOO-17、WOO-18）

购物车片段（wc-cart-fragments.js）：

严重：全站加载，且未进行条件性取消入队
警告：在非 WC 页面上加载，但没有合理说明
良好：仅在购物车、结账和产品页面上有条件地取消入队
更佳：迁移到 Mini-Cart Block（内置优化）

产品查询：

严重：直接对 wp_posts 执行 SQL 查询以获取产品
警告：使用 WP_Query 和 post_type='product'
信息：重复加载产品时缺少对象缓存

Action Scheduler：

警告：对批量 WC 操作使用 wp_cron()（不可靠，取决于流量）
良好：as_enqueue_async_action()、as_schedule_single_action()
WooCommerce 自带，无需单独安装

会话处理：

警告：自定义会话筛选器超过 30 天上限（WC 10.1+）
信息：自定义会话实现绕过了 WC_Session_Handler

交叉参考：

如需全面的性能分析，请参阅 wp-performance-review

8. 使用以下输出格式生成报告

酌情建议交叉参考相关技能：

安全问题 → /wp-sec-review
插件架构 → /wp-plugin-review
区块问题 → /wp-block-review
主题问题 → /wp-theme-review
性能问题 → /wp-perf-review

特定文件类型检查

HPOS 兼容性（WOO-16）

兼容性声明（缺失时为严重问题）：

// GOOD: Declare HPOS compatibility
add_action( 'before_woocommerce_init', function() {
    if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(
            'custom_order_tables',
            __FILE__,
            true
        );
    }
} );

// BAD: Missing declaration
// Extension silently breaks on HPOS-enabled stores

直接访问文章（严重问题）：

对产品订单使用带有 'post_type' => 'shop_order' 的 get_posts()
使用 new WP_Query( array( 'post_type' => 'shop_order' ) )
使用 get_post_meta( $order_id, ... ) 获取订单数据
使用 update_post_meta( $order_id, ... ) 更新订单数据
直接对订单的 wp_posts 使用 $wpdb->prepare()

CRUD 模式（良好）：

// GOOD: HPOS-compatible order access
$order = wc_get_order( $order_id );
$order->update_meta_data( 'custom_field', $value );
$order->save();

// GOOD: Query orders
$orders = wc_get_orders( array(
    'status' => 'completed',
    'limit' => 10,
    'date_created' => '>=' . strtotime( '-30 days' )
) );

// BAD: Direct post access (breaks HPOS)
$orders = get_posts( array(
    'post_type' => 'shop_order',
    'post_status' => 'wc-completed'
) );
update_post_meta( $order_id, 'custom_field', $value );

WooCommerce CRUD 模式（WOO-02、WOO-07）

WC_Data 基类：

所有 WooCommerce 对象都继承 WC_Data
数据存储负责持久化（HPOS 表与文章表）
更改会缓冲，直到调用 ->save()

订单 CRUD：

// GOOD: Complete order manipulation
$order = wc_get_order( $order_id );
$order->set_status( 'processing', 'Payment received' );
$order->update_meta_data( 'gift_message', $message );
$order->add_order_note( 'Custom note' );
$order->save(); // Single save after all changes

// BAD: Manual post status change
wp_update_post( array(
    'ID' => $order_id,
    'post_status' => 'wc-processing'
) );

产品 CRUD：

// GOOD: WC_Product_Query for product lists
$query = new WC_Product_Query( array(
    'status' => 'publish',
    'limit' => 10,
    'category' => array( 'clothing' ),
    'orderby' => 'date',
    'order' => 'DESC'
) );
$products = $query->get_products();

// WARNING: WP_Query for products (future-breaking)
$products = new WP_Query( array(
    'post_type' => 'product',
    'posts_per_page' => 10
) );

自定义数据存储注册：

// GOOD: Register custom data store
add_filter( 'woocommerce_data_stores', 'register_custom_data_store' );
function register_custom_data_store( $data_stores ) {
    $data_stores['custom-order-type'] = 'Custom_Order_Data_Store';
    return $data_stores;
}

支付网关开发（WOO-03、WOO-19）

WC_Payment_Gateway 类结构：

// GOOD: Complete payment gateway implementation
class WC_Gateway_Custom extends WC_Payment_Gateway {

    public function __construct() {
        $this->id = 'custom_gateway';
        $this->has_fields = true;
        $this->method_title = __( 'Custom Gateway', 'text-domain' );
        $this->method_description = __( 'Description', 'text-domain' );

        $this->init_form_fields();
        $this->init_settings();

        add_action( 'woocommerce_update_options_payment_gateways_' . $this->id,
            array( $this, 'process_admin_options' ) );
    }

    public function process_payment( $order_id ) {
        $order = wc_get_order( $order_id );

        // CRITICAL: Always check HTTPS in production
        if ( ! is_ssl() && 'yes' !== $this->get_option( 'testmode' ) ) {
            wc_add_notice( __( 'SSL required', 'text-domain' ), 'error' );
            return array( 'result' => 'failure' );
        }

        // GOOD: Use payment_complete() not manual status change
        $order->payment_complete( $transaction_id );

        return array(
            'result' => 'success',
            'redirect' => $this->get_return_url( $order )
        );
    }
}

严重的安全反模式：

// CRITICAL: Never store raw card data
// BAD:
update_post_meta( $order_id, 'card_number', $_POST['card_number'] );
$wpdb->insert( 'payment_tokens', array( 'card' => $_POST['card_number'] ) );

// CRITICAL: Never log card data
// BAD:
error_log( 'Card: ' . $_POST['card_number'] );
wc_get_logger()->debug( 'CVV: ' . $_POST['cvv'] );

// GOOD: Use tokenization
$token = new WC_Payment_Token_CC();
$token->set_token( $gateway_token );
$token->set_gateway_id( $this->id );
$token->set_last4( substr( $card_number, -4 ) );
$token->set_card_type( $card_type );
$token->save();

退款处理：

// GOOD: Implement refund support
public function process_refund( $order_id, $amount = null, $reason = '' ) {
    $order = wc_get_order( $order_id );

    // Process refund via API
    $result = $this->api_refund( $order, $amount );

    if ( $result->success ) {
        $order->add_order_note(
            sprintf( __( 'Refunded %s', 'text-domain' ), $amount )
        );
        return true;
    }

    return false;
}

交叉参考：

如需全面的安全模式，请参阅 wp-security-review
本节仅关注 WC 支付专属的反模式

配送方式（WOO-04）

WC_Shipping_Method 类结构：

// GOOD: Complete shipping method implementation
class WC_Shipping_Custom extends WC_Shipping_Method {

    public function __construct( $instance_id = 0 ) {
        $this->id = 'custom_shipping';
        $this->instance_id = absint( $instance_id );
        $this->method_title = __( 'Custom Shipping', 'text-domain' );
        $this->method_description = __( 'Description', 'text-domain' );
        $this->supports = array( 'shipping-zones', 'instance-settings' );

        $this->init();
    }

    public function calculate_shipping( $package = array() ) {
        $rate = array(
            'id' => $this->id . $this->instance_id,
            'label' => $this->title,
            'cost' => 10.00,
            'calc_tax' => 'per_order'
        );

        $this->add_rate( $rate );
    }
}

自定义产品类型（WOO-02）

产品类型注册：

// GOOD: Register custom product type
add_filter( 'product_type_selector', 'add_custom_product_type' );
function add_custom_product_type( $types ) {
    $types['custom-product'] = __( 'Custom Product', 'text-domain' );
    return $types;
}

// GOOD: Product class extending WC_Product
class WC_Product_Custom extends WC_Product {

    public function __construct( $product = 0 ) {
        $this->product_type = 'custom-product';
        parent::__construct( $product );
    }

    public function get_type() {
        return 'custom-product';
    }
}

// GOOD: Register product class
add_filter( 'woocommerce_product_class', 'load_custom_product_class', 10, 2 );
function load_custom_product_class( $classname, $product_type ) {
    if ( 'custom-product' === $product_type ) {
        $classname = 'WC_Product_Custom';
    }
    return $classname;
}

WooCommerce 钩子目录（WOO-05、WOO-06）

生命周期钩子：

// GOOD: Order lifecycle hooks
add_action( 'woocommerce_checkout_process', 'validate_custom_checkout_field' );
add_action( 'woocommerce_checkout_create_order', 'save_custom_order_data', 10, 2 );
add_action( 'woocommerce_thankyou', 'custom_thankyou_action' );
add_action( 'woocommerce_order_status_changed', 'handle_status_change', 10, 4 );

产品数据钩子：

// GOOD: Product admin hooks
add_action( 'woocommerce_product_options_general_product_data', 'add_custom_field' );
add_action( 'woocommerce_process_product_meta', 'save_custom_field' );

结账字段钩子：

// GOOD: Add checkout field
add_filter( 'woocommerce_checkout_fields', 'add_gift_message_field' );
function add_gift_message_field( $fields ) {
    $fields['order']['gift_message'] = array(
        'type' => 'textarea',
        'label' => __( 'Gift message', 'text-domain' ),
        'required' => false
    );
    return $fields;
}

add_action( 'woocommerce_checkout_update_order_meta', 'save_gift_message' );
function save_gift_message( $order_id ) {
    if ( ! empty( $_POST['gift_message'] ) ) {
        $order = wc_get_order( $order_id );
        $order->update_meta_data( 'gift_message', sanitize_textarea_field( $_POST['gift_message'] ) );
        $order->save();
    }
}

购物车操作（WOO-08）

购物车商品数据：

// GOOD: Add custom cart item data
add_filter( 'woocommerce_add_cart_item_data', 'add_custom_cart_data', 10, 2 );
function add_custom_cart_data( $cart_item_data, $product_id ) {
    if ( isset( $_POST['custom_field'] ) ) {
        $cart_item_data['custom_field'] = sanitize_text_field( $_POST['custom_field'] );
    }
    return $cart_item_data;
}

购物车费用：

// GOOD: Add custom fee
add_action( 'woocommerce_cart_calculate_fees', 'add_custom_fee' );
function add_custom_fee() {
    if ( WC()->cart->get_subtotal() > 100 ) {
        WC()->cart->add_fee( __( 'Handling fee', 'text-domain' ), 5 );
    }
}

购物车验证：

// GOOD: Validate cart contents
add_action( 'woocommerce_check_cart_items', 'validate_cart_items' );
function validate_cart_items() {
    if ( WC()->cart->get_cart_contents_count() < 3 ) {
        wc_add_notice( __( 'Minimum 3 items required', 'text-domain' ), 'error' );
    }
}

订单状态转换（WOO-07）

自定义订单状态：

// GOOD: Register custom order status
add_action( 'init', 'register_awaiting_shipment_status' );
function register_awaiting_shipment_status() {
    register_post_status( 'wc-awaiting-shipment', array(
        'label' => __( 'Awaiting Shipment', 'text-domain' ),
        'public' => true,
        'show_in_admin_status_list' => true,
        'label_count' => _n_noop(
            'Awaiting shipment <span class="count">(%s)</span>',
            'Awaiting shipment <span class="count">(%s)</span>',
            'text-domain'
        )
    ) );
}

add_filter( 'wc_order_statuses', 'add_awaiting_shipment_to_order_statuses' );
function add_awaiting_shipment_to_order_statuses( $order_statuses ) {
    $order_statuses['wc-awaiting-shipment'] = __( 'Awaiting Shipment', 'text-domain' );
    return $order_statuses;
}

// GOOD: Set order status
$order = wc_get_order( $order_id );
$order->set_status( 'awaiting-shipment', 'Order ready for shipment' );

购物车片段性能（WOO-15）

条件性取消入队：

// GOOD: Conditional cart fragments loading
add_filter( 'woocommerce_get_script_data', 'conditional_cart_fragments', 10, 2 );
function conditional_cart_fragments( $data, $handle ) {
    if ( 'wc-cart-fragments' === $handle ) {
        // Only load on WC pages
        if ( ! is_woocommerce() && ! is_cart() && ! is_checkout() ) {
            return null;
        }
    }
    return $data;
}

// CRITICAL: Site-wide cart fragments loading
// BAD: No conditional dequeue - loads on every page

Mini-Cart Block 替代方案：

// INFO: Recommend Mini-Cart Block migration
// Mini-Cart Block has built-in performance optimizations
// No cart fragments needed

Action Scheduler 模式

后台处理：

// GOOD: Action Scheduler for bulk operations
function schedule_order_export() {
    as_enqueue_async_action(
        'process_order_export',
        array( 'batch_id' => 123 ),
        'wc-exports'
    );
}

add_action( 'process_order_export', 'do_order_export', 10, 1 );
function do_order_export( $batch_id ) {
    $orders = wc_get_orders( array(
        'limit' => 100,
        'offset' => $batch_id * 100
    ) );

    foreach ( $orders as $order ) {
        // Export logic
    }

    // Schedule next batch if needed
    if ( count( $orders ) === 100 ) {
        as_enqueue_async_action(
            'process_order_export',
            array( 'batch_id' => $batch_id + 1 ),
            'wc-exports'
        );
    }
}

// WARNING: wp_cron for heavy WC tasks
// BAD:
wp_schedule_event( time(), 'hourly', 'process_order_export' );

Webhook 安全（WOO-20）

签名验证：

// GOOD: Verify webhook signature
function verify_wc_webhook( $payload, $signature, $secret ) {
    $expected = base64_encode( hash_hmac( 'sha256', $payload, $secret, true ) );

    // CRITICAL: Use hash_equals to prevent timing attacks
    return hash_equals( $expected, $signature );
}

// Webhook handler
$payload = file_get_contents( 'php://input' );
$signature = $_SERVER['HTTP_X_WC_WEBHOOK_SIGNATURE'] ?? '';
$delivery_id = $_SERVER['HTTP_X_WC_WEBHOOK_DELIVERY_ID'] ?? '';

// WARNING: Missing signature verification
if ( ! verify_wc_webhook( $payload, $signature, $secret ) ) {
    http_response_code( 401 );
    exit;
}

// GOOD: Check for duplicate delivery
if ( get_transient( 'wc_webhook_' . $delivery_id ) ) {
    http_response_code( 200 );
    exit;
}
set_transient( 'wc_webhook_' . $delivery_id, true, DAY_IN_SECONDS );

// GOOD: Process async via Action Scheduler
as_enqueue_async_action( 'process_wc_webhook', array( 'payload' => $payload ) );

模板覆盖反模式（WOO-10、WOO-11、WOO-12）

保留钩子：

// In child-theme/woocommerce/content-product.php

// GOOD: Preserve all action hooks from original template
do_action( 'woocommerce_before_shop_loop_item' );
do_action( 'woocommerce_before_shop_loop_item_title' );
// Custom content here
do_action( 'woocommerce_shop_loop_item_title' );
do_action( 'woocommerce_after_shop_loop_item_title' );
do_action( 'woocommerce_after_shop_loop_item' );

// CRITICAL: Deleted hooks in template override
// BAD: No do_action() calls - breaks plugin integration

版本跟踪：

// GOOD: Template with version comment
/**
 * Product loop template
 *
 * @version 8.9.0
 */

// WARNING: Outdated version
// Template version 3.6.0 when WC is 10.5 - may miss updates

优先使用钩子的理念：

// BETTER: Use hooks instead of template override
add_action( 'woocommerce_shop_loop_item_title', 'add_custom_content', 15 );
function add_custom_content() {
    // Custom content via hook - no template override needed
}

// INFO: Template override where hook exists
// Suggest using hook instead of copying entire template

交叉参考：

如需了解通用模板模式，请参阅 wp-theme-development

表层检查

WooCommerce Blocks 结账集成（WOO-14）：

// GOOD: Add checkout field via Additional Checkout Fields API (WC 8.6+)
add_action( 'woocommerce_init', 'register_custom_checkout_field' );
function register_custom_checkout_field() {
    woocommerce_register_additional_checkout_field( array(
        'id' => 'namespace/gift-message',
        'label' => __( 'Gift message', 'text-domain' ),
        'location' => 'order',
        'type' => 'text'
    ) );
}

WooCommerce REST API 扩展（WOO-09）：

// INFO: Custom REST endpoint registration
add_action( 'rest_api_init', 'register_custom_endpoint' );
function register_custom_endpoint() {
    register_rest_route( 'wc/v3', '/custom-endpoint', array(
        'methods' => 'GET',
        'callback' => 'custom_endpoint_callback',
        'permission_callback' => function() {
            return current_user_can( 'manage_woocommerce' );
        }
    ) );
}

优惠券验证（WOO-21）：

// GOOD: Custom coupon validation
add_filter( 'woocommerce_coupon_is_valid', 'validate_custom_coupon', 10, 3 );
function validate_custom_coupon( $valid, $coupon, $discount ) {
    if ( WC()->cart->get_cart_contents_count() < 3 ) {
        throw new Exception(
            __( 'Coupon requires at least 3 items', 'text-domain' ),
            109
        );
    }
    return $valid;
}

会话处理（WOO-18）：

// WARNING: Custom session filter exceeding 30-day cap (WC 10.1+)
// BAD:
add_filter( 'wc_session_expiration', function() {
    return 60 * DAY_IN_SECONDS; // Exceeds 30-day cap
} );

// GOOD: Respect 30-day cap
add_filter( 'wc_session_expiration', function() {
    return 30 * DAY_IN_SECONDS; // Maximum allowed
} );

快速检测的搜索模式（WOO-22）

使用以下 rg 命令和 Shell 检查，快速扫描 WooCommerce。按严重程度排列。

严重问题模式

# HPOS declaration candidates
# If this returns nothing in a WooCommerce extension, the plugin likely lacks HPOS declaration.
rg -n "declare_compatibility\s*\(\s*['\"]custom_order_tables['\"]" . -g '*.php'

# get_posts/WP_Query with shop_order
rg -n "post_type.*shop_order|shop_order.*post_type" . -g '*.php'

# Direct $wpdb queries against wp_posts for orders
rg -n "\$wpdb.*wp_posts.*shop_order" . -g '*.php'

# Raw card data storage/logging
rg -n "card_number|card_cvv|cvv.*meta|card.*error_log" . -g '*.php'

# Template overrides without do_action() calls
find . -path "*/woocommerce/*.php" -exec rg -L "do_action|apply_filters" {} \;

# Webhook signature handling candidates (manually confirm verification logic)
rg -n "X-WC-Webhook-Signature|hash_hmac|verify" . -g '*.php'

警告模式

# WP_Query with post_type=product (compare these result sets manually)
rg -n "WP_Query|get_posts" . -g '*.php'
rg -n "post_type.*product|product.*post_type" . -g '*.php'

# Site-wide cart-fragments loading without conditional dequeue (manual context check)
rg -n "wc-cart-fragments|woocommerce_get_script_data|is_woocommerce|is_cart" . -g '*.php'

# wp_cron for bulk WC operations (manual context check)
rg -n "wp_schedule_event|wp_cron|wc_|order|product" . -g '*.php'

# Hardcoded API credentials
rg -n "api_key.*=.*['\"][A-Za-z0-9]{20,}" . -g '*.php'

# get_post_meta/update_post_meta for order fields
rg -n "get_post_meta.*order_id|update_post_meta.*order_id" . -g '*.php'

# Session filters exceeding 30-day cap (manual follow-up on returned values)
rg -n "wc_session_expiration|wc_session_expiring" . -g '*.php'

INFO 模式

# Template overrides where hooks exist
find . -path "*/woocommerce/*.php" -type f

# Missing object caching for repeated product loads
rg -n "wc_get_product" . -g '*.php'

# Action Scheduler candidates
rg -n "foreach.*wc_get_orders|foreach.*wc_get_products" . -g '*.php'

# WC Blocks integration opportunities
rg -n "woocommerce_register_additional_checkout_field|Store API" . -g '*.php'

注意： WC 专属模式所需的上下文与通用 WP 不同。对于非订单类型的文章，使用 get_posts() 是有效的。对于标准文章／页面，使用 WP_Query 是有效的。只有在与 WC 专属文章类型结合使用时才标记。

WooCommerce 上下文检测

根据文件结构和模式提供上下文感知的审查说明：

扩展／插件

检测： 主插件文件中包含 WC 依赖检查和 HPOS 声明 审查重点： 全面审查 HPOS、CRUD 和钩子 最常见的上下文

主题集成

检测： 主题中包含带模板覆盖的 woocommerce/ 目录 审查重点： 模板覆盖质量、钩子保留情况 交叉参考： wp-theme-development 中的主题模式

支付网关

检测： 扩展 WC_Payment_Gateway 的类 审查重点： 加强安全审查（切勿存储原始银行卡数据、检查 HTTPS、验证 Webhook） 交叉参考： wp-security-review 中的通用安全审查

配送方式

检测： 扩展 WC_Shipping_Method 的类 审查重点： 审查 calculate_shipping()、区域支持、费率计算

自定义产品类型

检测： 扩展 WC_Product 的类 审查重点： 审查数据存储、产品类型注册、类层次结构

WC Blocks 集成

检测： 使用 Store API、结账区块扩展点 审查重点： 表层审查、Additional Checkout Fields API 交叉参考： wp-block-development 中的深入区块模式

快速参考：WooCommerce 开发模式（WOO-23）

按关注点整理的常见 WooCommerce 模式。所有示例均遵循 WordPress PHP 编码标准（括号内使用空格、使用 array() 而非 []、使用 Yoda 条件）。

HPOS 兼容性声明

❌ 错误：缺少 HPOS 声明

<?php
// Extension silently breaks on HPOS-enabled stores

✅ 正确：在 before_woocommerce_init 钩子中声明兼容性

<?php
add_action( 'before_woocommerce_init', function() {
    if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(
            'custom_order_tables',
            __FILE__,
            true
        );
    }
} );

订单数据访问

❌ 错误：直接访问文章（会破坏 HPOS）

<?php
$orders = get_posts( array(
    'post_type' => 'shop_order',
    'post_status' => 'wc-completed'
) );
update_post_meta( $order_id, 'custom_field', $value );

✅ 正确：兼容 HPOS 的 CRUD

<?php
$orders = wc_get_orders( array(
    'status' => 'completed',
    'limit' => 10
) );

$order = wc_get_order( $order_id );
$order->update_meta_data( 'custom_field', $value );
$order->save();

订单元数据操作

❌ 错误：直接使用元数据函数

<?php
update_post_meta( $order_id, 'delivery_date', '2026-02-15' );
$date = get_post_meta( $order_id, 'delivery_date', true );

✅ 正确：使用 WC_Order 方法

<?php
$order = wc_get_order( $order_id );
$order->update_meta_data( 'delivery_date', '2026-02-15' );
$order->save();

$date = $order->get_meta( 'delivery_date', true );

产品数据访问

❌ 错误：对产品使用 WP_Query（未来可能造成兼容性问题）

<?php
$products = new WP_Query( array(
    'post_type' => 'product',
    'posts_per_page' => 10
) );

✅ 正确：使用 WC_Product_Query

<?php
$query = new WC_Product_Query( array(
    'status' => 'publish',
    'limit' => 10,
    'category' => array( 'clothing' ),
    'orderby' => 'date',
    'order' => 'DESC'
) );
$products = $query->get_products();

支付网关

❌ 错误：存储原始银行卡数据、缺少 HTTPS 检查

<?php
public function process_payment( $order_id ) {
    // CRITICAL: Never store raw card data
    update_post_meta( $order_id, 'card_number', $_POST['card_number'] );

    // Process payment
    $order = wc_get_order( $order_id );
    $order->update_status( 'processing' ); // Manual status change

    return array(
        'result' => 'success',
        'redirect' => $this->get_return_url( $order )
    );
}

✅ 正确：使用令牌化、检查 HTTPS、调用 payment_complete()

<?php
public function process_payment( $order_id ) {
    $order = wc_get_order( $order_id );

    // Check HTTPS in production
    if ( ! is_ssl() && 'yes' !== $this->get_option( 'testmode' ) ) {
        wc_add_notice( __( 'SSL required', 'text-domain' ), 'error' );
        return array( 'result' => 'failure' );
    }

    // Process via API (use tokenization, never store raw cards)
    $result = $this->api_charge( $order );

    if ( $result->success ) {
        // Use payment_complete() not manual status change
        $order->payment_complete( $result->transaction_id );

        return array(
            'result' => 'success',
            'redirect' => $this->get_return_url( $order )
        );
    }

    return array( 'result' => 'failure' );
}

配送方式

✅ 正确：完整的配送方式

<?php
class WC_Shipping_Custom extends WC_Shipping_Method {

    public function __construct( $instance_id = 0 ) {
        $this->id = 'custom_shipping';
        $this->instance_id = absint( $instance_id );
        $this->method_title = __( 'Custom Shipping', 'text-domain' );
        $this->supports = array( 'shipping-zones', 'instance-settings' );

        $this->init();
    }

    public function calculate_shipping( $package = array() ) {
        $rate = array(
            'id' => $this->id . $this->instance_id,
            'label' => $this->title,
            'cost' => 10.00,
            'calc_tax' => 'per_order'
        );

        $this->add_rate( $rate );
    }
}

自定义产品类型

✅ 正确：注册并实现自定义产品类型

<?php
// Register product type
add_filter( 'product_type_selector', 'add_custom_product_type' );
function add_custom_product_type( $types ) {
    $types['custom-product'] = __( 'Custom Product', 'text-domain' );
    return $types;
}

// Product class
class WC_Product_Custom extends WC_Product {

    public function __construct( $product = 0 ) {
        $this->product_type = 'custom-product';
        parent::__construct( $product );
    }

    public function get_type() {
        return 'custom-product';
    }
}

// Register product class
add_filter( 'woocommerce_product_class', 'load_custom_product_class', 10, 2 );
function load_custom_product_class( $classname, $product_type ) {
    if ( 'custom-product' === $product_type ) {
        $classname = 'WC_Product_Custom';
    }
    return $classname;
}

购物车操作

✅ 正确：添加购物车项目数据

<?php
add_filter( 'woocommerce_add_cart_item_data', 'add_custom_cart_data', 10, 2 );
function add_custom_cart_data( $cart_item_data, $product_id ) {
    if ( isset( $_POST['custom_field'] ) ) {
        $cart_item_data['custom_field'] = sanitize_text_field( $_POST['custom_field'] );
    }
    return $cart_item_data;
}

✅ 正确：添加购物车费用

<?php
add_action( 'woocommerce_cart_calculate_fees', 'add_custom_fee' );
function add_custom_fee() {
    if ( WC()->cart->get_subtotal() > 100 ) {
        WC()->cart->add_fee( __( 'Handling fee', 'text-domain' ), 5 );
    }
}

订单状态转换

❌ 错误：手动更改文章状态

<?php
wp_update_post( array(
    'ID' => $order_id,
    'post_status' => 'wc-processing'
) );

✅ 正确：使用 WC_Order::set_status()

<?php
$order = wc_get_order( $order_id );
$order->set_status( 'processing', 'Payment received' );
// Automatically saved

✅ 正确：在支付流程中使用 payment_complete()

<?php
$order = wc_get_order( $order_id );
$order->payment_complete( $transaction_id );

保留钩子的模板覆盖

❌ 错误：模板覆盖中删除了钩子

<?php
// In child-theme/woocommerce/content-product.php
// CRITICAL: No do_action() calls - breaks plugin integration
?>
<li class="product">
    <h2><?php the_title(); ?></h2>
    <div class="price"><?php echo $product->get_price_html(); ?></div>
</li>

✅ 正确：保留所有操作钩子

<?php
// In child-theme/woocommerce/content-product.php
do_action( 'woocommerce_before_shop_loop_item' );
do_action( 'woocommerce_before_shop_loop_item_title' );
?>
<h2><?php the_title(); ?></h2>
<?php
do_action( 'woocommerce_shop_loop_item_title' );
do_action( 'woocommerce_after_shop_loop_item_title' );
do_action( 'woocommerce_after_shop_loop_item' );

✅ 更佳：使用钩子，而非覆盖模板

<?php
add_action( 'woocommerce_shop_loop_item_title', 'add_custom_content', 15 );
function add_custom_content() {
    // Custom content via hook - no template override needed
}

购物车片段优化

❌ 错误：在全站加载购物车片段

<?php
// No conditional dequeue - loads on every page
// CRITICAL performance issue

✅ 正确：按条件取消排队

<?php
add_filter( 'woocommerce_get_script_data', 'conditional_cart_fragments', 10, 2 );
function conditional_cart_fragments( $data, $handle ) {
    if ( 'wc-cart-fragments' === $handle ) {
        if ( ! is_woocommerce() && ! is_cart() && ! is_checkout() ) {
            return null;
        }
    }
    return $data;
}

✅ 更佳：迁移到 Mini-Cart Block

// Mini-Cart Block has built-in performance optimizations
// No cart fragments needed

Action Scheduler

❌ 错误：使用 wp_cron 执行批量 WC 操作

<?php
wp_schedule_event( time(), 'hourly', 'process_order_export' );

add_action( 'process_order_export', 'do_export' );
function do_export() {
    // Unreliable, traffic-dependent, no retry
}

✅ 正确：使用 Action Scheduler 执行批量操作

<?php
function schedule_order_export() {
    as_enqueue_async_action(
        'process_order_export',
        array( 'batch_id' => 0 ),
        'wc-exports'
    );
}

add_action( 'process_order_export', 'do_order_export', 10, 1 );
function do_order_export( $batch_id ) {
    $orders = wc_get_orders( array(
        'limit' => 100,
        'offset' => $batch_id * 100
    ) );

    foreach ( $orders as $order ) {
        // Export logic
    }

    // Schedule next batch if needed
    if ( 100 === count( $orders ) ) {
        as_enqueue_async_action(
            'process_order_export',
            array( 'batch_id' => $batch_id + 1 ),
            'wc-exports'
        );
    }
}

Webhook 安全

❌ 错误：缺少签名验证

<?php
// Webhook handler
$payload = file_get_contents( 'php://input' );
$data = json_decode( $payload );

// WARNING: No signature verification - allows forged webhooks
process_webhook( $data );

✅ 正确：使用 hash_equals() 验证 HMAC-SHA256

<?php
function verify_wc_webhook( $payload, $signature, $secret ) {
    $expected = base64_encode( hash_hmac( 'sha256', $payload, $secret, true ) );
    return hash_equals( $expected, $signature );
}

// Webhook handler
$payload = file_get_contents( 'php://input' );
$signature = $_SERVER['HTTP_X_WC_WEBHOOK_SIGNATURE'] ?? '';
$delivery_id = $_SERVER['HTTP_X_WC_WEBHOOK_DELIVERY_ID'] ?? '';

if ( ! verify_wc_webhook( $payload, $signature, $secret ) ) {
    http_response_code( 401 );
    exit;
}

// Check for duplicate delivery
if ( get_transient( 'wc_webhook_' . $delivery_id ) ) {
    http_response_code( 200 );
    exit;
}
set_transient( 'wc_webhook_' . $delivery_id, true, DAY_IN_SECONDS );

// Process async
as_enqueue_async_action( 'process_wc_webhook', array( 'payload' => $payload ) );

WooCommerce Blocks 结账

✅ 正确：Additional Checkout Fields API（WC 8.6+）

<?php
add_action( 'woocommerce_init', 'register_custom_checkout_field' );
function register_custom_checkout_field() {
    woocommerce_register_additional_checkout_field( array(
        'id' => 'namespace/gift-message',
        'label' => __( 'Gift message', 'text-domain' ),
        'location' => 'order',
        'type' => 'text',
        'attributes' => array(
            'maxLength' => 200
        )
    ) );
}

// Access field value
$order = wc_get_order( $order_id );
$gift_message = $order->get_meta( 'namespace/gift-message' );

REST API 扩展

✅ 正确：带身份验证的自定义 REST 端点

<?php
add_action( 'rest_api_init', 'register_custom_endpoint' );
function register_custom_endpoint() {
    register_rest_route( 'wc/v3', '/custom-endpoint', array(
        'methods' => 'GET',
        'callback' => 'custom_endpoint_callback',
        'permission_callback' => function() {
            return current_user_can( 'manage_woocommerce' );
        }
    ) );
}

优惠券验证

✅ 正确：自定义优惠券验证

<?php
add_filter( 'woocommerce_coupon_is_valid', 'validate_custom_coupon', 10, 3 );
function validate_custom_coupon( $valid, $coupon, $discount ) {
    if ( WC()->cart->get_cart_contents_count() < 3 ) {
        throw new Exception(
            __( 'Coupon requires at least 3 items', 'text-domain' ),
            109
        );
    }
    return $valid;
}

会话处理

❌ 错误：超过 30 天上限

<?php
add_filter( 'wc_session_expiration', function() {
    return 60 * DAY_IN_SECONDS; // Exceeds cap
} );

✅ 正确：遵守 30 天上限（WC 10.1+）

<?php
add_filter( 'wc_session_expiration', function() {
    return 30 * DAY_IN_SECONDS; // Maximum allowed
} );

电子邮件自定义

✅ 正确：扩展 WC_Email 类

<?php
class WC_Email_Custom extends WC_Email {

    public function __construct() {
        $this->id = 'custom_email';
        $this->title = __( 'Custom Email', 'text-domain' );
        $this->description = __( 'Email description', 'text-domain' );

        $this->template_html = 'emails/custom-email.php';
        $this->template_plain = 'emails/plain/custom-email.php';

        parent::__construct();
    }

    public function trigger( $order_id ) {
        $this->object = wc_get_order( $order_id );

        if ( ! $this->is_enabled() || ! $this->get_recipient() ) {
            return;
        }

        $this->send( $this->get_recipient(), $this->get_subject(), $this->get_content(), $this->get_headers(), $this->get_attachments() );
    }
}

严重程度定义（WOO-24）

严重程度	定义	示例
CRITICAL	扩展会在现代 WC 商店中失效，或存在安全漏洞	缺少 HPOS 兼容性声明；直接访问订单文章（使用 get_posts/WP_Query 查询 shop_order）；直接查询订单/产品数据库；存储/记录原始银行卡数据（数据库或 error_log 中出现 card_number）；模板覆盖中包含已删除的操作钩子；缺少 Webhook 签名验证；通过 HTTP 传输银行卡数据
WARNING	扩展可以正常工作，但存在质量/兼容性/性能问题	使用 WP_Query 查询产品（未来可能导致故障）；在全站加载购物车片段；模板覆盖已过时（版本不匹配）；代码中硬编码 API 凭据；使用 wp_cron() 执行批量 WC 操作；会话时长超过 30 天；使用 get_post_meta/update_post_meta 处理订单字段；支付处理中缺少 HTTPS 检查
INFO	最佳实践改进或优化机会	存在钩子的模板覆盖（建议改用钩子）；轻量任务使用 Action Scheduler 而非 wp_cron；对重复加载的产品使用对象缓存；集成 WC Blocks 的机会；使用 Additional Checkout Fields API；产品对象缓存（WC 10.5+ 实验性功能）

输出格式（WOO-24）

按文件分组报告发现的问题（PHP 文件按实际文件路径排列），并标注行号和严重程度。每个问题都使用 BAD/GOOD 代码对照。

# WooCommerce Review: my-wc-extension

## FILE: includes/class-order-handler.php

### Line 45: CRITICAL - Direct post access for orders
get_posts() with post_type='shop_order' breaks on HPOS-enabled stores. Use wc_get_orders() instead.

❌ **BAD:**
```php
$orders = get_posts( array(
    'post_type' => 'shop_order',
    'post_status' => 'wc-completed'
) );

✅ GOOD：

$orders = wc_get_orders( array(
    'status' => 'completed',
    'limit' => 10
) );

第 67 行：CRITICAL - 使用直接 meta 函数处理订单数据

对订单数据调用 update_post_meta() 会破坏 HPOS 兼容性。请改用 WC_Order 方法。

❌ BAD：

update_post_meta( $order_id, 'custom_field', $value );

✅ GOOD：

$order = wc_get_order( $order_id );
$order->update_meta_data( 'custom_field', $value );
$order->save();

文件：my-wc-extension.php

第 1 行：CRITICAL - 缺少 HPOS 声明

扩展必须声明 HPOS 兼容状态。请添加 before_woocommerce_init 钩子。

❌ BAD：

<?php
// No HPOS declaration - extension silently incompatible

✅ GOOD：

<?php
add_action( 'before_woocommerce_init', function() {
    if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(
            'custom_order_tables',
            __FILE__,
            true
        );
    }
} );

文件：includes/class-gateway.php

第 89 行：CRITICAL - 记录原始银行卡数据

记录银行卡数据违反 PCI 规范，构成安全漏洞。切勿记录支付信息。

❌ BAD：

error_log( 'Processing card: ' . $_POST['card_number'] );

✅ GOOD：

// Never log card data
// Use tokenization, log transaction IDs only
$this->log( 'Processing transaction: ' . $transaction_id );

第 102 行：WARNING - 缺少 HTTPS 检查

在生产模式下处理支付前，请检查 is_ssl()。

❌ BAD：

public function process_payment( $order_id ) {
    // Process payment without SSL check
}

✅ GOOD：

public function process_payment( $order_id ) {
    if ( ! is_ssl() && 'yes' !== $this->get_option( 'testmode' ) ) {
        wc_add_notice( __( 'SSL required', 'text-domain' ), 'error' );
        return array( 'result' => 'failure' );
    }
    // Process payment
}

文件：includes/class-cart-fragments.php

第 23 行：WARNING - 全站加载购物车片段

每个页面都加载购物车片段会导致性能问题。请添加条件式取消加载逻辑。

❌ BAD：

// No conditional dequeue - loads on all pages

✅ GOOD：

add_filter( 'woocommerce_get_script_data', 'conditional_cart_fragments', 10, 2 );
function conditional_cart_fragments( $data, $handle ) {
    if ( 'wc-cart-fragments' === $handle ) {
        if ( ! is_woocommerce() && ! is_cart() && ! is_checkout() ) {
            return null;
        }
    }
    return $data;
}

摘要

问题总数：7

CRITICAL：4（必须修复——扩展在启用 HPOS 的商店中会失效，或存在安全违规）
WARNING：2（质量/性能问题）
INFO：1（最佳实践改进）

HPOS 兼容性风险： HIGH——扩展会在现代 WooCommerce 商店中失效 安全说明： 检测到支付安全问题。运行 /wp-sec-review 进行全面安全分析。 性能说明： 检测到购物车片段性能问题。运行 /wp-perf-review 进行全面性能分析。


## Common Mistakes (WOO-25)

Patterns that look like issues but are NOT problems:

| Pattern | Why It's NOT a Problem | Context |
|---------|------------------------|---------|
| **get_posts() for custom post types (not orders)** | Valid when post type is not 'shop_order'. Only shop_order queries break HPOS. | Extensions can use get_posts() for their own post types |
| **WP_Query for standard posts/pages** | Valid for non-product queries. Only product queries flagged as WARNING. | Blog posts, custom post types are fine with WP_Query |
| **get_post_meta() for custom post types (not orders)** | Valid when not accessing order data. Only order meta breaks HPOS. | Custom post type meta operations work normally |
| **Template overrides in child themes** | Legitimate when hooks are preserved. Only flag if do_action() calls deleted. | Intentional customization with proper hook preservation |
| **wc-cart-fragments.js on cart/checkout/product pages** | Expected on WC pages. Only flag site-wide loading. | Conditional loading to WC pages is correct |
| **wp_cron() for lightweight non-WC tasks** | Acceptable for simple scheduled tasks. Only flag for heavy WC operations. | Daily cleanup, simple notifications are fine |
| **WC_Session usage within 30-day window** | Normal behavior. Only flag custom filters exceeding cap. | Standard session handling works correctly |
| **error_log() in non-payment code** | Acceptable debugging. Only flag in payment processing context. | General logging is fine, just not card data |
| **Direct $wpdb for custom tables (NOT WC core tables)** | Valid for extension's own tables. Only flag queries against wp_posts/wp_postmeta for WC data. | Custom table queries don't affect HPOS |
| **process_payment() accessing $_POST for custom fields** | Valid for non-card data (shipping notes, gift messages). Only flag raw card data access. | Custom checkout field handling is expected |
| **Template overrides without @version comment** | Missing metadata, not necessarily outdated. Only flag significant version mismatches. | Version tracking helps but absence isn't critical |
| **apiVersion 2 in WC Blocks integration** | Block-related, not WC-specific. Defer to wp-block-development. | Block patterns handled by block skill |

## Version Compatibility Reference

Quick reference for WooCommerce version requirements:

| Feature | WooCommerce Version | Notes |
|---------|---------------------|-------|
| WC_Data CRUD API | 3.0+ | Base class for all CRUD objects |
| wc_get_order(), wc_get_product() | 3.0+ | Preferred data access methods |
| Product attribute lookup table | 6.3+ | Indexed product attributes for filtering |
| Cart fragments no longer global by default | 7.8+ | Requires opt-in for site-wide loading |
| HPOS (Custom Order Tables) default | 8.2+ | New stores use HPOS by default |
| HPOS compatibility declaration required | 8.2+ | declare_compatibility() mandatory |
| Additional Checkout Fields API | 8.6+ | Block checkout field registration |
| Session 30-day cap enforced | 10.1+ | Maximum session duration limit |
| wc_enqueue_js() deprecated | 10.4+ | Use wp_add_inline_script() instead |
| Product object caching (experimental) | 10.5+ | Opt-in performance feature |
| Variation price caching improvements | 10.5+ | Automatic performance optimization |
| Batch analytics imports (100/12hrs) | 10.5+ | Background processing improvements |

## Deep-Dive References

For advanced WooCommerce development patterns, load these companion reference documents:

| Task | Reference to Load |
|------|-------------------|
| HPOS compatibility migration, payment gateway development (WC_Payment_Gateway lifecycle, process_payment flow, refund handling, security patterns), shipping methods (WC_Shipping_Method, calculate_shipping, zones), custom product types (register_product_type, data stores), order handling (WC_Order CRUD, status transitions), cart operations (cart item data, fees, validation), REST API extensions, Action Scheduler patterns, webhook security | `references/wc-extension-guide.md` |
| Template hierarchy (archive-product, content-product, single-product, cart, checkout, myaccount), override procedures (child theme woocommerce/ directory, version tracking), hooks-first philosophy (when to use hooks vs overrides, preserving action hooks), shop/product/cart/checkout theming, WooCommerce Blocks compatibility notes, email templates | `references/wc-template-guide.md` |
| Cart fragments analysis (problem, solutions, Mini-Cart Block), WC_Product_Query optimization, HPOS performance benefits, session handling (30-day cap, cleanup), Action Scheduler for background processing, transient and object caching strategies, variation price caching, product attribute lookup table, database optimization | `references/wc-performance-guide.md` |

**Note:** Reference docs provide deep-dive content. This SKILL.md is self-sufficient for standard WooCommerce reviews.

**Security crossover:** When encountering security-relevant patterns (payment data handling, REST API authentication, AJAX nonce verification, capability checks), this skill provides brief reminders but defers to wp-security-review for comprehensive security analysis. For detailed security patterns, use `/wp-sec-review` command.

**Plugin crossover:** When encountering plugin-level patterns (WC dependency checking, activation/deactivation, hooks architecture, REST API registration), this skill provides brief mentions but defers to wp-plugin-development for plugin architecture depth. For detailed plugin review, use `/wp-plugin-review` command.

**Block crossover:** When encountering WooCommerce Blocks integration (Store API, checkout block extension points, Additional Checkout Fields API), this skill provides brief mentions but defers to wp-block-development for block development depth. For detailed block patterns, use `/wp-block-review` command.

**Theme crossover:** When encountering template overrides in themes (woocommerce/ directory, template hierarchy, version tracking), this skill provides brief mentions but defers to wp-theme-development for theme development depth. For detailed theme review, use `/wp-theme-review` command.

**Performance crossover:** When encountering cart fragments, query optimization, caching strategies, this skill provides brief mentions but defers to wp-performance-review for comprehensive performance analysis. For detailed performance patterns, use `/wp-perf-review` command.

支持 Markdown

登录后评论

基本信息

作者: jorgerosal
仓库: jorgerosal/wordpress-skills
分类: 测试与质量
安装次数: 76
GitHub Stars: 111

报告问题