@xfe-repo/web-components 1.6.1 → 1.7.0

package/skills/references/EffectMerchantSelect.md

@@ -0,0 +1,183 @@
+# EffectMerchantSelect
+
+> 商户下拉选择器，支持按商户号、商户平台名、主账号手机号三种搜索源切换查询，数据通过 `apiService.merchantList` 自动获取。
+
+## 导入
+
+```tsx
+import { EffectMerchantSelect } from '@xfe-repo/web-components'
+import type { MerchantOptions } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+最常见用法 — 在 Form.Item 中使用，value/onChange 由 Form 自动注入：
+
+```tsx
+<Form.Item name="enterpriseNo" label="商户">
+  <EffectMerchantSelect />
+</Form.Item>
+```
+
+### 独立受控模式
+
+```tsx
+import { EffectMerchantSelect } from '@xfe-repo/web-components'
+
+function MyForm() {
+  const [merchantNo, setMerchantNo] = useState<string>()
+
+  return <EffectMerchantSelect value={merchantNo} onChange={(value) => setMerchantNo(value)} />
+}
+```
+
+## 进阶用法
+
+### 切换搜索源
+
+组件左侧有一个搜索源下拉框，可在运行时切换搜索字段。也可通过 `source` 指定初始搜索源：
+
+```tsx
+<EffectMerchantSelect
+  source="platformName" // 初始按商户平台名搜索
+  value={merchantNo}
+  onChange={(value, name) => {
+    setMerchantNo(value)
+    console.log('商户名：', name) // 返回 platformName
+  }}
+/>
+```
+
+### 自定义标签展示模式
+
+```tsx
+// 选项标签展示为 "商户平台名 - 企业编号" 格式
+<EffectMerchantSelect labelDisplayMode="platformName-enterpriseNo" value={merchantNo} onChange={(value) => setMerchantNo(value)} />
+```
+
+### onChange 同步商户名称
+
+Form 管理 enterpriseNo，但 enterpriseName 需要 useState 单独保存：
+
+```tsx
+const [merchantName, setMerchantName] = useState('')
+
+<Form.Item name="enterpriseNo" label="商户">
+  <EffectMerchantSelect
+    onChange={(no, name) => {
+      setMerchantName(name)
+    }}
+  />
+</Form.Item>
+```
+
+### 按手机号搜索
+
+```tsx
+<Form.Item name="enterpriseNo" label="商户">
+  <EffectMerchantSelect source="phone" placeholder="请输入手机号搜索" />
+</Form.Item>
+```
+
+> 💡 `source` 可选值：`"businessNo"`（默认，按商户号）、`"platformName"`（按平台名称）、`"phone"`（按手机号）。
+
+## Props
+
+```typescript
+type Source = 'businessNo' | 'platformName' | 'phone'
+
+interface EffectMerchantSelectProps {
+  className?: string
+  onChange?: (value?: string, name?: string) => void
+  value?: string
+  /** 搜索字段来源 */
+  source?: Source
+  disabled?: boolean
+  /** 选项标签展示模式 */
+  labelDisplayMode?: LabelDisplayMode
+}
+```
+
+| 属性             | 类型                                        | 必填 | 默认值           | 说明                                        |
+| ---------------- | ------------------------------------------- | ---- | ---------------- | ------------------------------------------- |
+| value            | `string`                                    | 否   | -                | 受控值（企业编号 enterpriseNo）             |
+| onChange         | `(value?: string, name?: string) => void`   | 否   | -                | 值变化回调，第二个参数为商户的 platformName |
+| source           | `'businessNo' \| 'platformName' \| 'phone'` | 否   | `'businessNo'`   | 初始搜索字段来源                            |
+| labelDisplayMode | `LabelDisplayMode`                          | 否   | `'platformName'` | 选项标签展示模式                            |
+| disabled         | `boolean`                                   | 否   | -                | 禁用状态                                    |
+| className        | `string`                                    | 否   | -                | 自定义样式类名                              |
+
+## 导出类型
+
+```typescript
+// 商户选项列表类型
+export type MerchantOptions = {
+  label: string
+  value: string
+  originalName: string
+  data?: MerchantListBus
+}[]
+
+// 标签展示模式
+export type LabelDisplayMode = 'platformName' | 'platformName-enterpriseNo'
+```
+
+> **注意**：`LabelDisplayMode` 定义在内部 `useMerchantOptions` 模块中，未从包入口直接导出。使用时直接传字面量 `'platformName'` 或 `'platformName-enterpriseNo'` 即可。
+
+## API 数据源
+
+- **内部 Hook**：`useMerchantOptions`（使用 SWR 缓存，`revalidateOnMount: false`）
+- **内部接口**：`apiService.merchantList`
+- **请求参数**：`{ businessNo?, name?, phone?, page: 1, pageSize: 20, labelDisplayMode }`
+- **可覆盖**：通过 `<ConfigProvider apiService={{ merchantList: customFn }}>` 替换默认实现
+
+### 搜索源切换逻辑
+
+组件搜索行为较特殊：
+
+1. 左侧有一个独立的 Select 下拉框用于切换搜索源（`sourceControl`）
+2. 切换搜索源时，已选值和选项列表会被清空
+3. 搜索使用 800ms 防抖延迟（比其他 Effect 选择器的 300ms 更长）
+4. 请求参数根据当前搜索源动态构建：`{ [sourceControl]: searchValue, labelDisplayMode }`
+
+```
+搜索源选项：
+- businessNo  → 按商户号搜索
+- platformName → 按商户平台名搜索
+- phone       → 按主账号手机号搜索
+```
+
+## 常见陷阱
+
+- ❌ 期望 `value` 是商户名——实际 value 是企业编号 `enterpriseNo`（string 类型）：
+  ```tsx
+  // value 不是商户名，而是企业编号
+  <EffectMerchantSelect value="某某商户" />
+  ```
+- ✅ 使用企业编号作为 value，通过 onChange 的第二个参数获取商户名：
+
+  ```tsx
+  <EffectMerchantSelect
+    value={enterpriseNo}
+    onChange={(value, name) => {
+      setEnterpriseNo(value) // 企业编号
+      setMerchantName(name) // 商户平台名
+    }}
+  />
+  ```
+
+- ❌ 搜索无结果时以为组件坏了——首次渲染不发起搜索请求（`revalidateOnMount: false`），需要用户输入触发
+- ✅ 如果需要默认展示选项，通过 `value` 传入企业编号，组件会自动发起反查请求
+
+- ❌ 切换搜索源后期望保留之前的选中值——切换时会清空值和选项
+- ✅ 在切换搜索源后重新搜索并选择
+
+- ❌ 接口报错时组件白屏——组件内部有 error 处理，会展示红色错误文本
+- ✅ 接口异常时检查 ConfigProvider 中 merchantList 配置是否正确
+
+## 相关组件
+
+| 场景       | 组件                | 说明                                  |
+| ---------- | ------------------- | ------------------------------------- |
+| API 配置   | `ConfigProvider`    | 提供 apiService.merchantList 接口实现 |
+| 类似选择器 | `EffectBrandSelect` | 相似的远程搜索选择器模式              |

package/skills/references/EffectReservoirSelect.md

@@ -0,0 +1,178 @@
+# EffectReservoirSelect
+
+> 库区选择器，依赖 `warehouseId` 获取库区列表，支持搜索和级联联动。同模块还导出 `EffectShelveSelect` 库位选择器。
+
+## 导入
+
+```tsx
+import { EffectReservoirSelect, EffectShelveSelect } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+```tsx
+import { EffectReservoirSelect } from '@xfe-repo/web-components'
+
+function MyForm() {
+  const [reservoirId, setReservoirId] = useState<number>()
+
+  return (
+    <EffectReservoirSelect
+      warehouseId={100}
+      value={reservoirId}
+      onChange={(value, name) => {
+        setReservoirId(value)
+        console.log('库区名称：', name)
+      }}
+    />
+  )
+}
+```
+
+## 进阶用法
+
+### 仓库 → 库区 → 库位三级联动
+
+```tsx
+import { EffectWarehouseSelect, EffectReservoirSelect, EffectShelveSelect } from '@xfe-repo/web-components'
+
+function WarehouseLocationPicker() {
+  const [warehouseId, setWarehouseId] = useState<number>()
+  const [reservoirId, setReservoirId] = useState<number>()
+  const [shelveCode, setShelveCode] = useState<string>()
+
+  return (
+    <div>
+      <EffectWarehouseSelect
+        value={warehouseId ? String(warehouseId) : undefined}
+        onChange={(value) => setWarehouseId(value ? Number(value) : undefined)}
+      />
+      <EffectReservoirSelect warehouseId={warehouseId} value={reservoirId} onChange={(value) => setReservoirId(value)} />
+      <EffectShelveSelect
+        warehouseId={warehouseId}
+        reservoirId={reservoirId}
+        value={shelveCode}
+        onChange={(value) => setShelveCode(value)}
+      />
+    </div>
+  )
+}
+```
+
+### 筛选异常库区
+
+```tsx
+<EffectReservoirSelect warehouseId={100} reservoirType="abnormal" />
+```
+
+## Props
+
+### EffectReservoirSelect Props
+
+```typescript
+type Props = {
+  className?: string
+  onChange?: (value?: number, name?: string) => void
+  value?: number
+  defaultValue?: string
+  disabled?: boolean
+  warehouseId?: number
+  reservoirType?: string
+}
+```
+
+| 属性          | 类型                      | 必填 | 默认值     | 说明                                                      |
+| ------------- | ------------------------- | ---- | ---------- | --------------------------------------------------------- |
+| value         | `number`                  | 否   | -          | 受控值（库区 ID）                                         |
+| defaultValue  | `string`                  | 否   | -          | 默认值                                                    |
+| onChange      | `(value?, name?) => void` | 否   | -          | 值变化回调，返回库区 ID 和名称                            |
+| warehouseId   | `number`                  | 否   | -          | **核心依赖**：仓库 ID，变更时重新加载库区列表并清空选中值 |
+| reservoirType | `string`                  | 否   | `'normal'` | 库区类型，`'normal'` 普通库区 / `'abnormal'` 异常库区     |
+| disabled      | `boolean`                 | 否   | -          | 禁用状态                                                  |
+| className     | `string`                  | 否   | -          | 自定义样式类名                                            |
+
+### EffectShelveSelect Props
+
+```typescript
+type Props = {
+  className?: string
+  onChange?: (value?: string, name?: string) => void
+  value?: string
+  defaultValue?: string
+  disabled?: boolean
+  warehouseId?: number
+  reservoirId?: number
+  valueType?: 'code' | 'id'
+}
+```
+
+| 属性         | 类型                      | 必填 | 默认值   | 说明                                          |
+| ------------ | ------------------------- | ---- | -------- | --------------------------------------------- |
+| value        | `string`                  | 否   | -        | 受控值（库位编码或 ID）                       |
+| defaultValue | `string`                  | 否   | -        | 默认值                                        |
+| onChange     | `(value?, name?) => void` | 否   | -        | 值变化回调                                    |
+| warehouseId  | `number`                  | 否   | -        | 仓库 ID                                       |
+| reservoirId  | `number`                  | 否   | -        | **核心依赖**：库区 ID，需同时传入 warehouseId |
+| valueType    | `'code' \| 'id'`          | 否   | `'code'` | 值类型：`code` 返回库位编码，`id` 返回库位 ID |
+| disabled     | `boolean`                 | 否   | -        | 禁用状态                                      |
+| className    | `string`                  | 否   | -        | 自定义样式类名                                |
+
+## API 数据源
+
+### EffectReservoirSelect
+
+- **内部接口**：`apiService.reservoirList`
+- **请求参数**：`{ page: 1, pageSize: 500, warehouseIdFilter: String(warehouseId), reservoirStateFilter: '1', reservoirType }`
+- **前置条件**：`warehouseId` 必须存在才会发起请求
+
+### EffectShelveSelect
+
+- **内部接口**：`apiService.shelveList`
+- **请求参数**：`{ page: 1, pageSize: 2000, warehouseId, reservoirId, status: 1 }`
+- **前置条件**：`warehouseId` 和 `reservoirId` 都必须存在才会发起请求
+
+## 依赖 Props
+
+| 依赖属性    | 类型     | 来源                         | 说明                      |
+| ----------- | -------- | ---------------------------- | ------------------------- |
+| warehouseId | `number` | EffectWarehouseSelect 的输出 | 库区选择器必须依赖仓库 ID |
+| reservoirId | `number` | EffectReservoirSelect 的输出 | 库位选择器必须依赖库区 ID |
+
+## 子组件
+
+| 组件                    | 说明       |
+| ----------------------- | ---------- |
+| `EffectReservoirSelect` | 库区选择器 |
+| `EffectShelveSelect`    | 库位选择器 |
+
+## 常见陷阱
+
+- ❌ 不传 `warehouseId` 就使用 EffectReservoirSelect：
+  ```tsx
+  // 没有 warehouseId 时不会发起请求，选择器显示 "请先选择仓库"
+  ```
+- ✅ 确保 `warehouseId` 存在后再渲染或传入：
+
+  ```tsx
+  <EffectReservoirSelect warehouseId={warehouseId} />
+  ```
+
+- ❌ `warehouseId` 变更后期望保留之前选中的库区值：
+  ```tsx
+  // warehouseId 变更时组件内部会自动清空 value 并触发 onChange()
+  ```
+- ✅ 在 `onChange` 中正确处理 `undefined` 值
+
+- ❌ EffectShelveSelect 只传 reservoirId 不传 warehouseId：
+  ```tsx
+  // 两个 ID 都存在时才会发起请求
+  ```
+- ✅ 同时传入 warehouseId 和 reservoirId
+
+## 相关组件
+
+| 场景     | 组件                    | 说明                                                      |
+| -------- | ----------------------- | --------------------------------------------------------- |
+| 级联上游 | `EffectWarehouseSelect` | 提供 warehouseId                                          |
+| 级联下游 | `EffectShelveSelect`    | 使用 reservoirId 获取库位列表                             |
+| API 配置 | `ConfigProvider`        | 提供 `apiService.reservoirList` / `apiService.shelveList` |

package/skills/references/EffectScopeSelect.md

@@ -0,0 +1,220 @@
+# EffectScopeSelect
+
+> 商品范围选择复合组件，级联聚合 分类→品牌→系列→SPU→SKU 五级选择器，通过 `scopeLevel` 控制显示深度。
+
+## 导入
+
+```tsx
+import { EffectScopeSelect, ScopeLevelEnum } from '@xfe-repo/web-components'
+import type { ScopeSelectValueType, ScopeSelectProps } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+最常见用法 — 在 Form.Item 中使用，value/onChange 由 Form 自动注入：
+
+```tsx
+<Form.Item name="scope" label="适用范围">
+  <EffectScopeSelect categoryChangeOnSelect />
+</Form.Item>
+```
+
+### 独立受控模式
+
+```tsx
+import { EffectScopeSelect, ScopeLevelEnum } from '@xfe-repo/web-components'
+import type { ScopeSelectValueType } from '@xfe-repo/web-components'
+
+function MyForm() {
+  const [scope, setScope] = useState<ScopeSelectValueType>()
+
+  return (
+    <EffectScopeSelect
+      value={scope}
+      onChange={(value) => {
+        console.log(value)
+        // { categoryIds: [1, 11], brandId: 100, seriesId: 200, spuId: 300, skuId: 400 }
+        setScope(value)
+      }}
+    />
+  )
+}
+```
+
+## 进阶用法
+
+### 限制显示层级
+
+使用 `scopeLevel` 控制选择器显示到哪一级。例如只需要选到品牌：
+
+```tsx
+<EffectScopeSelect
+  scopeLevel={ScopeLevelEnum.BRAND} // 只显示：分类 + 品牌
+  onChange={(value) => {
+    // value: { categoryIds: [1, 11], brandId: 100 }
+  }}
+/>
+```
+
+### 设置必选层级
+
+使用 `requireLevel` 标记哪些层级为必填（显示红色星号），并控制 onChange 的触发时机。当选择达到 `requireLevel` 指定的层级时才触发 `onChange`。
+
+```tsx
+<EffectScopeSelect
+  scopeLevel={ScopeLevelEnum.SKU}
+  requireLevel={ScopeLevelEnum.BRAND} // 分类和品牌为必选
+  onChange={(value) => {
+    // 选择品牌后即触发 onChange
+  }}
+/>
+```
+
+### 分类选择即触发
+
+默认分类需选到叶子节点才触发下一级。设置 `categoryChangeOnSelect` 后，选择任意层级即可触发。
+
+```tsx
+<EffectScopeSelect categoryChangeOnSelect onChange={(value) => setScope(value)} />
+```
+
+### 受控模式
+
+```tsx
+const [scope, setScope] = useState<ScopeSelectValueType>({
+  categoryIds: [1, 11, 111],
+  brandId: 100,
+})
+
+<EffectScopeSelect
+  value={scope}
+  onChange={setScope}
+/>
+```
+
+### ScopeSelectValueType ↔ 后端 DTO 转换
+
+```tsx
+// 前端 → 后端
+const toDTO = (scope: ScopeSelectValueType) => ({
+  categoryFst: scope.categoryIds?.[0],
+  categoryScd: scope.categoryIds?.[1],
+  categoryTrd: scope.categoryIds?.[2],
+  brandId: scope.brandId,
+  seriesId: scope.seriesId,
+})
+
+// 后端 → 前端
+const fromDTO = (dto) => ({
+  categoryIds: [dto.categoryFst, dto.categoryScd, dto.categoryTrd].filter(Boolean),
+  brandId: dto.brandId,
+  seriesId: dto.seriesId,
+})
+```
+
+## 使用提示
+
+> 💡 `categoryChangeOnSelect` 在所有业务场景中均有使用，建议默认传入。
+
+## Props
+
+```typescript
+export type ScopeSelectProps = {
+  value?: ScopeSelectValueType
+  defaultValue?: ScopeSelectValueType
+  scopeLevel?: ScopeLevelEnum
+  requireLevel?: ScopeLevelEnum
+  categoryChangeOnSelect?: boolean
+  onChange?: (value?: ScopeSelectValueType) => void
+}
+```
+
+| 属性                   | 类型                   | 必填 | 默认值                        | 说明                                                 |
+| ---------------------- | ---------------------- | ---- | ----------------------------- | ---------------------------------------------------- |
+| value                  | `ScopeSelectValueType` | 否   | -                             | 受控值                                               |
+| defaultValue           | `ScopeSelectValueType` | 否   | -                             | 默认值                                               |
+| scopeLevel             | `ScopeLevelEnum`       | 否   | `ScopeLevelEnum.SKU` (5)      | 控制显示到哪一级选择器                               |
+| requireLevel           | `ScopeLevelEnum`       | 否   | `ScopeLevelEnum.CATEGORY` (1) | 必填层级标记（显示星号），同时控制 onChange 触发时机 |
+| categoryChangeOnSelect | `boolean`              | 否   | -                             | 分类选择是否无需选到叶子节点即可触发                 |
+| onChange               | `(value?) => void`     | 否   | -                             | 值变化回调，选择达到 requireLevel 时触发             |
+
+## 导出类型
+
+```typescript
+// 选择结果值类型
+export type ScopeSelectValueType = {
+  categoryIds?: number[] // 分类路径 ID 数组
+  brandId?: number // 品牌 ID
+  seriesId?: number // 系列 ID
+  spuId?: number // SPU ID
+  skuId?: number // SKU ID
+}
+
+// 层级枚举
+export enum ScopeLevelEnum {
+  CATEGORY = 1, // 分类
+  BRAND = 2, // 品牌
+  SERIES = 3, // 系列
+  SPU = 4, // SPU
+  SKU = 5, // SKU
+}
+```
+
+## 子组件
+
+EffectScopeSelect 内部组合了以下组件，按级联顺序渐进显示：
+
+| 层级 | 内部组件                | 显示条件                     | 数据依赖                    |
+| ---- | ----------------------- | ---------------------------- | --------------------------- |
+| 1    | `EffectCategoryCascade` | 始终显示                     | 无                          |
+| 2    | `EffectBrandSelect`     | `scopeLevel >= 2` 且已选分类 | `categoryId`（分类末级 ID） |
+| 3    | `EffectSeriesSelect`    | `scopeLevel >= 3` 且已选品牌 | `categoryId` + `brandId`    |
+| 4    | `EffectSpuSelect`       | `scopeLevel >= 4` 且已选系列 | `categoryId` + `seriesId`   |
+| 5    | `EffectSkuSelect`       | `scopeLevel >= 5` 且已选 SPU | `categoryId` + `spuId`      |
+
+> 每一级的显示取决于上一级是否已选择有效值（非 undefined/falsy），上一级变更时下级自动清空。
+
+## 常见陷阱
+
+- ❌ 混淆 `scopeLevel` 和 `requireLevel`：
+  ```tsx
+  // scopeLevel 控制「显示哪些选择器」
+  // requireLevel 控制「哪些是必填的」并影响 onChange 触发时机
+  <EffectScopeSelect scopeLevel={ScopeLevelEnum.SPU} requireLevel={ScopeLevelEnum.SKU} />
+  // 这会导致 onChange 永远不触发：因为 SKU 选择器不会显示（scopeLevel < SKU）
+  ```
+- ✅ 确保 `requireLevel <= scopeLevel`：
+
+  ```tsx
+  <EffectScopeSelect scopeLevel={ScopeLevelEnum.SPU} requireLevel={ScopeLevelEnum.BRAND} />
+  ```
+
+- ❌ 期望 `onChange` 在每次选择时都触发：
+  ```tsx
+  // 实际上只有在选择达到 requireLevel 指定的层级时才会触发
+  ```
+- ✅ 如需在每次选择时都触发，将 `requireLevel` 设为 `ScopeLevelEnum.CATEGORY`（默认值）
+
+- ❌ 当已经使用 EffectScopeSelect 时又单独使用内部的 EffectCategoryCascade、EffectBrandSelect 等
+- ✅ EffectScopeSelect 已内部集成所有级联组件的联动逻辑，直接使用即可
+
+- ⚠️ Form.List 动态行中使用时，需添加自定义 validator 防止重复：
+  ```tsx
+  validator: (_, value) => {
+    const key = JSON.stringify(value)
+    const isDup = allRows.filter((r) => JSON.stringify(r) === key).length > 1
+    return isDup ? Promise.reject('范围重复') : Promise.resolve()
+  }
+  ```
+
+## 相关组件
+
+| 场景     | 组件                    | 说明                                                  |
+| -------- | ----------------------- | ----------------------------------------------------- |
+| 分类选择 | `EffectCategoryCascade` | 内部使用，单独使用时参见其文档                        |
+| 品牌选择 | `EffectBrandSelect`     | 内部使用，单独使用时参见其文档                        |
+| 系列选择 | `EffectSeriesSelect`    | 内部使用，提供系列级选择                              |
+| SPU 选择 | `EffectSpuSelect`       | 内部使用，提供 SPU 级选择                             |
+| SKU 选择 | `EffectSkuSelect`       | 内部使用，提供 SKU 级选择                             |
+| API 配置 | `ConfigProvider`        | 所有内部 Effect 组件依赖 ConfigProvider 提供 API 服务 |
+| 弹窗使用 | `WithModal`             | 常在弹窗中使用商品范围选择                            |