@xfe-repo/web-components 1.6.1 → 1.7.0

package/skills/references/EffectSeriesSelect.md

@@ -0,0 +1,205 @@
+# EffectSeriesSelect
+
+> 系列下拉选择器，支持按分类和品牌过滤、远程搜索、图片预览和无限滚动加载，数据通过 `apiService.seriesComboBox` 自动获取。
+
+## 导入
+
+```tsx
+import { EffectSeriesSelect } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+最常见用法 — 在 Form.Item 中使用，value/onChange 由 Form 自动注入：
+
+```tsx
+<Form.Item name="seriesId" label="系列">
+  <EffectSeriesSelect categoryId={categoryId} brandId={brandId} />
+</Form.Item>
+```
+
+### 级联使用（标准模式）
+
+EffectSeriesSelect 通常作为 分类→品牌→系列 级联链的最后一环：
+
+```tsx
+const categoryId = Form.useWatch('categoryIds', form)?.at(-1)
+const brandId = Form.useWatch('brandId', form)
+
+<Form.Item name="seriesId" label="系列">
+  <EffectSeriesSelect
+    categoryId={categoryId}
+    brandId={brandId}
+    key={`${categoryId}-${brandId}`}
+  />
+</Form.Item>
+```
+
+> ⚠️ 建议同时传入 `categoryId` 和 `brandId`，仅传一个会降低过滤精度。
+
+### 独立受控模式
+
+```tsx
+import { EffectSeriesSelect } from '@xfe-repo/web-components'
+
+function MyForm() {
+  const [seriesId, setSeriesId] = useState<number>()
+
+  return <EffectSeriesSelect value={seriesId} onChange={(value) => setSeriesId(value)} />
+}
+```
+
+## 进阶用法
+
+### 按分类 + 品牌过滤系列
+
+`categoryId` 或 `brandId` 变更时，组件会自动重新请求系列列表并清空已选值。
+
+```tsx
+const [categoryId, setCategoryId] = useState<number>()
+const [brandId, setBrandId] = useState<number>()
+const [seriesId, setSeriesId] = useState<number>()
+
+<EffectCategoryCascade
+  onChange={(values, selectedList) => {
+    if (selectedList && isSingleTreeSelected(selectedList)) {
+      const lastItem = selectedList[selectedList.length - 1]
+      setCategoryId(Number(lastItem.value))
+    }
+  }}
+/>
+<EffectBrandSelect
+  categoryId={categoryId}
+  value={brandId}
+  onChange={(value) => setBrandId(value as number)}
+/>
+<EffectSeriesSelect
+  categoryId={categoryId}
+  brandId={brandId}
+  value={seriesId}
+  onChange={(value) => setSeriesId(value)}
+/>
+```
+
+## Props
+
+```typescript
+type ConditionsType = { categoryId?: number; brandId?: number }
+
+type Props = ConditionsType & {
+  className?: string
+  onChange?: (value?: number, name?: string) => void
+  value?: number
+  defaultValue?: string
+  disabled?: boolean
+}
+```
+
+| 属性         | 类型                                      | 必填 | 默认值 | 说明                                    |
+| ------------ | ----------------------------------------- | ---- | ------ | --------------------------------------- |
+| value        | `number`                                  | 否   | -      | 受控值（系列 ID）                       |
+| defaultValue | `string`                                  | 否   | -      | 默认值                                  |
+| onChange     | `(value?: number, name?: string) => void` | 否   | -      | 值变化回调，第二个参数为系列名称        |
+| categoryId   | `number`                                  | 否   | -      | 分类 ID，变更时自动重新加载并清空选中值 |
+| brandId      | `number`                                  | 否   | -      | 品牌 ID，变更时自动重新加载并清空选中值 |
+| disabled     | `boolean`                                 | 否   | -      | 禁用状态                                |
+| className    | `string`                                  | 否   | -      | 自定义样式类名                          |
+
+## 导出类型
+
+组件本身未导出独立类型。内部使用了从 `EffectSkuSelect` 导入的 `ItemOption`、`ValueType`、`SelectDropdown` 等。
+
+## API 数据源
+
+- **内部 Hook**：`useSeriesOptions`（使用 SWR 缓存）
+- **内部接口**：`apiService.seriesComboBox`
+- **请求参数**：`{ categoryId, brandId, id, seriesName, page, pageSize }`
+- **可覆盖**：通过 `<ConfigProvider apiService={{ seriesComboBox: customFn }}>` 替换默认实现
+
+## 依赖 Props
+
+| 依赖属性   | 类型     | 来源                         | 说明               |
+| ---------- | -------- | ---------------------------- | ------------------ |
+| categoryId | `number` | EffectCategoryCascade 的输出 | 按分类过滤系列列表 |
+| brandId    | `number` | EffectBrandSelect 的输出     | 按品牌过滤系列列表 |
+
+### 联动示例
+
+```tsx
+import { useState } from 'react'
+import { EffectCategoryCascade, EffectBrandSelect, EffectSeriesSelect, isSingleTreeSelected } from '@xfe-repo/web-components'
+import type { TreeValueType, TreeSelectList, BrandValueType } from '@xfe-repo/web-components'
+
+function CategoryBrandSeriesFilter() {
+  const [categoryId, setCategoryId] = useState<number>()
+  const [brandId, setBrandId] = useState<number>()
+  const [seriesId, setSeriesId] = useState<number>()
+
+  const handleCategoryChange = (values?: TreeValueType, selectedList?: TreeSelectList) => {
+    if (selectedList && isSingleTreeSelected(selectedList)) {
+      const lastItem = selectedList[selectedList.length - 1]
+      setCategoryId(Number(lastItem.value))
+    } else {
+      setCategoryId(undefined)
+    }
+  }
+
+  return (
+    <div>
+      <EffectCategoryCascade onChange={handleCategoryChange} />
+      <EffectBrandSelect categoryId={categoryId} value={brandId} onChange={(value) => setBrandId(value as number)} />
+      <EffectSeriesSelect categoryId={categoryId} brandId={brandId} value={seriesId} onChange={(value) => setSeriesId(value)} />
+    </div>
+  )
+}
+```
+
+## 常见陷阱
+
+- ❌ `categoryId` 或 `brandId` 变更后仍然期望保留之前选中的系列值：
+  ```tsx
+  // conditions 变更时组件内部会自动清空 value 并触发 onChange()
+  ```
+- ✅ 在 `onChange` 回调中处理清空逻辑：
+
+  ```tsx
+  <EffectSeriesSelect
+    categoryId={categoryId}
+    brandId={brandId}
+    onChange={(value) => {
+      // value 可能为 undefined（上游条件变更导致的自动清空）
+      setSeriesId(value)
+    }}
+  />
+  ```
+
+- ❌ 只传 `brandId` 不传 `categoryId` 期望获取全量系列列表——两个条件独立生效，不传即不过滤
+- ✅ 根据业务需要传递对应的过滤条件
+
+- ⚠️ 仅传 `brandId` 不传 `categoryId` 会降低过滤精度，返回该品牌在所有分类下的系列。建议始终同时传入两个参数。
+
+- ❌ value 为 `0` 时被误判为空值——组件内部 `value || undefined` 会将 `0` 视为 falsy
+- ✅ 使用有效的正整数 ID 作为 value
+
+### 多选版本（EffectSeriesSelectV2）
+
+```tsx
+import { EffectSeriesSelectV2 } from '@xfe-repo/web-components'
+
+;<Form.Item name="seriesIds" label="系列（多选）">
+  <EffectSeriesSelectV2 categoryId={categoryId} brandId={brandId} mode="multiple" />
+</Form.Item>
+```
+
+> 💡 V2 固定为多选模式，需同时传入 `categoryId` 和 `brandId`。详见 [EffectSeriesSelectV2](./EffectSeriesSelectV2.md)。
+
+## 相关组件
+
+| 场景     | 组件                    | 说明                                    |
+| -------- | ----------------------- | --------------------------------------- |
+| 级联上游 | `EffectCategoryCascade` | 提供 categoryId                         |
+| 级联上游 | `EffectBrandSelect`     | 提供 brandId                            |
+| 级联下游 | `EffectSpuSelect`       | 使用 seriesId 过滤 SPU 列表             |
+| 多选版本 | `EffectSeriesSelectV2`  | 固定多选模式的系列选择器                |
+| 聚合使用 | `EffectScopeSelect`     | 内部已集成本组件，无需单独使用          |
+| API 配置 | `ConfigProvider`        | 提供 apiService.seriesComboBox 接口实现 |

package/skills/references/EffectSeriesSelectV2.md

@@ -0,0 +1,154 @@
+# EffectSeriesSelectV2
+
+> 系列多选器 V2，基于品牌和分类筛选系列列表，支持远程搜索和滚动加载更多，固定 `mode="multiple"` 多选模式。
+
+## 导入
+
+```tsx
+import { EffectSeriesSelectV2 } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+```tsx
+import { EffectSeriesSelectV2 } from '@xfe-repo/web-components'
+
+function MyForm() {
+  const [seriesIds, setSeriesIds] = useState<number[]>([])
+
+  return <EffectSeriesSelectV2 brandId={1} categoryId={100} value={seriesIds} onChange={(values) => setSeriesIds(values)} />
+}
+```
+
+## 进阶用法
+
+### 分类 → 品牌 → 系列三级联动
+
+```tsx
+import { EffectCategoryCascade, EffectBrandSelect, EffectSeriesSelectV2 } from '@xfe-repo/web-components'
+
+function CategoryBrandSeriesFilter() {
+  const [categoryId, setCategoryId] = useState<number>()
+  const [brandId, setBrandId] = useState<number>()
+  const [seriesIds, setSeriesIds] = useState<number[]>([])
+
+  return (
+    <div>
+      <EffectCategoryCascade
+        onChange={(values, selectedList) => {
+          if (selectedList && isSingleTreeSelected(selectedList)) {
+            setCategoryId(Number(selectedList[selectedList.length - 1].value))
+          }
+        }}
+      />
+      <EffectBrandSelect categoryId={categoryId} value={brandId} onChange={(value) => setBrandId(value as number)} />
+      <EffectSeriesSelectV2 brandId={brandId} categoryId={categoryId} value={seriesIds} onChange={setSeriesIds} />
+    </div>
+  )
+}
+```
+
+### 自定义分页大小
+
+```tsx
+<EffectSeriesSelectV2 brandId={1} categoryId={100} pageSize={20} value={seriesIds} onChange={setSeriesIds} />
+```
+
+## Props
+
+```typescript
+type EffectSeriesSelectV2Props = Omit<SelectProps<number[]>, 'mode' | 'onChange'> & {
+  allowClear?: boolean
+  brandId?: number
+  categoryId?: number
+  onChange?: (value: number[]) => void
+  pageSize?: number
+  placeholder?: string
+  value?: number[]
+}
+```
+
+| 属性         | 类型                        | 必填 | 默认值         | 说明                                                   |
+| ------------ | --------------------------- | ---- | -------------- | ------------------------------------------------------ |
+| value        | `number[]`                  | 否   | -              | 受控值，选中的系列 ID 数组                             |
+| onChange     | `(value: number[]) => void` | 否   | -              | 值变化回调                                             |
+| brandId      | `number`                    | 否   | -              | **核心依赖**：品牌 ID，变更时重新加载系列列表          |
+| categoryId   | `number`                    | 否   | -              | **核心依赖**：分类 ID，变更时重新加载系列列表          |
+| pageSize     | `number`                    | 否   | `10`           | 每页加载数量（滚动加载更多）                           |
+| allowClear   | `boolean`                   | 否   | `true`         | 是否显示清除按钮                                       |
+| placeholder  | `string`                    | 否   | `'请选择系列'` | 占位符文本                                             |
+| disabled     | `boolean`                   | 否   | -              | 禁用状态（继承自 SelectProps）                         |
+| className    | `string`                    | 否   | -              | 自定义样式类名（继承自 SelectProps）                   |
+| ...restProps | `SelectProps`               | 否   | -              | 其他 Ant Design Select 属性（除 `mode` 和 `onChange`） |
+
+> **注意**：`mode` 固定为 `"multiple"`，无法通过 props 修改。
+
+## API 数据源
+
+- **内部接口**：`apiService.seriesList`
+- **请求参数**：`{ brandId, categoryId, page, pageSize, seriesName }`
+- **前置条件**：`brandId` 和 `categoryId` 都必须存在才会发起请求
+- **搜索策略**：300ms 防抖远程搜索
+- **分页策略**：下拉滚动到底部自动加载下一页，追加到已有选项列表
+- **可覆盖**：通过 `<ConfigProvider apiService={{ seriesList: customFn }}>` 替换默认实现
+
+## 依赖 Props
+
+| 依赖属性   | 类型     | 来源                         | 说明               |
+| ---------- | -------- | ---------------------------- | ------------------ |
+| brandId    | `number` | EffectBrandSelect 的输出     | 按品牌过滤系列列表 |
+| categoryId | `number` | EffectCategoryCascade 的输出 | 按分类过滤系列列表 |
+
+### 联动示例
+
+```tsx
+const [categoryId, setCategoryId] = useState<number>()
+const [brandId, setBrandId] = useState<number>()
+const [seriesIds, setSeriesIds] = useState<number[]>([])
+
+// brandId 或 categoryId 变更时，EffectSeriesSelectV2 会自动重新加载列表
+<EffectSeriesSelectV2
+  brandId={brandId}
+  categoryId={categoryId}
+  value={seriesIds}
+  onChange={setSeriesIds}
+/>
+```
+
+## 常见陷阱
+
+- ❌ 只传 `brandId` 不传 `categoryId`（或反过来）：
+  ```tsx
+  // 两者都为空时选项列表为空，不会发起请求
+  ```
+- ✅ 确保 `brandId` 和 `categoryId` 同时存在
+
+- ❌ 尝试修改 `mode` 为单选：
+  ```tsx
+  // mode 被从 Props 中 Omit 掉，固定为 "multiple"
+  ```
+- ✅ 如需单选系列，请使用 `EffectSeriesSelect` 组件
+
+- ❌ 期望 `brandId`/`categoryId` 变更后保留已选值：
+  ```tsx
+  // 依赖变更时组件会重新加载选项列表，但不会自动清空 value
+  // 需要自行在上游变更时重置 seriesIds
+  ```
+- ✅ 在上游变更回调中清空系列值：
+  ```tsx
+  <EffectBrandSelect
+    onChange={(value) => {
+      setBrandId(value as number)
+      setSeriesIds([]) // 手动清空系列选择
+    }}
+  />
+  ```
+
+## 相关组件
+
+| 场景     | 组件                    | 说明                                  |
+| -------- | ----------------------- | ------------------------------------- |
+| 级联上游 | `EffectCategoryCascade` | 提供 categoryId                       |
+| 级联上游 | `EffectBrandSelect`     | 提供 brandId                          |
+| 单选替代 | `EffectSeriesSelect`    | 系列单选器（V1）                      |
+| API 配置 | `ConfigProvider`        | 提供 `apiService.seriesList` 接口实现 |

package/skills/references/EffectSkuRecognize.md

@@ -0,0 +1,149 @@
+# EffectSkuRecognize
+
+> SKU 图片智能识别组件，通过传入图片 URL 进行智能识图，展示相似 SKU 卡片列表供用户选择。
+
+## 导入
+
+```tsx
+import { EffectSkuRecognize } from '@xfe-repo/web-components'
+import type { EffectSkuRecognizeProps } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+```tsx
+import { EffectSkuRecognize } from '@xfe-repo/web-components'
+
+function SkuMatcher() {
+  const [skuId, setSkuId] = useState<number>()
+
+  return (
+    <EffectSkuRecognize
+      image="https://example.com/product.jpg"
+      onChange={(skuId, skuItem) => {
+        setSkuId(skuId)
+        console.log('选中 SKU：', skuItem)
+      }}
+    />
+  )
+}
+```
+
+## 进阶用法
+
+### 限定品牌和分类范围
+
+```tsx
+<EffectSkuRecognize image={imageUrl} brandId={123} categoryId={456} onChange={(skuId, skuItem) => setSkuId(skuId)} />
+```
+
+### 限制结果数量
+
+```tsx
+<EffectSkuRecognize image={imageUrl} limitSize={5} onChange={(skuId, skuItem) => setSkuId(skuId)} />
+```
+
+### 紧凑布局
+
+```tsx
+<EffectSkuRecognize image={imageUrl} size="small" onChange={(skuId, skuItem) => setSkuId(skuId)} />
+```
+
+### 识别临时 SKU
+
+```tsx
+<EffectSkuRecognize image={imageUrl} skuType="tmp" onChange={(skuId, skuItem) => setSkuId(skuId)} />
+```
+
+## Props
+
+```typescript
+export interface EffectSkuRecognizeProps {
+  categoryId?: number
+  brandId?: number
+  image: string
+  limitSize?: number
+  onChange?: (skuId: number, skuItem: ListSkuV2) => void
+  value?: number
+  defaultValue?: number
+  disabled?: boolean
+  size?: 'small' | 'default'
+  skuType?: 'std' | 'tmp'
+}
+```
+
+| 属性         | 类型                       | 必填   | 默认值      | 说明                                          |
+| ------------ | -------------------------- | ------ | ----------- | --------------------------------------------- |
+| image        | `string`                   | **是** | -           | 用于识别的图片 URL                            |
+| value        | `number`                   | 否     | -           | 受控值（SKU ID）                              |
+| defaultValue | `number`                   | 否     | -           | 默认值                                        |
+| onChange     | `(skuId, skuItem) => void` | 否     | -           | 选中 SKU 回调，返回 skuId 和完整 SKU 数据     |
+| categoryId   | `number`                   | 否     | -           | 分类 ID，缩小识别范围                         |
+| brandId      | `number`                   | 否     | -           | 品牌 ID，缩小识别范围                         |
+| limitSize    | `number`                   | 否     | -           | 最多显示的结果数量                            |
+| size         | `'small' \| 'default'`     | 否     | `'default'` | 卡片网格布局尺寸                              |
+| skuType      | `'std' \| 'tmp'`           | 否     | `'std'`     | SKU 类型，`'std'` 标准 SKU / `'tmp'` 临时 SKU |
+| disabled     | `boolean`                  | 否     | -           | 禁用时隐藏"就是它"选择按钮                    |
+
+## 导出类型
+
+```typescript
+export interface EffectSkuRecognizeProps { ... }
+
+// ListSkuV2 来自 @api/product，包含以下关键字段：
+// skuId, skuName, brandName, seriesName, image, skuImage, score, name 等
+```
+
+## API 数据源
+
+- **内部接口**：`apiService.productImageSpuSkuList`
+- **请求参数**：`{ type: 'sku', skuType, brandId, categoryId, image }`
+- **触发时机**：组件挂载时、`image`/`brandId`/`categoryId`/`skuType` 变更时自动触发识别
+- **可覆盖**：通过 `<ConfigProvider apiService={{ productImageSpuSkuList: customFn }}>` 替换
+
+## 依赖 Props
+
+| 依赖属性   | 类型     | 来源                         | 说明             |
+| ---------- | -------- | ---------------------------- | ---------------- |
+| brandId    | `number` | EffectBrandSelect 的输出     | 限定识别品牌范围 |
+| categoryId | `number` | EffectCategoryCascade 的输出 | 限定识别分类范围 |
+
+## 内部结构
+
+组件渲染为一个 `Spin` 加载容器，内部使用 `OSSImage.PreviewGroup` 包裹 `List` 列表。每个结果项为一个 `Card`，包含：
+
+- `Badge`：显示相似度分数
+- `OSSImage`：SKU 图片（支持预览）
+- `Link`：跳转到 SKU 详情页 `/dashboard/product/standardSku/detail?skuId=xxx`
+- `Button`："就是它"选择按钮（disabled 时隐藏）
+
+预览模式下底部工具栏也有"就是它"按钮。
+
+## 常见陷阱
+
+- ❌ 不传 `image` prop：
+  ```tsx
+  // image 为空字符串时不会发起请求，组件不会显示任何结果
+  ```
+- ✅ 确保传入有效的图片 URL
+
+- ❌ 期望 `disabled` 时隐藏整个组件：
+  ```tsx
+  // disabled 仅隐藏 "就是它" 按钮，结果列表仍然展示
+  ```
+- ✅ 如需完全隐藏，请在外层自行控制渲染
+
+- ❌ `image` 变更时未注意到会自动重新识别：
+  ```tsx
+  // 每次 image 变化都会触发新的识别请求
+  ```
+- ✅ 确保 image 稳定引用，避免不必要的重复请求
+
+## 相关组件
+
+| 场景         | 组件              | 说明                                     |
+| ------------ | ----------------- | ---------------------------------------- |
+| SKU 选择替代 | `EffectSkuSelect` | 基于搜索的 SKU 下拉选择器                |
+| SKU 表格选择 | `EffectSkuTable`  | 分类/品牌/系列/SPU/SKU 联动表格          |
+| 图片展示     | `OSSImage`        | 内部使用的 OSS 图片组件                  |
+| API 配置     | `ConfigProvider`  | 提供 `apiService.productImageSpuSkuList` |