用途
该技能用于检查 Shopify 店铺中捆绑商品（bundle）的实际可履约能力。它会遍历所有被标记为捆绑的商品——无论是通过 Shopify 原生的 requiresComponents 机制，还是通过 bundle.components metafield 约定定义——然后验证每个组件变体是否有足够库存来支撑捆绑所需的数量比例。最终会暴露出那些在店铺前台显示为有货、但实际上因某个组件缺货而无法履约的捆绑商品。
该技能为只读操作，不执行任何变更。
主要能力
- 识别捆绑商品：支持 Shopify 原生捆绑（requiresComponents）和 metafield 定义的捆绑（bundle.components）。
- 解析组件清单：原生捆绑使用 productVariant.requiresComponents 和 productVariant.productVariantComponents；metafield 捆绑解析 JSON 值为 [{variantId, quantity}]。
- 查询组件库存：批量查询组件变体的 inventoryQuantity、inventoryItem 及按地点的库存水平。
- 计算可构建数量：对每个捆绑计算 max_buildable_units = floor(min over components of (component_on_hand - safety_stock) / required_qty)。
- 标记问题捆绑：max_buildable_units == 0 标记为 broken（无法构建），低于阈值标记为 constrained（受限）。
- 输出 CSV 报告，包含瓶颈组件信息。
使用方式
前置条件
- 已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_products,read_inventory
- API 权限范围：read_products、read_inventory
参数
- store（字符串，必填）：店铺域名，例如 mystore.myshopify.com
- metafield_namespace（字符串，可选，默认 bundle）：存放捆绑组件定义的 metafield 命名空间
- metafield_key（字符串，可选，默认 components）：存放 {variantId, quantity} JSON 列表的 metafield 键
- safety_stock（整数，可选，默认 0）：若现有库存减去此缓冲后低于所需数量，则视为组件缺货
- only_listed（布尔，可选，默认 true）：仅检查状态为 ACTIVE 的捆绑商品
- format（字符串，可选，默认 human）：输出格式，human 或 json
工作流程
- 查询捆绑商品（products 查询）：使用 query "metafield:<namespace>.<key>:* OR product_type:bundle"，分页直到 hasNextPage: false。
- 解析每个捆绑的组件清单。
- 批量查询组件变体库存（productVariants 查询）。
- 批量查询组件库存项及按地点库存水平（inventoryItems 查询）。
- 计算每个捆绑的 max_buildable_units，标记 broken 或 constrained。
输出格式
生成 CSV 文件 bundle_availability_<YYYY-MM-DD>.csv，列包括：bundle_product_id、bundle_title、bundle_variant_sku、max_buildable_units、bottleneck_component_sku、bottleneck_component_title、bottleneck_required_qty、bottleneck_on_hand、status。
human 格式会输出汇总统计（检查的捆绑数、完全可构建数、受限数、无法构建数）及主要问题捆绑列表。json 格式输出结构化结果。
适用场景
- 拥有大量捆绑商品的店铺，建议每日运行，在客户购买无法发货的商品之前发现损坏的捆绑。
- 使用 safety_stock 为同一组件的非捆绑销售保留缓冲——捆绑与独立变体共享库存。
- 可与 inventory-adjustment 或 low-inventory-restock 配合，将损坏的捆绑转化为补货操作。
- 对于原生捆绑，requiresComponents: true 是权威依据，当两者同时存在时优先使用它而非 metafield 约定。
- max_buildable_units = 0 的捆绑应暂时下架，直到瓶颈组件补货；可考虑与 product-lifecycle-manager 链式使用。
限制
- 只读技能，不执行任何变更，不会调整组件数量或捆绑可用性。
- 需要已认证的 Shopify CLI 会话及 read_products、read_inventory 权限。
- 遇到 API 限流（THROTTLED）需等待 2 秒并最多重试 3 次。
- metafield 值 JSON 无效时跳过该捆绑并记录警告。
- 组件变体 ID 无法解析（组件商品已删除）时标记为 BROKEN_REFERENCE。
- 组件 tracked: false（未跟踪库存）时视为无限可用并在输出中注明。