respira-woocommerce

Respira WooCommerce

此技能涵盖的内容

Respira WooCommerce 扩展（v2.1.0+）通过 WordPress Abilities API 提供 21 项能力，还为 Elementor、Divi、Flatsome UX Builder、Bricks 和 Gutenberg 商店／产品模板提供店面布局操作界面。此扩展为付费扩展，且需要许可证；如果扩展未启用，所有 Woo 工具都会返回清晰的 respira_webmcp_woo_unavailable 错误，并应引导用户前往 respira.press/addons/woocommerce。

这 21 项能力位于 respira-woocommerce/* 命名空间下：

• 产品：get-products、get-product、create-product、update-product、duplicate-product。
• 分类：get-categories、get-category、create-category、update-category、delete-category。
• 标签：get-tags、get-tag、create-tag、update-tag、delete-tag。
• 订单：get-orders、get-order、update-order-status。
• 库存：get-stock-status、update-stock。
• 报告：get-sales-report。

店面操作界面（位于 /respira/v1/woocommerce/storefront/ 下）涵盖 analyze-shop、analyze-product、update-card-layout 和 add-low-stock-badge。这些工具作用于由构建器管理的商品卡片模板，而非 WC 核心数据。

常见错误

错误做法	正确做法
对 WooCommerce 产品页面使用 respira_update_page	使用 WooCommerce 的 update-product 能力更新产品数据。使用 respira_find_element 和 respira_update_element 更新页面上由构建器管理的视觉内容。
直接在页面内容中编辑产品价格或库存	这些是文章元字段。请使用 update-product 或 update-stock 能力。
在大型商品目录中不分页就运行 get-products	始终设置 per_page（最大值为 100）并进行分页。大型商品目录会导致超时。
通过文章元字段应用优惠券	优惠券应通过规范的 WooCommerce 优惠券修改功能（或 WC 管理后台）处理。直接编辑元数据会绕过 WC 验证。
通过 update_page 编辑由构建器管理的商店归档模板	先使用 respira_get_builder_info 确认模板类型。店面工具可更改商品卡片布局；视觉编辑应使用 respira_update_element。
调用 Woo 工具前未检查 WooCommerce 是否已启用	使用 respira_get_site_context 确认。如果插件未启用或扩展未获得许可，Woo 工具会返回结构化错误。
忘记 update-order-status 只会更改状态	更新订单的其他内容（商品行、总计、地址）需要使用 WC 管理后台或专用工具。此能力刻意限定了范围。

输入

• 产品 ID、SKU 或搜索词。
• 分类或标签的 slug 或 ID。
• 订单 ID 或订单状态筛选条件（pending、processing、on-hold、completed、cancelled、refunded、failed）。
• 优惠券代码或优惠券 ID。
• 要读取或更新的字段。

工作流

产品操作

1. respira_get_site_context。确认 WooCommerce 已启用且扩展已获得许可。
2. get-products。按名称、SKU 或筛选条件查找产品。设置 per_page 并进行分页。
3. update-product。应用更改（价格、库存、状态、标题、描述、图片）。
4. 如需编辑产品页面上的视觉内容或构建器内容：使用 respira_get_builder_info、respira_find_element 和 respira_update_element。

分类和标签操作

1. 使用 get-categories 或 get-tags。按 slug 或名称查找目标项。
2. 使用 create-、update- 或 delete-。修改操作受能力检查限制。
3. 使用 update-category 调整顺序或更改父级（设置 parent 和 display order）。

订单操作

1. 使用带状态筛选条件的 get-orders。
2. 使用 get-order 获取指定记录。
3. 使用 update-order-status 更改状态。其他涉及较大改动的操作需要通过 WC 管理后台完成。

库存操作

1. 使用 get-stock-status 获取快照。
2. 使用 update-stock 修改数量或状态。此能力会遵循每个产品的 manage_stock 设置。

店面布局

1. analyze-shop 或 analyze-product。返回当前使用的构建器以及可编辑的卡片 / 模板路径。
2. 使用 update-card-layout 修改商品卡片结构。
3. 使用 add-low-stock-badge 插入条件徽章小组件。
4. 始终先使用 respira_create_page_duplicate 为页面创建快照。

批量更新商品

要更新多个商品（例如提高某个类别中所有商品的价格）：

1. 使用带类别筛选条件的 get-products。收集目标 ID。
2. 使用 respira_batch_update。在一次调用中对收集到的所有 ID 应用相同的字段更改。

规则

• 调用 Woo 工具前，务必确认 WooCommerce 已启用且插件已获许可。
• 切勿使用 respira_update_page 修改商品页面上的价格、库存或商品元数据。这些属于 WC 数据字段。
• 对于商品描述：如果商品页面使用构建器，视觉描述可能位于构建器 JSON 中。使用 respira_find_element 查找该内容。WC description 字段是备用描述（用于非构建器页面）。
• respira_batch_update 每次调用最多接受 100 个项目。较大的操作需分批处理。
• 未向用户确认折扣类型前，切勿创建或修改优惠券。将百分比优惠券应用为 fixed_cart 可能造成重大收入损失。
• 货币因站点而异。不要假设是 USD 或 EUR；请从 respira_get_site_context 读取。

验证

执行 update-product 后：

1. 调用 get-product，确认已更改的字段正确。
2. 对于价格更改，验证 regular_price 和 sale_price 均正确。
3. 对于库存更改，验证 stock_quantity 和 stock_status。

执行 update-order-status 后：

1. 调用 get-order，确认状态转换正确。
2. 请注意，WC 会在某些状态转换时自动发送电子邮件；告知用户。

批量更新后：

1. 从批次中抽查 2-3 个商品，验证字段已更改。
2. 报告更新的商品总数，以及返回错误的商品。

升级处理

出现以下情况时，请停止并询问用户：

• 商品目录超过 1,000 件，且请求为“更新所有商品”。先确认范围和批处理策略。
• 优惠券更新会影响不限使用次数或全站折扣。应用前先确认。
• 涉及 WooCommerce Subscriptions、Memberships 或 Bookings。这些有各自的数据模型。继续前请检查可用工具。
• 更新会将商品的 status 从 publish 改为 draft。确认用户确实要取消发布。
• 订单已付款并发货，且请求会修改该订单。WC 会为已付款订单保存不可变更的历史记录；修改前请先询问。

示例

目标：将 “Merino Wool Tee” 的常规价格从 €49 调整为 €59。

1. respira_get_site_context        → WooCommerce 8.7 active, Woo add-on licensed ✓
2. get-products                    → search "Merino Wool Tee" → ID 2847
3. update-product                  → ID 2847, regular_price: "59"
4. get-product                     → ID 2847 → regular_price: "59.00" ✓