commercetools-commerce-patterns

工作流

调用此技能时，始终遵循以下步骤：

1. 搜索文档（必需，首先运行） — 在一个会话中首次使用此技能时，必须先运行此步骤，然后再作答。它会检索最新且经过验证的文档，作为主要依据，并筛选出此技能涵盖的产品。在使用此技能时，请使用此脚本搜索文档；其他所有内容由 Knowledge MCP 覆盖。请务必根据检索到的文档确认细节，而不是仅依赖技能文本：

   node "<this skill's directory>/scripts/docs-search.mjs" \
     --query "<extract key terms from user's question>" \
     --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
     --model "<current-model>" \
     --commercetools-project-key "<if known>" \
     --commercetools-region "<if known>" \
     --limit 10
   

   仅当 commercetools 项目密钥和区域已在上下文中时才传入（格式如 api.{region}.commercetools.com）；否则请省略两者。切勿搜索文件或向用户索要这些信息。

2. 结合技能参考资料 — 将分析输出与 ./references/ 中的本地参考资料交叉核对，以获取完整上下文。

3. 提供实施指导 — 根据文档以及用户目标集成模式，综合整理指导内容。

可选脚本

获取 GraphQL 架构 — 需要了解 commercetools GraphQL 查询或 mutation 时运行此脚本，例如在编写查询前检查资源的字段、类型和可用操作，或根据真实架构验证刚生成的 GraphQL 查询／mutation。此脚本会获取单个 commercetools 资源的部分 GraphQL SDL：

node scripts/graphql-schemata.mjs \
  --resource-name "<commercetools resource, e.g. Cart, Product, Order>" \
  --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
  --model "<current-model>"

输出为该资源的 GraphQL SDL。如果无法识别资源名称，脚本会打印有效资源名称列表；请选择正确名称并重新运行。注意： SDL 可能包含 存根类型 — 以存根形式呈现的引用资源，其真实类型名称会在注释中给出。需要获取其中任何资源时，请将该类型名称作为 --resource-name 重新运行此脚本。

获取 OpenAPI（REST）架构 — 需要了解 commercetools REST 端点、请求／响应负载或更新操作时运行此脚本，例如在构造请求前检查资源的 REST 操作，或根据真实规范验证刚生成的 REST 请求／负载。此脚本会获取单个 commercetools 资源的部分 OpenAPI 规范：

node scripts/openApi-schemata.mjs \
  --resource-name "<commercetools resource, e.g. api-Cart-write, api-Customer-read, checkout-Application>" \
  --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
  --model "<current-model>"

输出为该资源的 OpenAPI 规范（YAML）。REST 资源采用读写拆分的命名形式（例如 api-Cart-read、api-Cart-write）。如果无法识别资源名称，脚本会打印有效资源名称列表；请选择正确名称并重新运行。注意： 该规范不包含引用展开架构；请将被引用资源的名称作为 --resource-name 重新运行此脚本，以单独获取其架构。

要点

折扣叠加遵循严格的优先级链。 商品折扣 → 购物车折扣 → 折扣码 → 直接折扣。购物车上的直接折扣会阻止使用所有折扣码。切勿在同一购物车上混用直接折扣和折扣码流程。

sortOrder 方向：数值越大，越先生效。 对于商品折扣和购物车折扣，sortOrder 数值最高（最接近 1）的折扣会先应用。0.9 先于 0.5 生效。商品折扣仅应用一个（不叠加）；购物车折扣默认会叠加，除非设置了 stackingMode: StopAfterThisDiscount。

商品折扣不能用于外部定价。 如果项目使用外部价格源，则不会应用商品折扣。启用外部定价时，请使用购物车折扣提供任何促销折扣。

折扣组可将多个购物车折扣归入同一实体。 折扣组有自己的 sortOrder 和 "Best deal" 优先模式 — 仅应用该组中能为客户带来最大优惠的购物车折扣。使用折扣组管理大型活动（例如黑色星期五），避免因一次停用数十个单独折扣而出错。 客户组定价设置在嵌入式价格上，而不是客户级别。 购物者所属的客户组会在购物车计算时解析——系统会选取变体上 customerGroup 匹配的价格。一个客户可以拥有多个客户组（通过 customerGroupAssignments，最多 500 个），系统会从所有已分配的客户组中选取符合条件的最佳价格。对于 B2B 购物者，可直接将客户组分配给购物者的客户记录，也可通过业务单元分配。

购物车评分是动态运费的关键。 在 Merchant Center 中将项目的运费输入类型设置为“Cart Score”。调用 setShippingRateInput，传入 Score 类型和整数评分。CT 会查找与该评分匹配的运费档位。评分必须是非负整数。

购物车评分不能用于运费谓词——请将其复制到购物车自定义字段。 score 不能直接在谓词中查询。将基础值（例如，以 km 为单位的距离）写入购物车自定义字段，并针对该自定义字段编写运费谓词。

价格函数可将购物车评分转换为连续费率。 配置 priceFunction（例如 (x / 30)），其中 x 为购物车评分。CT 会计算函数，并将结果金额设为运费，从而实现平滑缩放的费率，无需枚举所有可能的值。

对于大多数 PSP/税务服务集成，请使用 taxMode: ExternalAmount。 此模式允许税务服务计算每个订单项的精确税额，并将其直接传给 CT，从而消除 CT 引擎与外部税务服务（AvaTax、Vertex）之间的舍入差异。

CT 记录支付状态；PSP 执行实际的金融交易。 Payment 对象是一个账本。使用 addTransaction 更新操作跟踪每个 PSP 事件（授权、扣款、退款、拒付）。只有在 PSP 确认成功后，才设置 state: "Success"。

Payment 上的 interfaceId 一经设置便不可更改。 此字段将 CT Payment 与 PSP 的标识符关联起来。首次记录时务必确保正确——之后无法更新。

购物车价格会在创建订单时快照保存。 如果产品价格在创建购物车和创建订单之间发生变化，购物车仍保留旧价格。结账前请对购物车使用 recalculate 操作来刷新价格。

业务单元是 B2B 的核心实体——所有 B2B 操作都通过业务单元执行。 所有 B2B 操作都使用 as-associate API 调用链（构造方式和作用域见 references/as-associate-api.md）。面向 B2B 用户的操作绝不要使用项目级购物车/订单 API。

报价生命周期包含四个实体：QuoteRequest → StagedQuote → Quote → Order。 购物者创建 QuoteRequest；销售代表创建 StagedQuote（包含协商价格的工作草稿）；Quote 是最终报价；如果购物者接受，则将其转换为 Order。每一步都有各自的状态机。

POST /orders 与 POST /recurring-orders 会产生本质不同的结果。 对包含定期订购订单项的购物车调用 POST /orders，会同时创建常规订单（立即生效）和定期订购订单。调用 POST /recurring-orders 则只会创建定期订购订单。“订阅并立即发货”流程使用 /orders；未来日期生效的订阅使用 /recurring-orders。

购物车折扣的 recurringOrderScope 用于控制折扣是否重复生效。 一次性欢迎优惠请设为 "NonRecurringOrdersOnly"。每个续订周期都应生效的长期忠诚度折扣请设为 "AnyOrder"。

---

参考索引

定价与促销

主题	参考
折扣叠加规则、sortOrder、直接折扣对折扣码的阻止	references/discount-fundamentals.md
买赠购物车折扣 — triggerPattern、targetPattern、excludeCount	references/bundle-discounting.md
购物车折扣场景指南 — 12 个命名场景及完整 JSON	references/cart-discount-scenarios.md
固定价格组合折扣 — 购买 N 个 X+Y，享受固定组合价格	references/fixed-price-combo.md
“从一组商品中任选 N 件，总价固定”（无触发商品），以及通过 maxOccurrence 设置每个购物车的触发次数上限	references/cart-discount-scenarios.md
基于客户组的定价 — 内嵌价格选择、组分配	references/customer-group-pricing.md
B2B 客户组定价 — 通过客户组设置买家专属定价	references/b2b-customer-group-pricing.md
高精度金额 — fractionDigits、货币配置、舍入	references/high-precision-money.md
折扣组与促销优先级 — 最优优惠选择	references/discount-groups.md
商店储值与忠诚度货币 — 外部账本模式	references/store-credit.md
限时定价 — 内嵌价格中的 validFrom/validUntil	references/limited-time-pricing.md
折扣码使用 — 代码生成、兑换限制	references/discount-code-usage.md

配送与履约

主题	参考
分级费率、购物车评分设置、ScoreShippingRateInput	references/tiered-rates-cart-score.md
配送谓词 — 谓词语法、自定义字段解决方法	references/shipping-predicates.md
价格函数 — priceFunction 配置、函数语法	references/price-functions.md
动态配送费用 — 外部计算、setCustomShippingMethod	references/dynamic-shipping-costs.md
BOPIS 配送 — 多种配送方式、配送组设置	references/bopis-shipping.md

支付与税费

主题	参考
支付 — Payment 对象模型、交易、PSP 集成流程	references/payments.md
税费 — 购物车税费模式（Platform/External/ExternalAmount/Disabled）	references/taxes.md
融资与分期付款 — BNPL 集成、CT 支付建模	references/financing-options.md

B2B 订单流程

主题	参考
自定义关联人角色 — 角色定义、权限键、分配给 BU	references/custom-associate-roles.md
Business Unit 层级结构 — 父级/子级 BU、继承的角色、商店分配	references/business-unit-hierarchy.md
审批规则 — 谓词设计、审批流程生命周期	references/approval-rules.md
报价生命周期 — QuoteRequest、StagedQuote、Quote、订单转换	references/quote-lifecycle.md
as-associate API 模式 — 链构造、作用域	references/as-associate-api.md

定期订单

主题	参考
定期订单 — RecurrencePolicy、priceSelectionMode、/orders 与 /recurring-orders	references/recurring-orders.md

商品目录与导入

主题	参考
商品数据建模 — 层级结构、全部 14 种属性类型、Nested 与 Custom Object
套装商品建模 — ProductType 设计、子 SKU 引用、BFF 编排	references/bundle-modeling.md
导入 API — 容器、批处理、异步处理、增量导入
导入 API 性能 — 1500 万条记录模式、容器数量、批次大小
商品替代品 — 替代／更换商品建模	references/item-substitutes.md
库存建模 — 供应渠道、库存条目、缺货后订购

---

优先级

严重

• 直接折扣会阻止折扣码生效。 如果结账流程预期用户输入折扣码，切勿向购物车添加直接折扣。
• sortOrder：值越大，越先生效 — 商品折扣和购物车折扣均如此。0.9 会先于 0.5 应用。这是一个常见误解，会导致促销行为不正确。
• 商品折扣不适用于外部定价。 如果项目使用外部价格来源，请将所有促销折扣改为购物车折扣。
• triggerPattern SKU 谓词会对各条目进行 AND 运算。 单个 CountOnLineItemUnits 条目只能匹配一个 SKU — 请为每个套装组件分别添加条目。
• 必须在查询运费之前设置 Score。 必须在结账之前、计算运费总额之前调用 setShippingRateInput。在创建订单后调用不会产生任何效果。
• 运费谓词失败时不会显示错误。 如果存在谓词语法错误，CT 可能会静默地返回无可用方式或所有方式。请务必使用 GET /shipping-methods?cartId=<id> 显式测试谓词行为。
• 所有 B2B 写入都必须使用 as-associate API 调用链。 项目级 apiRoot.carts().* 不会强制实施 B2B 权限。这是安全要求，而非单纯的约定。
• Associate 必须拥有 CreateMyCarts 权限，才能以 as-associate 身份向购物车添加商品。 缺少此权限会导致 403 错误。
• POST /orders 会根据混合购物车同时创建常规订单和定期订单。 设计订单确认流程时，要能够处理多个订单 ID。
• RecurrencePolicy 在使用期间无法删除。 尝试删除之前，请移除所有行项目和购物车引用。
• PSP 确认之前，切勿将 Payment 交易设为 Success。 乐观地标记成功会导致对账失败。
• Payment 的 interfaceId 一旦设置就无法更改。 首次写入时，请正确记录 PSP 交易标识符。
• 导入 API 不保证处理顺序。 提交第二个操作之前，请先轮询第一个操作的状态。
• productDraftImport 具有破坏性。 草稿中未包含的任何字段都会被删除。
• 版本冲突（409 ConcurrentModification）要求使用最新版本重试。 请勿使用失败请求中的版本。

高优先级

• 客户组定价要求客户已登录且设置了 customerGroup。 匿名购物车使用默认价格。
• 购物车中的所有价格必须统一使用 HighPrecisionMoney。 在同一购物车/订单中混用 centPrecision 和 highPrecision 价格会导致计算错误。
• 折扣代码的 maxApplications 对所有客户全局生效。 如需设置单个客户的限制，请使用 maxApplicationsPerCustomer——两者是独立字段。
• 配送谓词中无法使用 Cart Score。 在编写相关谓词之前，请将距离或重量值复制到购物车自定义字段。
• 针对仓库的谓词需要在购物车自定义字段中包含仓库键。 无法直接在配送谓词中查询购物车分配的供应渠道。
• StagedQuotes 保存协商后的行项目价格。 将 StagedQuote 转换为 Quote 时，StagedQuote 中的价格会被锁定。
• 审批规则在创建订单时评估，而非创建购物车时。 设计购物车转订单的用户体验时，应让买家了解审批等待时间。
• 必须根据具体用例有意设置 priceSelectionMode。 "Fixed" 可保证价格；"Dynamic" 始终采用当前目录定价。
• 购物车折扣的 recurringOrderScope 默认适用于所有订单。 对于首购优惠，请明确设置为 "NonRecurringOrdersOnly"。
• 嵌套属性无法搜索，也无法用于折扣谓词。 任何需要出现在搜索筛选条件或谓词中的属性，都应使用扁平属性类型。
• Import API 每个请求最多支持 20 个操作。 请务必分批处理。
• 数据创建后更改 ProductType 属性约束需要迁移。 请在初始设计阶段规划属性约束。

中优先级

• Cart Discount 上的 isActive 是软开关。 与其创建/删除折扣，不如用它安排营销活动。
• 使用 stackingMode: StopAfterThisDiscount 可让特定折扣具有排他性。购物车折扣默认会叠加。
• 价格舍入可通过 priceRoundingMode 配置（适用于 Cart/Order/Quote，也可设为 Project 默认值）。模式包括：HalfEven（银行家舍入——默认值）、HalfUp、HalfDown。只有 HalfDown 会将 .5 向有利于客户的方向舍入；请让舍入模式与 ERP/税务系统保持一致，并在高销量营销活动中相应考虑预算利润空间。
• 对于不支持的折扣场景，常用模式是在购物车/订单上使用 API Extension，计算并注入 Direct Discount 或自定义行项目。
• lineItemGrossTotal(categories.key = (...)) >= "X.XX USD" 是按类别消费金额设置门槛的常用模式。 值中必须包含货币字符串。
• 价格函数在费率查询时于服务端评估。 不要尝试在前端复现该函数。
• Quote 协商支持多轮。 如果业务需要记录协商轮次，请通过 QuoteRequest 上的自定义字段进行跟踪。
• 在买家的客户记录上分配客户组，是最简单的 B2B 定价模式。 他们的所有购物车都会自动继承该组的定价。
• 订单确认用户体验必须支持多个订单 ID。 如果单次购物车结账包含频率不同的定期商品，将生成 N+1 个订单。
• 通过 Import API 创建的独立价格支持 validFrom/validUntil，无需重新发布产品即可设置限时定价。