@xfe-repo/web-components 1.6.1 → 1.7.0

package/skills/references/EffectBrandSelect.md

@@ -0,0 +1,231 @@
+# EffectBrandSelect
+
+> 品牌下拉选择器，支持分类过滤、远程搜索、多选，数据通过 `apiService.brandComboBox` 自动获取。
+
+## 导入
+
+```tsx
+import { EffectBrandSelect } from '@xfe-repo/web-components'
+import type { BrandValueType, BrandOptions } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+最常见用法 — 在 Form.Item 中使用，value/onChange 由 Form 自动注入：
+
+```tsx
+<Form.Item name="brandId" label="品牌">
+  <EffectBrandSelect categoryId={categoryId} />
+</Form.Item>
+```
+
+### 独立受控模式
+
+```tsx
+import { EffectBrandSelect } from '@xfe-repo/web-components'
+
+function MyForm() {
+  const [brandId, setBrandId] = useState<number>()
+
+  return <EffectBrandSelect value={brandId} onChange={(value) => setBrandId(value as number)} />
+}
+```
+
+## 进阶用法
+
+### 按分类过滤品牌
+
+`categoryId` 变更时，组件会自动重新请求品牌列表并清空已选值。
+
+```tsx
+const [categoryId, setCategoryId] = useState<number>()
+const [brandId, setBrandId] = 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)}
+/>
+```
+
+### 多选模式
+
+```tsx
+const [brandIds, setBrandIds] = useState<number[]>()
+
+<EffectBrandSelect
+  mode="multiple"
+  value={brandIds}
+  onChange={(value, labels) => {
+    setBrandIds(value as number[])
+    // labels 多选时以 '>>>' 连接，如 "Nike>>>Adidas"
+    console.log('选中品牌名称：', labels)
+  }}
+/>
+```
+
+### 显示"其它"品牌
+
+默认隐藏"其它"品牌选项，需要时显式开启：
+
+```tsx
+<EffectBrandSelect showOtherBrand />
+```
+
+### onChange 同步品牌名称
+
+onChange 第二参数携带品牌名称，需手动同步到隐藏字段：
+
+```tsx
+<Form.Item name="brandId" label="品牌">
+  <EffectBrandSelect
+    categoryId={categoryId}
+    key={categoryId}
+    onChange={(brandId, brandName) => {
+      form.setFieldValue('brandName', brandName)
+    }}
+  />
+</Form.Item>
+<Form.Item name="brandName" hidden><Input /></Form.Item>
+```
+
+## Props
+
+```typescript
+type Props = {
+  className?: string
+  onChange?: (value?: BrandValueType, label?: string) => void
+  value?: BrandValueType
+  defaultValue?: BrandValueType
+  disabled?: boolean
+  categoryId?: number
+  mode?: 'multiple' | 'tags'
+  sysBizTypeId?: InQueryBrandComboBox['sysBizTypeId']
+  /** 是否显示其他品牌，默认不露出 */
+  showOtherBrand?: boolean
+  style?: React.CSSProperties
+}
+```
+
+| 属性           | 类型                       | 必填 | 默认值  | 说明                                            |
+| -------------- | -------------------------- | ---- | ------- | ----------------------------------------------- |
+| value          | `BrandValueType`           | 否   | -       | 受控值                                          |
+| defaultValue   | `BrandValueType`           | 否   | -       | 默认值                                          |
+| onChange       | `(value?, label?) => void` | 否   | -       | 值变化回调，多选时 label 以 `>>>` 连接          |
+| categoryId     | `number`                   | 否   | -       | 分类 ID，变更时自动重新加载品牌列表并清空选中值 |
+| mode           | `'multiple' \| 'tags'`     | 否   | -       | 多选/标签模式                                   |
+| sysBizTypeId   | `string`                   | 否   | -       | 业务品牌类型 ID                                 |
+| showOtherBrand | `boolean`                  | 否   | `false` | 是否显示"其它"品牌选项（value=1310）            |
+| disabled       | `boolean`                  | 否   | -       | 禁用状态                                        |
+| className      | `string`                   | 否   | -       | 自定义样式类名                                  |
+| style          | `React.CSSProperties`      | 否   | -       | 自定义行内样式                                  |
+
+## 导出类型
+
+```typescript
+// 品牌值类型：单选为 number，多选为 number[]
+export type BrandValueType = number | number[] | string | undefined
+
+// 品牌选项列表
+export type BrandOptions = { label: string; value: number }[]
+```
+
+## API 数据源
+
+- **内部 Hook**：`useBrandOptions`（使用 SWR 缓存）
+- **内部接口**：`apiService.brandComboBox`
+- **请求参数**：`{ categoryId, sysBizTypeId, brandName, brandId, page: 1, pageSize: 500 }`
+- **可覆盖**：通过 `<ConfigProvider apiService={{ brandComboBox: customFn }}>` 替换默认实现
+
+## 依赖 Props
+
+| 依赖属性     | 类型     | 来源                         | 说明                                   |
+| ------------ | -------- | ---------------------------- | -------------------------------------- |
+| categoryId   | `number` | EffectCategoryCascade 的输出 | 按分类过滤品牌列表，变更时清空已选品牌 |
+| sysBizTypeId | `string` | 业务参数                     | 业务品牌类型过滤                       |
+
+### 联动示例
+
+```tsx
+import { useState } from 'react'
+import { EffectCategoryCascade, EffectBrandSelect, isSingleTreeSelected } from '@xfe-repo/web-components'
+import type { TreeValueType, TreeSelectList, BrandValueType } from '@xfe-repo/web-components'
+
+function CategoryBrandFilter() {
+  const [categoryId, setCategoryId] = useState<number>()
+  const [brandId, setBrandId] = 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)} />
+    </div>
+  )
+}
+```
+
+## 使用提示
+
+> 💡 不传 `categoryId` 时，组件加载全部品牌（不按分类过滤）。适用于跨分类的品牌搜索场景。
+
+## 常见陷阱
+
+### 分类切换后强制刷新
+
+当 `categoryId` 变化时，需要通过 `key` 强制重新挂载组件以刷新品牌列表：
+
+```tsx
+<Form.Item name="brandId" label="品牌">
+  <EffectBrandSelect categoryId={categoryId} key={categoryId} />
+</Form.Item>
+```
+
+> ⚠️ 不设置 `key` 时，categoryId 变化后品牌列表可能残留旧分类的数据。
+
+- ❌ `categoryId` 变更后仍然期望保留之前选中的品牌值：
+  ```tsx
+  // categoryId 变更时组件内部会自动清空 value 并触发 onChange()
+  ```
+- ✅ 在 `onChange` 回调中处理清空逻辑：
+
+  ```tsx
+  <EffectBrandSelect
+    categoryId={categoryId}
+    onChange={(value) => {
+      // value 可能为 undefined（categoryId 变更导致的自动清空）
+      setBrandId(value as number | undefined)
+    }}
+  />
+  ```
+
+- ❌ 用字符串作为 value 传入（虽然类型允许 string，但 options 的 value 是 number）
+- ✅ 使用 number 类型的 value
+
+- ❌ 在多选模式下解析 label 时忽略分隔符
+- ✅ 多选模式的 label 以 `>>>` 连接多个品牌名，使用 `label.split('>>>')` 解析
+
+## 相关组件
+
+| 场景     | 组件                    | 说明                                   |
+| -------- | ----------------------- | -------------------------------------- |
+| 级联上游 | `EffectCategoryCascade` | 提供 categoryId 过滤品牌列表           |
+| 级联下游 | `EffectSeriesSelect`    | 使用品牌 ID 过滤系列列表               |
+| 聚合使用 | `EffectScopeSelect`     | 内部已集成本组件，无需单独使用         |
+| API 配置 | `ConfigProvider`        | 提供 apiService.brandComboBox 接口实现 |

package/skills/references/EffectBrandTransfer.md

@@ -0,0 +1,143 @@
+# EffectBrandTransfer
+
+> 品牌穿梭框，基于 Ant Design Transfer 实现品牌多选，支持分类过滤和搜索，数据复用 `useBrandOptions` Hook 获取。
+
+## 导入
+
+```tsx
+import { EffectBrandTransfer } from '@xfe-repo/web-components'
+import type { EffectBrandTransferProps, TransferValueType, TransferPropValueType } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+```tsx
+import { EffectBrandTransfer } from '@xfe-repo/web-components'
+
+function MyForm() {
+  const [brandIds, setBrandIds] = useState<number[]>()
+
+  return <EffectBrandTransfer value={brandIds} onChange={(value) => setBrandIds(value as number[])} />
+}
+```
+
+## 进阶用法
+
+### 按分类过滤品牌
+
+`categoryId` 变更时，组件会自动重新请求品牌列表并清空已选值。
+
+```tsx
+const [categoryId, setCategoryId] = useState<number>()
+const [brandIds, setBrandIds] = useState<number[]>()
+
+<EffectCategoryCascade
+  onChange={(values, selectedList) => {
+    if (selectedList && isSingleTreeSelected(selectedList)) {
+      const lastItem = selectedList[selectedList.length - 1]
+      setCategoryId(Number(lastItem.value))
+    }
+  }}
+/>
+<EffectBrandTransfer
+  categoryId={categoryId}
+  value={brandIds}
+  onChange={(value, name) => {
+    setBrandIds(value as number[])
+    // name 多选时以 '>>>' 连接，如 "Nike>>>Adidas"
+    console.log('选中品牌名称：', name)
+  }}
+/>
+```
+
+### 显示"其它"品牌
+
+```tsx
+<EffectBrandTransfer showOtherBrand />
+```
+
+## Props
+
+```typescript
+export type EffectBrandTransferProps = {
+  className?: string
+  onChange?: (value?: BrandValueType, name?: string) => void
+  value?: TransferPropValueType
+  defaultValue?: TransferPropValueType
+  disabled?: boolean
+  categoryId?: number
+  sysBizTypeId?: InQueryBrandComboBox['sysBizTypeId']
+  /** 是否显示其他品牌，默认不露出 */
+  showOtherBrand?: boolean
+}
+```
+
+| 属性           | 类型                      | 必填 | 默认值  | 说明                                     |
+| -------------- | ------------------------- | ---- | ------- | ---------------------------------------- |
+| value          | `number[] \| undefined`   | 否   | -       | 受控值，已选中的品牌 ID 数组             |
+| defaultValue   | `number[] \| undefined`   | 否   | -       | 默认值                                   |
+| onChange       | `(value?, name?) => void` | 否   | -       | 值变化回调，name 以 `>>>` 连接多个品牌名 |
+| categoryId     | `number`                  | 否   | -       | 分类 ID，变更时自动重新加载并清空选中值  |
+| sysBizTypeId   | `string`                  | 否   | -       | 业务品牌类型 ID                          |
+| showOtherBrand | `boolean`                 | 否   | `false` | 是否显示"其它"品牌选项（key=1310）       |
+| disabled       | `boolean`                 | 否   | -       | 禁用状态                                 |
+| className      | `string`                  | 否   | -       | 自定义样式类名                           |
+
+## 导出类型
+
+```typescript
+// 穿梭框内部使用的值类型（string 数组）
+export type TransferValueType = string[]
+
+// Props 中 value/defaultValue 的类型
+export type TransferPropValueType = number[] | undefined
+
+// Props 类型
+export type EffectBrandTransferProps = { ... }
+```
+
+## API 数据源
+
+- **内部 Hook**：`useBrandOptions`（复用 EffectBrandSelect 的 Hook，使用 SWR 缓存）
+- **内部接口**：`apiService.brandComboBox`
+- **请求参数**：`{ categoryId, sysBizTypeId, brandName, brandId, pageSize: 500 }`
+- **可覆盖**：通过 `<ConfigProvider apiService={{ brandComboBox: customFn }}>` 替换默认实现
+
+## 依赖 Props
+
+| 依赖属性     | 类型     | 来源                         | 说明                                   |
+| ------------ | -------- | ---------------------------- | -------------------------------------- |
+| categoryId   | `number` | EffectCategoryCascade 的输出 | 按分类过滤品牌列表，变更时清空已选品牌 |
+| sysBizTypeId | `string` | 业务参数                     | 业务品牌类型过滤                       |
+
+## 常见陷阱
+
+- ❌ `categoryId` 变更后仍然期望保留已穿梭的品牌：
+  ```tsx
+  // categoryId 或 sysBizTypeId 变更时，组件内部会自动清空 targetKeys 并触发 onChange()
+  ```
+- ✅ 在 `onChange` 回调中处理清空逻辑：
+
+  ```tsx
+  <EffectBrandTransfer
+    categoryId={categoryId}
+    onChange={(value) => {
+      // value 可能为 undefined（依赖属性变更导致的自动清空）
+      setBrandIds(value as number[] | undefined)
+    }}
+  />
+  ```
+
+- ❌ 将 `value` 传入字符串数组
+- ✅ 使用 `number[]` 类型的 value，组件内部会自动转换为 string 用于 Transfer
+
+- ❌ 在 `onChange` 中直接使用 name 而不拆分
+- ✅ 多选时 name 以 `>>>` 连接，使用 `name.split('>>>')` 解析
+
+## 相关组件
+
+| 场景         | 组件                    | 说明                                                |
+| ------------ | ----------------------- | --------------------------------------------------- |
+| 级联上游     | `EffectCategoryCascade` | 提供 categoryId 过滤品牌列表                        |
+| 下拉选择替代 | `EffectBrandSelect`     | 品牌下拉选择器（单选/多选），共享 `useBrandOptions` |
+| API 配置     | `ConfigProvider`        | 提供 `apiService.brandComboBox` 接口实现            |

package/skills/references/EffectCategoryCascade.md

@@ -0,0 +1,228 @@
+# EffectCategoryCascade
+
+> 分类级联选择器，基于 antd Cascader 封装，是级联链（分类→品牌→系列→SPU→SKU）的起点，数据通过 `apiService.categoryListToTree` 自动获取。
+
+## 导入
+
+```tsx
+import { EffectCategoryCascade, isSingleTreeSelected } from '@xfe-repo/web-components'
+import type {
+  TreeSelectItem,
+  TreeSelectList,
+  TreeSingleValueType,
+  TreeValueType,
+  CustomTreeItem,
+  CustomTreeOptions,
+} from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+最常见用法 — 在 Form.Item 中使用，value/onChange 由 Form 自动注入：
+
+```tsx
+<Form.Item name="categoryIds" label="分类">
+  <EffectCategoryCascade changeOnSelect />
+</Form.Item>
+```
+
+### 独立受控模式
+
+```tsx
+import { EffectCategoryCascade } from '@xfe-repo/web-components'
+import type { TreeValueType, TreeSelectList } from '@xfe-repo/web-components'
+
+function MyForm() {
+  const handleChange = (value?: TreeValueType, selectedList?: TreeSelectList) => {
+    console.log('选中的分类路径值：', value) // 如 [1, 11, 111]
+    console.log('选中的分类详情：', selectedList) // 如 [{ value: 1, label: '手表', level: 0 }, ...]
+  }
+
+  return <EffectCategoryCascade onChange={handleChange} />
+}
+```
+
+## 进阶用法
+
+### 受控模式
+
+```tsx
+const [categoryValue, setCategoryValue] = useState<TreeValueType>()
+
+<EffectCategoryCascade
+  value={categoryValue}
+  onChange={(value, selectedList) => {
+    setCategoryValue(value)
+  }}
+/>
+```
+
+### 多选模式
+
+```tsx
+<EffectCategoryCascade
+  multiple
+  onChange={(values, selectedList) => {
+    // values: [[1, 11, 111], [2, 22, 222]]
+    // selectedList: [[{ value: 1, ... }, ...], [{ value: 2, ... }, ...]]
+    console.log('多选值：', values)
+  }}
+/>
+```
+
+### 选择即触发（不需要选到叶子节点）
+
+```tsx
+<EffectCategoryCascade
+  changeOnSelect
+  onChange={(value, selectedList) => {
+    // 选择任意层级都会触发
+    console.log('当前选择：', value)
+  }}
+/>
+```
+
+### 获取分类原始数据
+
+```tsx
+import { TreeCategory } from '@api/product'
+
+;<EffectCategoryCascade
+  onGetData={(dataList?: TreeCategory[]) => {
+    // 分类树数据加载完成后回调
+    console.log('分类树数据：', dataList)
+  }}
+/>
+```
+
+### 编辑态禁用
+
+编辑页面中分类不可修改时：
+
+```tsx
+<Form.Item name="categoryIds" label="分类">
+  <EffectCategoryCascade changeOnSelect disabled={isEdit} />
+</Form.Item>
+```
+
+## Props
+
+```typescript
+type Props = Omit<CascaderProps<any>, 'onChange' | 'defaultValue' | 'value'> & {
+  className?: string
+  onChange?: (value?: TreeValueType, selected?: TreeSelectList) => void
+  defaultValue?: TreeValueType
+  value?: TreeValueType
+  sysBizTypeId?: string
+  onGetData?: (dataList?: TreeCategory[]) => void
+}
+```
+
+| 属性           | 类型                          | 必填 | 默认值 | 说明                                                                              |
+| -------------- | ----------------------------- | ---- | ------ | --------------------------------------------------------------------------------- |
+| value          | `TreeValueType`               | 否   | -      | 受控值，单选为 `Array<string \| number>`，多选为 `Array<Array<string \| number>>` |
+| defaultValue   | `TreeValueType`               | 否   | -      | 默认值                                                                            |
+| onChange       | `(value?, selected?) => void` | 否   | -      | 值变化回调，第二个参数包含每级节点的详细信息                                      |
+| sysBizTypeId   | `string`                      | 否   | -      | 业务分类类型 ID，变更时重新加载分类树并清空选中值                                 |
+| onGetData      | `(dataList?) => void`         | 否   | -      | 分类树数据加载完成回调                                                            |
+| multiple       | `boolean`                     | 否   | -      | 继承自 antd Cascader，开启多选模式                                                |
+| changeOnSelect | `boolean`                     | 否   | -      | 继承自 antd Cascader，选择任意层级即触发 onChange                                 |
+| className      | `string`                      | 否   | -      | 自定义样式类名                                                                    |
+
+> **注意**：继承了 antd `CascaderProps` 的其他属性（如 `placeholder`、`disabled`、`showSearch` 等），但 `onChange`、`defaultValue`、`value` 被自定义实现覆盖。
+
+## 导出类型
+
+```typescript
+// 单个选中项
+export type TreeSelectItem = {
+  value: string | number
+  label: string
+  level: string | number
+  isLastLevel?: boolean
+}
+
+// 选中项列表：单选为 TreeSelectItem[]，多选为 TreeSelectItem[][]
+export type TreeSelectList = TreeSelectItem[] | TreeSelectItem[][]
+
+// 单选值类型：表示一条分类路径
+export type TreeSingleValueType = Array<string | number>
+
+// 值类型：单选为 TreeSingleValueType，多选为 TreeSingleValueType[]
+export type TreeValueType = TreeSingleValueType | TreeSingleValueType[]
+
+// 分类树节点（扩展自 TreeCategory）
+export type CustomTreeItem = TreeCategory & { index?: number }
+export type CustomTreeOptions = CustomTreeItem[] | CustomTreeItem[][]
+```
+
+### 辅助函数
+
+```typescript
+// 判断 selectedList 是否为单选模式的结果
+export const isSingleTreeSelected = (selectList?: TreeSelectList): selectList is TreeSelectItem[]
+
+// 将选项转换为 selectedList
+export const transformOptionToSelectedList = (selectedOptions?: CustomTreeOptions, multiple?: boolean) => TreeSelectList
+
+// 将 selectedList 转换为 values
+export const transformSelectListToValues = (selectList?: TreeSelectList, multiple?: boolean) => TreeValueType
+
+// 将 values 转换为 selectedList（注意：此时 label 为 value 的字符串形式）
+export const transformValuesToSelectList = (values?: TreeValueType, multiple?: boolean) => TreeSelectList
+```
+
+## API 数据源
+
+- **内部 Hook**：`useCategoryTree`（使用 SWR 缓存）
+- **内部接口**：`apiService.categoryListToTree`
+- **请求参数**：`{ sysBizTypeId }`
+- **可覆盖**：通过 `<ConfigProvider apiService={{ categoryListToTree: customFn }}>` 替换默认实现
+
+## 使用提示
+
+> 💡 约 70% 业务场景传 `changeOnSelect`，允许用户选择任意级别分类。建议默认使用。
+
+> 💡 常见宽度：`style={{ width: 160 }}` 或 `style={{ width: 200 }}`。
+
+## 常见陷阱
+
+- ❌ 混淆单选和多选时 `value`、`onChange` 的类型：
+  ```tsx
+  // 单选：value = [1, 11, 111]，selectedList = [{ value: 1, ... }, ...]
+  // 多选：value = [[1, 11], [2, 22]]，selectedList = [[...], [...]]
+  ```
+- ✅ 使用 `isSingleTreeSelected` 安全地判断 selectedList 模式：
+
+  ```tsx
+  onChange={(values, selectedList) => {
+    if (selectedList && isSingleTreeSelected(selectedList)) {
+      // 单选模式
+      const lastCategoryId = selectedList[selectedList.length - 1]?.value
+    }
+  }}
+  ```
+
+- ❌ 从 `onChange` 的 `value` 中直接取最后一级分类 ID 来传给 EffectBrandSelect：
+  ```tsx
+  // value 的元素类型是 string | number，可能不是纯 number
+  ```
+- ✅ 从 `selectedList` 中取值并转换：
+
+  ```tsx
+  const lastItem = selectedList[selectedList.length - 1]
+  const categoryId = Number(lastItem.value)
+  ```
+
+- ❌ `sysBizTypeId` 变更后期望保留已选分类
+- ✅ `sysBizTypeId` 变更时组件会自动清空选中值并触发 `onChange()`
+
+- ⚠️ 编辑回填时使用 `setTimeout(() => form.setFieldsValue(...))` 可能产生时序问题，建议使用 `useEffect` + `form.setFieldsValue` 在数据加载完成后统一设置。
+
+## 相关组件
+
+| 场景     | 组件                | 说明                                        |
+| -------- | ------------------- | ------------------------------------------- |
+| 级联下游 | `EffectBrandSelect` | 使用分类末级 ID 作为 categoryId 过滤品牌    |
+| 聚合使用 | `EffectScopeSelect` | 内部已集成本组件，无需单独使用              |
+| API 配置 | `ConfigProvider`    | 提供 apiService.categoryListToTree 接口实现 |