Skip to main content

​
概览

外卖商品的定制分为三层：

​
Specs — 规格

每个商品可能有一个或多个规格维度：
选择不同规格会改变 item_id 和 sku_id。下单时传入对应规格的 ID 即可。

​
Attrs — 属性

不影响价格的定制选项：

​
Ingredients — 加料

加料按规格（SKU）区分。 同一商品不同规格（如不同杯型）可选的加料及其内部标识可能不同——例如某商品「超大杯」只能「冰」、「特大杯」只能「热」。get_shop_menu 顶层 ingredient_options 是默认规格的加料；选其他规格时请用该规格 sku_options[].ingredient_options 里的 option_id（见 菜单接口）。沿用默认规格的 option_id 下其他规格时，网关按「组名 + 选项名」自动映射；该规格不存在的加料在 quote_cart / preview_order 阶段即报错。
最复杂的定制层，包含互斥规则：

​
互斥规则

每个选项的 excludes 数组列出了与它不兼容的选项 ID：
ID 格式为 ig_{组索引}_{选项索引}，稳定且可预测。
互斥规则是单向的：A 排除 B 不意味着 B 排除 A。需要逐一检查每个选中选项的排除列表。

​
典型场景

星巴克链式排除：
互斥选择：

​
Default Ingredients — 默认选择

为方便 AI Agent 快速下单，菜单返回了预计算的 default_ingredients：
这是系统自动选择每个必选组的第一个非互斥选项后的结果。Agent 可以直接将此字段传入下单接口，无需理解互斥逻辑。
对于大多数下单场景，直接使用 default_ingredients 是最简单的方式。只有用户明确要求定制时才需要手动选择。

​
两层「必选组」

「必选」在菜单里有两个不同层次，别混：
  • 商品内·配料必选组：某商品内部必须选够做法，如奶茶必选「温度」「糖度」。落在该商品的 ingredient_options（上游 isRequired 组）。漏选会在下单时被上游判「配料未选齐」。
  • 店铺级·必选商品组：整单必须再点一个某类商品，如麻辣烫的「必选好汤」汤底。落在 get_shop_menu 响应顶层的 required_groups[]（及 categories[].required），需从 candidate_item_ids 选商品加入 items[]。
两者判定时机不同：店铺级必选组由网关在 quote_cart（can_checkout=false + blocking_reason 软提示）和 preview_order（MISSING_REQUIRED_SELECTION，HTTP 400 硬拦）拦截；商品内配料必选组则在下单时由上游校验。

​
回显已选规格

get_shop_menu 返回的是可选项；而 quote_cart（算价）与 preview_order（预览）会在每个商品上回显用户已选的规格与配料，便于向用户展示「点了什么」： 回显按每个商品各自的 sku_id / ingredient_option_ids 翻译，多商品（含同款不同规格）互不串味；无规格 / 配料时对应字段为 []。