@xfe-repo/web-components 1.6.1 → 1.7.0

package/skills/references/EffectSkuSelect.md

@@ -0,0 +1,251 @@
+# EffectSkuSelect
+
+> SKU 下拉选择器，级联链末端组件，支持按分类、品牌、系列、SPU 多级过滤，带图片预览和无限滚动加载，数据通过 `apiService.skuListV2` 自动获取。
+
+## 导入
+
+```tsx
+import { EffectSkuSelect } from '@xfe-repo/web-components'
+import type { ValueType, ItemOption } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+最常见用法 — 在 Form.Item 中使用，value/onChange 由 Form 自动注入：
+
+```tsx
+<Form.Item name="skuId" label="SKU">
+  <EffectSkuSelect categoryId={categoryId} brandId={brandId} />
+</Form.Item>
+```
+
+### 独立受控模式
+
+```tsx
+import { EffectSkuSelect } from '@xfe-repo/web-components'
+
+function MyForm() {
+  const [skuId, setSkuId] = useState<number>()
+
+  return <EffectSkuSelect value={skuId} onChange={(value) => setSkuId(value)} />
+}
+```
+
+## 进阶用法
+
+### 完整级联过滤（分类 → 品牌 → 系列 → SPU → SKU）
+
+```tsx
+const [categoryId, setCategoryId] = useState<number>()
+const [brandId, setBrandId] = useState<number>()
+const [seriesId, setSeriesId] = useState<number>()
+const [spuId, setSpuId] = useState<number>()
+const [skuId, setSkuId] = useState<number>()
+
+<EffectSkuSelect
+  categoryId={categoryId}
+  brandId={brandId}
+  seriesId={seriesId}
+  spuId={spuId}
+  value={skuId}
+  onChange={(value, skuData) => {
+    setSkuId(value)
+    // skuData 包含完整的 SKU 信息（ListSkuV2 类型）
+    console.log('SKU数据：', skuData)
+  }}
+/>
+```
+
+### 显示 SKU ID 信息
+
+开启后选项标签格式为 `skuId | ahsSkuId | skuName`：
+
+```tsx
+<EffectSkuSelect showSkuId value={skuId} onChange={(value, skuData) => setSkuId(value)} />
+```
+
+### 按上架状态和 SKU 类型筛选
+
+```tsx
+<EffectSkuSelect
+  shelfStatus={1} // 1-上架，2-下架，3-包含所有
+  skuType="std" // 'std'-标准SKU，'tmp'-临时SKU
+  value={skuId}
+  onChange={(value) => setSkuId(value)}
+/>
+```
+
+### 级联 categoryId 提取
+
+EffectCategoryCascade 返回数组，需取末位传给 EffectSkuSelect：
+
+```tsx
+const categoryIds = Form.useWatch('categoryIds', form)
+const categoryId = categoryIds?.[categoryIds.length - 1]
+
+<Form.Item name="skuId" label="SKU">
+  <EffectSkuSelect categoryId={categoryId} brandId={brandId} key={`${categoryId}-${brandId}`} />
+</Form.Item>
+```
+
+## 使用提示
+
+> 💡 常见校验：`<Form.Item name="skuId" label="SKU" rules={[{ required: true, message: '请选择SKU' }]}>`
+
+## Props
+
+```typescript
+type ConditionsType = { categoryId?: number; brandId?: number; seriesId?: number; spuId?: number }
+
+type Props = ConditionsType & {
+  className?: string
+  onChange?: (value?: number, data?: ListSkuV2) => void
+  defaultValue?: number | string
+  disabled?: boolean
+  value?: number
+  /** 上架状态: 1-上架，2-下架，3-包含所有（不传则由后端决定默认行为） */
+  shelfStatus?: number
+  showSkuId?: boolean
+  skuType?: 'std' | 'tmp'
+}
+```
+
+| 属性         | 类型                                         | 必填 | 默认值  | 说明                                                            |
+| ------------ | -------------------------------------------- | ---- | ------- | --------------------------------------------------------------- |
+| value        | `number`                                     | 否   | -       | 受控值（SKU ID）                                                |
+| defaultValue | `number \| string`                           | 否   | -       | 默认值                                                          |
+| onChange     | `(value?: number, data?: ListSkuV2) => void` | 否   | -       | 值变化回调，第二个参数为完整 SKU 数据                           |
+| categoryId   | `number`                                     | 否   | -       | 分类 ID，变更时自动重新加载并清空选中值                         |
+| brandId      | `number`                                     | 否   | -       | 品牌 ID，变更时自动重新加载并清空选中值                         |
+| seriesId     | `number`                                     | 否   | -       | 系列 ID，变更时自动重新加载并清空选中值                         |
+| spuId        | `number`                                     | 否   | -       | SPU ID，变更时自动重新加载并清空选中值                          |
+| shelfStatus  | `number`                                     | 否   | -       | 上架状态：1-上架，2-下架，3-包含所有                            |
+| showSkuId    | `boolean`                                    | 否   | `false` | 是否在选项中显示 SKU ID（格式：`skuId \| ahsSkuId \| skuName`） |
+| skuType      | `'std' \| 'tmp'`                             | 否   | `'std'` | SKU 类型：标准/临时                                             |
+| disabled     | `boolean`                                    | 否   | -       | 禁用状态                                                        |
+| className    | `string`                                     | 否   | -       | 自定义样式类名                                                  |
+
+## 导出类型
+
+```typescript
+// 选项值类型
+export type ValueType = string | number | undefined
+
+// 选项数据结构
+export type ItemOption = { label: string; value: number; image: string }
+
+// 图片预览组件的 Props
+export type ImageItemProps<O extends ItemOption = ItemOption> = {
+  item: O
+  previewed: boolean
+  onPreview: (item?: O) => void
+  className?: string
+}
+```
+
+> **注意**：`ValueType`、`ItemOption`、`SelectDropdown`、`ImageItem`、`getNumberValue` 均从本文件导出，`EffectSeriesSelect` 和 `EffectSpuSelect` 内部会从 `EffectSkuSelect` 导入使用，但不会再次导出。如需使用这些类型，请始终从 `EffectSkuSelect` 导入。
+
+## API 数据源
+
+- **内部 Hook**：`useSkuOptions`（使用 SWR 缓存）
+- **内部接口**：`apiService.skuListV2`
+- **请求参数**：`{ categoryId, brandId, seriesId, spuId, id, skuName, type, status, page, pageSize }`
+- **可覆盖**：通过 `<ConfigProvider apiService={{ skuListV2: customFn }}>` 替换默认实现
+
+## 依赖 Props
+
+| 依赖属性   | 类型     | 来源                         | 说明                 |
+| ---------- | -------- | ---------------------------- | -------------------- |
+| categoryId | `number` | EffectCategoryCascade 的输出 | 按分类过滤 SKU 列表  |
+| brandId    | `number` | EffectBrandSelect 的输出     | 按品牌过滤 SKU 列表  |
+| seriesId   | `number` | EffectSeriesSelect 的输出    | 按系列过滤 SKU 列表  |
+| spuId      | `number` | EffectSpuSelect 的输出       | 按 SPU 过滤 SKU 列表 |
+
+### 联动示例
+
+```tsx
+import { useState } from 'react'
+import {
+  EffectCategoryCascade,
+  EffectBrandSelect,
+  EffectSeriesSelect,
+  EffectSpuSelect,
+  EffectSkuSelect,
+  isSingleTreeSelected,
+} from '@xfe-repo/web-components'
+
+function FullCascadeFilter() {
+  const [categoryId, setCategoryId] = useState<number>()
+  const [brandId, setBrandId] = useState<number>()
+  const [seriesId, setSeriesId] = useState<number>()
+  const [spuId, setSpuId] = useState<number>()
+  const [skuId, setSkuId] = useState<number>()
+
+  return (
+    <div>
+      <EffectCategoryCascade
+        onChange={(values, selectedList) => {
+          if (selectedList && isSingleTreeSelected(selectedList)) {
+            setCategoryId(Number(selectedList[selectedList.length - 1].value))
+          } else {
+            setCategoryId(undefined)
+          }
+        }}
+      />
+      <EffectBrandSelect categoryId={categoryId} value={brandId} onChange={(value) => setBrandId(value as number)} />
+      <EffectSeriesSelect categoryId={categoryId} brandId={brandId} value={seriesId} onChange={(value) => setSeriesId(value)} />
+      <EffectSpuSelect categoryId={categoryId} brandId={brandId} seriesId={seriesId} value={spuId} onChange={(value) => setSpuId(value)} />
+      <EffectSkuSelect
+        categoryId={categoryId}
+        brandId={brandId}
+        seriesId={seriesId}
+        spuId={spuId}
+        value={skuId}
+        onChange={(value, skuData) => {
+          setSkuId(value)
+          console.log('完整SKU数据：', skuData)
+        }}
+      />
+    </div>
+  )
+}
+```
+
+## 子组件
+
+EffectSkuSelect 同时导出了供 EffectSeriesSelect 和 EffectSpuSelect 内部复用的子组件：
+
+| 子组件           | 说明                                   |
+| ---------------- | -------------------------------------- |
+| `SelectDropdown` | 自定义下拉面板，支持图片预览和无限滚动 |
+| `ImageItem`      | 选项中的图片展示组件，支持预览         |
+| `getNumberValue` | 将 ValueType 转为 number 的工具函数    |
+
+## 常见陷阱
+
+- ❌ 不传任何上游条件，期望获取所有 SKU——组件会请求全量数据，可能导致性能问题：
+  ```tsx
+  <EffectSkuSelect onChange={(v) => setSkuId(v)} />
+  ```
+- ✅ 至少传入一个上游过滤条件缩小范围：
+
+  ```tsx
+  <EffectSkuSelect categoryId={categoryId} onChange={(v) => setSkuId(v)} />
+  ```
+
+- ❌ 混淆 `shelfStatus` 值——不传不等于默认上架
+- ✅ 需要只显示上架商品时显式传 `shelfStatus={1}`
+
+- ❌ 忽略 `onChange` 第二个参数 `data` 中的完整信息——`ListSkuV2` 包含 skuName、skuImage、ahsSkuId 等
+- ✅ 需要详情时保存完整 `data` 对象
+
+## 相关组件
+
+| 场景     | 组件                    | 说明                               |
+| -------- | ----------------------- | ---------------------------------- |
+| 级联上游 | `EffectCategoryCascade` | 提供 categoryId                    |
+| 级联上游 | `EffectBrandSelect`     | 提供 brandId                       |
+| 级联上游 | `EffectSeriesSelect`    | 提供 seriesId                      |
+| 级联上游 | `EffectSpuSelect`       | 提供 spuId                         |
+| 聚合使用 | `EffectScopeSelect`     | 内部已集成本组件，无需单独使用     |
+| API 配置 | `ConfigProvider`        | 提供 apiService.skuListV2 接口实现 |

package/skills/references/EffectSkuTable.md

@@ -0,0 +1,184 @@
+# EffectSkuTable
+
+> SKU 联动选择表格，以表格形式展示分类 → 品牌 → 系列 → SPU → SKU 的五级级联选择器，每列为一个独立的 Effect 组件。
+
+## 导入
+
+```tsx
+import { EffectSkuTable } from '@xfe-repo/web-components'
+import type { EffectSkuTableProps } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+```tsx
+import { EffectSkuTable } from '@xfe-repo/web-components'
+
+function SkuPicker() {
+  const [skuId, setSkuId] = useState<number>()
+
+  return (
+    <EffectSkuTable
+      categoryIds={[]}
+      onChange={(skuId, skuData) => {
+        setSkuId(skuId)
+        console.log('SKU 数据：', skuData)
+      }}
+    />
+  )
+}
+```
+
+## 进阶用法
+
+### 预设品牌和分类
+
+```tsx
+<EffectSkuTable categoryIds={[1, 2, 3]} brandId={100} brandName="Nike" onChange={(skuId, skuData) => setSkuId(skuId)} />
+```
+
+### 通过 SKU ID 回显
+
+传入 `value` 时组件会自动调用 `skuFindOne` 接口查询完整数据并填充各级选择器：
+
+```tsx
+<EffectSkuTable categoryIds={[]} value={12345} onChange={(skuId, skuData) => console.log(skuData)} />
+```
+
+### 隐藏分类列
+
+当 `categoryIds` 不为数组类型时（传入单个 number），分类列不显示：
+
+```tsx
+<EffectSkuTable categoryIds={100} onChange={(skuId, skuData) => setSkuId(skuId)} />
+```
+
+### 显示 SKU ID 和选择临时 SKU
+
+```tsx
+<EffectSkuTable categoryIds={[]} showSkuId skuType="tmp" onChange={(skuId, skuData) => setSkuId(skuId)} />
+```
+
+## Props
+
+```typescript
+export interface EffectSkuTableProps {
+  /** number[]: 各级分类Id数组，number: 最后一级分类Id */
+  categoryIds?: number[] | number
+  brandId?: number
+  brandName?: string
+  seriesId?: number
+  seriesName?: string
+  spuId?: number
+  spuName?: string
+  disabled?: boolean
+  value?: number
+  showSkuId?: boolean
+  skuType?: 'std' | 'tmp'
+  onChange?: (value?: number, skuData?: ListSkuV2) => void
+}
+```
+
+| 属性        | 类型                         | 必填 | 默认值  | 说明                                            |
+| ----------- | ---------------------------- | ---- | ------- | ----------------------------------------------- |
+| categoryIds | `number[] \| number`         | 否   | -       | 分类 ID。传数组时显示分类列，传数字时隐藏分类列 |
+| brandId     | `number`                     | 否   | -       | 预设品牌 ID                                     |
+| brandName   | `string`                     | 否   | -       | 预设品牌名称                                    |
+| seriesId    | `number`                     | 否   | `0`     | 预设系列 ID                                     |
+| seriesName  | `string`                     | 否   | -       | 预设系列名称                                    |
+| spuId       | `number`                     | 否   | -       | 预设 SPU ID                                     |
+| spuName     | `string`                     | 否   | -       | 预设 SPU 名称                                   |
+| value       | `number`                     | 否   | -       | 受控 SKU ID，传入时自动反查填充各级选择器       |
+| onChange    | `(value?, skuData?) => void` | 否   | -       | 值变化回调（见下方说明）                        |
+| disabled    | `boolean`                    | 否   | -       | 禁用所有选择器                                  |
+| showSkuId   | `boolean`                    | 否   | `false` | 是否在 SKU 选择器中显示 SKU ID                  |
+| skuType     | `'std' \| 'tmp'`             | 否   | `'std'` | SKU 类型，`'std'` 标准 / `'tmp'` 临时           |
+
+### onChange 回调说明
+
+`onChange` 在不同操作阶段返回不同的数据：
+
+- **选中 SKU 时**：`onChange(skuId, { skuId, categoryId, brandId, seriesId, spuId, skuName, brandName, ... })`
+- **变更上游选择器时**（如品牌变更）：`onChange(undefined, { categoryId, brandId, seriesId, ... })`（部分字段）
+- **通过 value 反查成功时**：`onChange(value, { 完整 SKU 数据 })`
+
+## 导出类型
+
+```typescript
+export interface EffectSkuTableProps { ... }
+
+// ListSkuV2 来自 @api/product
+// 包含: skuId, skuName, categoryId, categoryName, brandId, brandName,
+//       seriesId, seriesName, spuId, spuName, image, skuImage 等
+```
+
+## API 数据源
+
+- **SKU 反查接口**：`apiService.skuFindOne`（传入 `value` 时使用）
+- **请求参数**：`{ id: skuId }`
+- **内部组件各自的接口**：各级选择器使用各自的 API（见相关组件）
+
+## 子组件
+
+组件内部以 Table Column 形式渲染以下子组件：
+
+| 列      | 子组件                  | 说明                                 |
+| ------- | ----------------------- | ------------------------------------ |
+| 分类    | `EffectCategoryCascade` | 仅 `categoryIds` 为数组时显示        |
+| 品牌    | `EffectBrandSelect`     | 依赖 categoryId                      |
+| 系列    | `EffectSeriesSelect`    | 依赖 categoryId + brandId            |
+| SPU     | `EffectSpuSelect`       | 依赖 categoryId + brandId + seriesId |
+| SKU     | `EffectSkuSelect`       | 依赖以上所有 + spuId                 |
+| SKU图片 | `OSSImage`              | 显示选中 SKU 的缩略图                |
+
+## 常见陷阱
+
+- ❌ 不传 `categoryIds` 而期望分类列显示：
+  ```tsx
+  // 只有传入 number[] 类型时分类列才会渲染
+  ```
+- ✅ 传入空数组 `[]` 来显示空的分类选择器：
+
+  ```tsx
+  <EffectSkuTable categoryIds={[]} />
+  ```
+
+- ❌ 期望 `onChange` 的第二个参数始终包含完整的 SKU 数据：
+  ```tsx
+  // 变更上游选择器（如品牌、系列）时，skuData 只包含已选择的部分字段
+  // value 为 undefined 表示 SKU 尚未确定
+  ```
+- ✅ 根据 `value` 是否有值判断 SKU 是否已选中：
+
+  ```tsx
+  <EffectSkuTable
+    categoryIds={[]}
+    onChange={(value, skuData) => {
+      if (value) {
+        // SKU 已选中，skuData 包含完整数据
+      } else {
+        // 上游变更，SKU 被清空，skuData 只含部分信息
+      }
+    }}
+  />
+  ```
+
+- ❌ 传入 `value` 后立即读取 state：
+  ```tsx
+  // value 反查是异步的，需要等 onChange 回调触发
+  ```
+- ✅ 在 `onChange` 回调中获取反查结果
+
+- ⚠️ 已知问题：组件受控逻辑存在 bug，业务代码通过 `key={reloadKey}` 强制重新挂载来绕过。如遇数据不刷新，可尝试此方法。
+
+## 相关组件
+
+| 场景          | 组件                    | 说明                                  |
+| ------------- | ----------------------- | ------------------------------------- |
+| 图片识别选择  | `EffectSkuRecognize`    | 基于图片智能识别 SKU                  |
+| 单独 SKU 搜索 | `EffectSkuSelect`       | SKU 下拉搜索选择器                    |
+| 品牌选择      | `EffectBrandSelect`     | 内部使用的品牌选择器                  |
+| 分类选择      | `EffectCategoryCascade` | 内部使用的分类级联选择器              |
+| 系列选择      | `EffectSeriesSelect`    | 内部使用的系列选择器                  |
+| SPU 选择      | `EffectSpuSelect`       | 内部使用的 SPU 选择器                 |
+| API 配置      | `ConfigProvider`        | 提供 `apiService.skuFindOne` 接口实现 |

package/skills/references/EffectSpuSelect.md

@@ -0,0 +1,189 @@
+# EffectSpuSelect
+
+> SPU 下拉选择器，支持按分类、品牌、系列过滤和上架状态筛选，带图片预览和无限滚动加载，数据通过 `apiService.spuList` 自动获取。
+
+## 导入
+
+```tsx
+import { EffectSpuSelect } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+```tsx
+import { EffectSpuSelect } from '@xfe-repo/web-components'
+
+function MyForm() {
+  const [spuId, setSpuId] = useState<number>()
+
+  return <EffectSpuSelect value={spuId} onChange={(value) => setSpuId(value)} />
+}
+```
+
+## 进阶用法
+
+### 完整级联过滤
+
+```tsx
+const [categoryId, setCategoryId] = useState<number>()
+const [brandId, setBrandId] = useState<number>()
+const [seriesId, setSeriesId] = useState<number>()
+const [spuId, setSpuId] = useState<number>()
+
+<EffectCategoryCascade onChange={handleCategoryChange} />
+<EffectBrandSelect categoryId={categoryId} value={brandId} onChange={(v) => setBrandId(v as number)} />
+<EffectSeriesSelect categoryId={categoryId} brandId={brandId} value={seriesId} onChange={(v) => setSeriesId(v)} />
+<EffectSpuSelect
+  categoryId={categoryId}
+  brandId={brandId}
+  seriesId={seriesId}
+  value={spuId}
+  onChange={(value, spuData) => {
+    setSpuId(value)
+    // spuData 包含完整的 SPU 信息（SpuItem 类型）
+    console.log('SPU数据：', spuData)
+  }}
+/>
+```
+
+### 按上架状态筛选
+
+```tsx
+<EffectSpuSelect
+  shelfStatus={1} // 1-上架
+  value={spuId}
+  onChange={(value) => setSpuId(value)}
+/>
+```
+
+## Props
+
+```typescript
+type ConditionsType = { categoryId?: number; brandId?: number; seriesId?: number }
+
+type Props = ConditionsType & {
+  className?: string
+  onChange?: (value?: number, spuData?: SpuItem) => void
+  defaultValue?: string
+  disabled?: boolean
+  value?: number
+  shelfStatus?: number
+}
+```
+
+| 属性         | 类型                                          | 必填 | 默认值 | 说明                                    |
+| ------------ | --------------------------------------------- | ---- | ------ | --------------------------------------- |
+| value        | `number`                                      | 否   | -      | 受控值（SPU ID）                        |
+| defaultValue | `string`                                      | 否   | -      | 默认值                                  |
+| onChange     | `(value?: number, spuData?: SpuItem) => void` | 否   | -      | 值变化回调，第二个参数为完整 SPU 数据   |
+| categoryId   | `number`                                      | 否   | -      | 分类 ID，变更时自动重新加载并清空选中值 |
+| brandId      | `number`                                      | 否   | -      | 品牌 ID，变更时自动重新加载并清空选中值 |
+| seriesId     | `number`                                      | 否   | -      | 系列 ID，变更时自动重新加载并清空选中值 |
+| shelfStatus  | `number`                                      | 否   | -      | 上架状态过滤                            |
+| disabled     | `boolean`                                     | 否   | -      | 禁用状态                                |
+| className    | `string`                                      | 否   | -      | 自定义样式类名                          |
+
+## 导出类型
+
+组件本身未导出独立类型。`onChange` 回调中的 `SpuItem` 类型来源于 `@api/product`。
+
+## API 数据源
+
+- **内部 Hook**：`useSpuOptions`（使用 SWR 缓存）
+- **内部接口**：`apiService.spuList`
+- **请求参数**：`{ categoryId, brandId, seriesId, id, spuName, status, page, pageSize }`
+- **可覆盖**：通过 `<ConfigProvider apiService={{ spuList: customFn }}>` 替换默认实现
+
+## 依赖 Props
+
+| 依赖属性   | 类型     | 来源                         | 说明                |
+| ---------- | -------- | ---------------------------- | ------------------- |
+| categoryId | `number` | EffectCategoryCascade 的输出 | 按分类过滤 SPU 列表 |
+| brandId    | `number` | EffectBrandSelect 的输出     | 按品牌过滤 SPU 列表 |
+| seriesId   | `number` | EffectSeriesSelect 的输出    | 按系列过滤 SPU 列表 |
+
+### 联动示例
+
+```tsx
+import { useState } from 'react'
+import {
+  EffectCategoryCascade,
+  EffectBrandSelect,
+  EffectSeriesSelect,
+  EffectSpuSelect,
+  isSingleTreeSelected,
+} from '@xfe-repo/web-components'
+
+function CascadeFilter() {
+  const [categoryId, setCategoryId] = useState<number>()
+  const [brandId, setBrandId] = useState<number>()
+  const [seriesId, setSeriesId] = useState<number>()
+  const [spuId, setSpuId] = useState<number>()
+
+  return (
+    <div>
+      <EffectCategoryCascade
+        onChange={(values, selectedList) => {
+          if (selectedList && isSingleTreeSelected(selectedList)) {
+            setCategoryId(Number(selectedList[selectedList.length - 1].value))
+          } else {
+            setCategoryId(undefined)
+          }
+        }}
+      />
+      <EffectBrandSelect categoryId={categoryId} value={brandId} onChange={(value) => setBrandId(value as number)} />
+      <EffectSeriesSelect categoryId={categoryId} brandId={brandId} value={seriesId} onChange={(value) => setSeriesId(value)} />
+      <EffectSpuSelect
+        categoryId={categoryId}
+        brandId={brandId}
+        seriesId={seriesId}
+        value={spuId}
+        onChange={(value, spuData) => setSpuId(value)}
+      />
+    </div>
+  )
+}
+```
+
+## 常见陷阱
+
+- ❌ 忽略 `onChange` 第二个参数 `spuData` 的完整数据——它是 `SpuItem` 类型，包含 SPU 图片、名称等完整信息：
+  ```tsx
+  onChange={(value) => setSpuId(value)}
+  // 丢失了完整 SPU 数据
+  ```
+- ✅ 需要 SPU 详细信息时保存第二个参数：
+
+  ```tsx
+  onChange={(value, spuData) => {
+    setSpuId(value)
+    setSpuDetail(spuData)  // 保存完整 SPU 数据供后续使用
+  }}
+  ```
+
+- ❌ 上游条件变更后期望保留已选 SPU——条件变更时组件会自动清空选中值
+- ✅ 在 `onChange` 中正确处理 `undefined` 情况
+
+- ⚠️ onChange 有第二参数 `spuData`（完整 SPU 数据对象），请务必捕获以获取 SPU 详情：
+
+  ```tsx
+  <EffectSpuSelect
+    onChange={(spuId, spuData) => {
+      form.setFieldValue('spuName', spuData?.name)
+    }}
+  />
+  ```
+
+- ❌ `shelfStatus` 不传时期望默认只显示上架商品——不传表示不过滤
+- ✅ 需要过滤上架状态时显式传入 `shelfStatus={1}`
+
+## 相关组件
+
+| 场景     | 组件                    | 说明                             |
+| -------- | ----------------------- | -------------------------------- |
+| 级联上游 | `EffectCategoryCascade` | 提供 categoryId                  |
+| 级联上游 | `EffectBrandSelect`     | 提供 brandId                     |
+| 级联上游 | `EffectSeriesSelect`    | 提供 seriesId                    |
+| 级联下游 | `EffectSkuSelect`       | 使用 spuId 过滤 SKU 列表         |
+| 聚合使用 | `EffectScopeSelect`     | 内部已集成本组件，无需单独使用   |
+| API 配置 | `ConfigProvider`        | 提供 apiService.spuList 接口实现 |