用途
Variant Selection 是 Saleor Storefront 中用于商品详情页（PDP）的变体与属性选择系统。它适用于以下场景：修改商品页上的变体/属性选择器、理解某个变体为何不可选、为变体选项添加折扣标识、调试“加入购物车”按钮状态。
核心概念
加入购物车的是变体（Variant），而不是商品（Product）。每个变体是特定属性的组合。例如，T 恤商品可以有“黑色 + 中码”“黑色 + 大码”“白色 + 中码”等多个变体，每个变体有独立的 variantId。checkoutLinesAdd mutation 需要具体的 variantId；如果没有选择全部属性，就没有可添加的变体。
两类变体属性
Saleor 区分两种变体属性：
- 选择型（variantSelection 为 VARIANT_SELECTION）：用于识别具体变体，如颜色、尺寸，呈现为交互式选择器。
- 非选择型（variantSelection 为 NOT_VARIANT_SELECTION）：用于描述变体，如材质、品牌，仅作展示徽章，不是交互式选择器。
关键点：两类属性都不会“传递”给结账流程，只需传递 variantId。所有属性已存储在 Saleor 的变体上。GraphQL 查询使用 variantSelection 过滤器区分二者。
文件结构
src/ui/components/pdp/variant-selection/ 目录包含：index.ts（公共导出）、types.ts（TypeScript 接口）、utils.ts（数据转换与逻辑）、variant-selector.tsx（单属性选择器）、variant-selection-section.tsx（主容器）、optional-attributes.tsx（非选择型属性徽章），以及 renderers/ 下的 color-swatch-option.tsx（圆形色板）和 button-option.tsx（尺寸/文本按钮）。
utils.ts 中的关键函数
groupVariantsByAttributes() 从变体中提取唯一属性值；findMatchingVariant() 查找匹配所有已选属性的变体；getOptionsForAttribute() 获取带可用性/兼容性信息的选项；getAdjustedSelections() 在需要时清除冲突选择；getUnavailableAttributeInfo() 检测死胡同选择。
选项状态
选项有三种状态：可用（有库存，正常显示，可点击）、不兼容（当前选择下无匹配变体，变暗，可点击并清除其他选择）、缺货（变体存在但数量为 0，删除线，不可点击）。
URL 参数模式
选择状态存储在 URL 参数中，例如 ?color=black&size=m&variant=abc123。variant 参数仅在全部属性选择完成后自动设置。
折扣徽章
选项可显示折扣百分比。VariantOption 接口包含 hasDiscount 和 discountPercent 字段，渲染器在设置了 discountPercent 时显示小徽章。
状态机
选择系统有 5 种状态并自动解决冲突：空（无选择，不可加入购物车）、部分（部分属性已选，不可加入购物车）、完成（全部已选且找到变体，可加入购物车）、冲突（自动清除为部分状态）、死胡同（选择阻塞其他组，不可加入购物车）。关键行为：当用户选择不兼容选项时，其他选择会被自动清除而非阻止，用户始终可以探索所有选项。
反模式
不要在未完成全部选择时启用“加入购物车”（需要 variantId）；不要阻止不兼容选项（让用户点击并清除其他选择）；不要假设只有单个属性（商品可有多个属性）；不要在价格布尔检查中使用 0（应使用 typeof === "number"）；不要让非选择型属性变为交互式（它们仅作展示徽章）。