@xfe-repo/web-components 1.6.2 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfe-repo/web-components",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "sideEffects": [
@@ -20,7 +20,8 @@
     "./dist/index.css": "./dist/index.css"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",
@@ -61,8 +62,8 @@
     "react-dom": "18.2.0",
     "react-use": "^17.5.1",
     "swr": "^2.2.5",
-    "@xfe-repo/web-router": "1.6.0",
     "@xfe-repo/web-micro": "1.6.0",
+    "@xfe-repo/web-router": "1.6.0",
     "@xfe-repo/web-utils": "1.6.0",
     "@xfe-repo/web-service": "1.6.0"
   },

package/skills/GUIDE.md

@@ -0,0 +1,78 @@
+# 组件 Skill Reference 编写指南
+
+> 配合 TEMPLATE.md 使用。本文件标注每个组件需要包含模板中的哪些**条件章节**。
+> 所有组件都需要：导入、基本用法、Props。以下仅标注额外需要的章节。
+
+## 条件章节速查矩阵
+
+| 组件                     | 进阶用法                | 导出类型                                | API数据源                 | 依赖Props              | Ref方法           | 子组件                       | 常见陷阱    | 相关组件            |
+| ------------------------ | ----------------------- | --------------------------------------- | ------------------------- | ---------------------- | ----------------- | ---------------------------- | ----------- | ------------------- |
+| **Effect 副作用选择器**  |                         |                                         |                           |                        |                   |                              |             |                     |
+| EffectAddressCascade     |                         | ✅ SelectItem                           | ✅ commonAddressList      |                        |                   |                              | ✅          |                     |
+| EffectBrandSelect        | ✅ 多选/分类过滤        | ✅ BrandValueType, BrandOptions         | ✅ useBrandOptions        | ✅ categoryId          |                   |                              | ✅          | ✅ ScopeSelect      |
+| EffectBrandTransfer      |                         | ✅ TransferValueType                    | ✅ useBrandOptions        | ✅ categoryId          |                   |                              | ✅          |                     |
+| EffectCategoryCascade    | ✅ 多选/获取原始数据    | ✅ TreeValueType 等6个                  | ✅ useCategoryTree        |                        |                   |                              | ✅          | ✅ 级联起点         |
+| EffectFileUpload         | ✅ 自动上传/手动上传    | ✅ SimpleFileData, UploadResult         | ✅ uploadUploadFile       |                        | ✅ handleUpload等 | ✅ Group                     | ✅          | ✅ WithFilePanel    |
+| EffectLabelSelect        | ✅ 自定义数据源         | ✅ SelectOptionItem, LabelDic           | ✅ 可自定义               |                        |                   |                              | ✅          |                     |
+| EffectMerchantSelect     | ✅ 搜索源切换           | ✅ MerchantOptions                      | ✅ useMerchantOptions     |                        |                   |                              | ✅          |                     |
+| EffectReservoirSelect    |                         |                                         | ✅ reservoirList          | ✅ warehouseId         |                   |                              | ✅          | ✅ WarehouseSelect  |
+| EffectScopeSelect        | ✅ scopeLevel控制       | ✅ ScopeSelectValueType, ScopeLevelEnum |                           |                        |                   | ✅ 内含5个Effect             | ✅          |                     |
+| EffectSeriesSelect       |                         |                                         | ✅ useSeriesOptions       | ✅ categoryId, brandId |                   |                              | ✅          | ✅ 级联链           |
+| EffectSeriesSelectV2     |                         |                                         | ✅ seriesList             | ✅ categoryId, brandId |                   |                              | ✅          | ✅ 级联链           |
+| EffectSkuRecognize       |                         | ✅ EffectSkuRecognizeProps              | ✅ productImageSpuSkuList | ✅ image(必填)         |                   |                              | ✅          |                     |
+| EffectSkuSelect          |                         | ✅ ValueType, ItemOption                | ✅ useSkuOptions          | ✅ categoryId~spuId    |                   |                              | ✅          | ✅ 级联链           |
+| EffectSkuTable           |                         | ✅ EffectSkuTableProps                  |                           |                        |                   | ✅ 联动表格                  | ✅          |                     |
+| EffectSpuSelect          |                         |                                         | ✅ useSpuOptions          | ✅ categoryId~seriesId |                   |                              | ✅          | ✅ 级联链           |
+| EffectStaffSelect        |                         |                                         | ✅ businessList           | ✅ deptId(可选)        |                   |                              |             |                     |
+| EffectWarehouseSelect    |                         | ✅ WarehouseOption                      | ✅ useStoreOptions        |                        |                   |                              | ✅          | ✅ ReservoirSelect  |
+| EffectWithFilePanel      |                         |                                         |                           |                        |                   | ✅ 包装FileUpload            | ✅          | ✅ FileUpload       |
+| **容器/高阶组件**        |                         |                                         |                           |                        |                   |                              |             |                     |
+| WithModal                | ✅ 异步保存/外控visible | ✅ WithModalProps                       |                           |                        |                   |                              | ✅          |                     |
+| WithPanel                | ✅ 异步保存/外控visible | ✅ WithPanelProps                       |                           |                        |                   |                              | ✅          |                     |
+| MultiWindow              | ✅ 缓存控制             | ✅ PagePathType等4个                    |                           |                        | ✅ contentRef     | ✅ Contents                  | ✅          |                     |
+| **增强 Ant Design 组件** |                         |                                         |                           |                        |                   |                              |             |                     |
+| CInput                   |                         | ✅ CInputProps等3个                     |                           |                        | ✅ InputRef       | ✅ .TextArea/.Search/.Group  | ✅ autoTrim |                     |
+| CTable                   | ✅ 拖拽排序             | ✅ CTableProps, TableDragEndEvent       |                           |                        |                   | ✅ .Column/.DragHandle       | ✅          |                     |
+| OSSImage                 | ✅ 预览组               | ✅ OSSImageProps                        |                           |                        |                   | ✅ .PreviewGroup/.ModalGroup | ✅          |                     |
+| **展示/功能组件**        |                         |                                         |                           |                        |                   |                              |             |                     |
+| Clock                    |                         | ✅ ClockProps + formatClock             |                           |                        |                   |                              |             |                     |
+| Countdown                | ✅ date/second模式      | ✅ CountdownProps + formatDate          |                           |                        |                   |                              |             |                     |
+| Counter                  |                         | ✅ CounterProps                         |                           |                        |                   |                              |             |                     |
+| Currency                 |                         | ✅ CurrencyUnit, CurrencyProps          |                           |                        |                   |                              | ✅ unit换算 |                     |
+| FileUpload               | ✅ 多文件               | ✅ ModifyFileData                       |                           |                        |                   |                              |             | ✅ EffectFileUpload |
+| Iconfont                 |                         |                                         |                           |                        |                   |                              |             |                     |
+| Loading                  |                         |                                         |                           |                        |                   |                              |             |                     |
+| PrivacyField             |                         |                                         |                           |                        |                   |                              | ✅          |                     |
+| QRCode                   | ✅ SSE轮询              | ✅ QRCodeStatus + useSseQrcode          |                           |                        |                   |                              |             |                     |
+| RichTextEditor           | ✅ 图片插入             | ✅ RichTextEditorProps                  |                           |                        |                   |                              | ✅          | ✅ ConfigProvider   |
+| SearchForm               |                         | ✅ SearchFormProps                      |                           |                        |                   | ✅ Content                   |             |                     |
+| SearchList               |                         | ✅ SearchListProps                      |                           |                        |                   |                              |             |                     |
+| **配置/上下文**          |                         |                                         |                           |                        |                   |                              |             |                     |
+| ConfigProvider           | ✅ API覆盖/主题         | ✅ IApiPayload, IConfigContext          |                           |                        |                   |                              | ✅          | ✅ 全局依赖         |
+| **工具模块**             |                         |                                         |                           |                        |                   |                              |             |                     |
+| ApiService               | ✅ 各方法签名           | ✅ IApiService(全量)                    |                           |                        |                   |                              |             | ✅ ConfigProvider   |
+| commonFn                 | ✅ 各函数用法           | ✅ 函数签名+常量                        |                           |                        |                   |                              |             |                     |
+
+## 维护优先级
+
+> 全部 40 个组件文档已完成编写，并经过 platform + dashboard + erp 三项目业务用法审计。
+> 以下优先级适用于后续组件新增或文档维护场景。
+
+### 高优先级维护（业务使用频率最高、Agent 出错影响最大）
+
+1. **CInput** (253 次) — 最高频组件，搜索栏 + Form.Item 是核心模式
+2. **OSSImage** (93 次) — Table 列渲染 + 空值防御是关键
+3. **WithModal** (82 次) — Form 三件套 + With{Action}Modal 封装范式
+4. **SearchList** (69 次) — dashboard 核心，noStyle + div 结构约定
+5. **CTable** (52 次) — TypeTable 别名 + rowSelection + getCTable 反模式
+6. **EffectCategoryCascade** (40 次) — 级联链起点，changeOnSelect 几乎必传
+7. **EffectBrandSelect** (39 次) — key={categoryId} 强制刷新是关键陷阱
+8. **EffectFileUpload** (33 次) — Form.Item 集成 + handleUpload Ref + Promise.all
+
+### 中优先级维护
+
+9-22. 其余使用频率 3-25 次的组件，详见审计报告
+
+### 低优先级
+
+未在业务中使用的组件：Clock、Counter、FileUpload、Iconfont、QRCode 等

package/skills/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: xfe-web-components
+description: >-
+  @xfe-repo/web-components 组件库的完整使用指南。包含 40 个 React 组件的 Props 类型定义、
+  代码示例、常见陷阱和组件间联动关系。当使用 EffectBrandSelect、EffectCategoryCascade、
+  WithModal、EffectFileUpload、EffectScopeSelect、CTable、SearchForm、OSSImage、
+  CInput、SearchList、Currency、Loading 等组件时自动激活。
+  触发关键词：xfe-repo、web-components、Effect 组件、品牌选择、分类级联、文件上传、弹窗、
+  侧边栏、SKU 选择、商户选择、Form.Item、搜索表单、表格。
+---
+
+# @xfe-repo/web-components 使用指南
+
+本 Skill 提供 `@xfe-repo/web-components` 组件库的完整 API 参考文档。
+
+## 通用规范
+
+- 所有组件从 `@xfe-repo/web-components` 统一导入
+- 类型从同一包导入：`import type { XxxProps } from '@xfe-repo/web-components'`
+- 所有 Effect 组件（`Effect` 前缀）内部会发起 API 请求，依赖 `ConfigProvider` 提供的 `apiService`
+- 业务项目通常已在入口处配置了 `ConfigProvider`，无需重复包裹
+- **Form.Item 集成是绝对主流**：几乎所有组件在业务中都通过 `<Form.Item name="xxx">` 使用，value/onChange 由 Form 自动注入，无需手动管理
+- Effect 选择器级联依赖变化时，使用 `key={依赖值}` 强制重新挂载刷新数据
+
+## 组件索引
+
+按需查阅 `references/` 中的组件文档：
+
+| 组件                  | 文档                                  | 说明                             |
+| --------------------- | ------------------------------------- | -------------------------------- |
+| ConfigProvider        | `references/ConfigProvider.md`        | 全局配置，所有 Effect 组件的依赖 |
+| EffectBrandSelect     | `references/EffectBrandSelect.md`     | 品牌下拉选择器                   |
+| EffectCategoryCascade | `references/EffectCategoryCascade.md` | 分类级联选择器                   |
+| EffectFileUpload      | `references/EffectFileUpload.md`      | 文件上传（支持 Ref）             |
+| WithModal             | `references/WithModal.md`             | 高阶弹窗组件                     |
+| EffectScopeSelect     | `references/EffectScopeSelect.md`     | 商品范围选择（复合组件）         |
+| EffectAddressCascade  | `references/EffectAddressCascade.md`  | 地址级联选择                     |
+| EffectBrandTransfer   | `references/EffectBrandTransfer.md`   | 品牌穿梭框                       |
+| EffectLabelSelect     | `references/EffectLabelSelect.md`     | 标签维度双选择器                 |
+| EffectMerchantSelect  | `references/EffectMerchantSelect.md`  | 商户选择器                       |
+| EffectReservoirSelect | `references/EffectReservoirSelect.md` | 库区选择器                       |
+| EffectSeriesSelect    | `references/EffectSeriesSelect.md`    | 系列选择器                       |
+| EffectSeriesSelectV2  | `references/EffectSeriesSelectV2.md`  | 系列多选器 V2                    |
+| EffectSkuRecognize    | `references/EffectSkuRecognize.md`    | SKU 图片识别                     |
+| EffectSkuSelect       | `references/EffectSkuSelect.md`       | SKU 选择器                       |
+| EffectSkuTable        | `references/EffectSkuTable.md`        | SKU 联动表格                     |
+| EffectSpuSelect       | `references/EffectSpuSelect.md`       | SPU 选择器                       |
+| EffectStaffSelect     | `references/EffectStaffSelect.md`     | 员工选择器                       |
+| EffectWarehouseSelect | `references/EffectWarehouseSelect.md` | 仓库选择器                       |
+| EffectWithFilePanel   | `references/EffectWithFilePanel.md`   | 文件上传面板                     |
+| WithPanel             | `references/WithPanel.md`             | 高阶侧边栏组件                   |
+| CInput                | `references/CInput.md`                | 增强输入框（自动 trim）          |
+| CTable                | `references/CTable.md`                | 拖拽排序表格                     |
+| CVideo                | `references/CVideo.md`                | 视频播放器                       |
+| OSSImage              | `references/OSSImage.md`              | OSS 图片组件                     |
+| MultiWindow           | `references/MultiWindow.md`           | 多窗口 Tab 容器                  |
+| SearchForm            | `references/SearchForm.md`            | 搜索表单                         |
+| SearchList            | `references/SearchList.md`            | 搜索列表容器                     |
+| FileUpload            | `references/FileUpload.md`            | 基础文件上传                     |
+| RichTextEditor        | `references/RichTextEditor.md`        | 富文本编辑器                     |
+| QRCode                | `references/QRCode.md`                | 二维码组件                       |
+| Clock                 | `references/Clock.md`                 | 实时时钟                         |
+| Countdown             | `references/Countdown.md`             | 倒计时                           |
+| Counter               | `references/Counter.md`               | 计数器                           |
+| Currency              | `references/Currency.md`              | 金额展示                         |
+| Iconfont              | `references/Iconfont.md`              | 自定义图标                       |
+| Loading               | `references/Loading.md`               | 加载状态                         |
+| PrivacyField          | `references/PrivacyField.md`          | 隐私脱敏字段                     |
+| commonFn              | `references/commonFn.md`              | 通用工具函数                     |
+| ApiService            | `references/ApiService.md`            | API 服务接口定义                 |
+
+## 常见陷阱
+
+- ❌ 直接在未包裹 `ConfigProvider` 的环境中使用 Effect 组件 — 会因缺少 `apiService` 报错
+- ❌ 给 Effect 选择器组件传 `options` prop — 数据由组件内部 API 获取，不接受外部 options
+- ❌ `WithModal` 的 `onSave` 返回 `false` 不能阻止关闭 — 需要返回 `Promise<false>` 或显式 `return false`
+- ❌ `EffectFileUpload` 不调用 `ref.current.handleUpload()` 就提交表单 — 文件不会真正上传
+- ✅ Effect 组件的级联依赖链：分类 → 品牌 → 系列 → SPU → SKU，上游变化时下游自动重置

package/skills/TEMPLATE.md

@@ -0,0 +1,170 @@
+# 组件 Skill Reference 模板
+
+> 本文件是编写组件 reference 文档的统一模板。
+> 编写时请删除所有 `<!-- ... -->` 注释和不适用的章节。
+> 文件命名：`references/{ComponentName}.md`
+
+---
+
+# {ComponentName}
+
+> {一句话功能描述，说明组件做什么、解决什么问题}
+
+## 导入
+
+```tsx
+import { ComponentName } from '@xfe-repo/web-components'
+// 如有额外导出的类型
+import type { ComponentNameProps, OtherType } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+<!-- 最简可运行示例，覆盖最常见场景。绝大多数组件在业务中通过 Form.Item 使用 -->
+
+### Form.Item 集成（最常用）
+
+```tsx
+<Form.Item name="fieldName" label="字段名" rules={[{ required: true }]}>
+  <ComponentName placeholder="请选择" />
+</Form.Item>
+```
+
+### 独立受控模式
+
+```tsx
+<ComponentName value={value} onChange={(val) => setValue(val)} />
+```
+
+## 进阶用法
+
+<!-- 如组件有多个重要使用场景，按场景分小节。不重要的场景可省略 -->
+
+### {场景名称}
+
+<!-- 说明为什么需要这种用法，1-2 句话 -->
+
+```tsx
+// 代码示例
+```
+
+## Props
+
+<!-- 完整 Props 类型定义，从源码复制 -->
+
+```typescript
+interface ComponentNameProps {
+  // ...
+}
+```
+
+<!-- Props 表格，只列出开发者需要关注的属性。继承自 Antd 的通用属性（如 className、style、disabled）可省略或简述 -->
+
+| 属性     | 类型                      | 必填 | 默认值 | 说明       |
+| -------- | ------------------------- | ---- | ------ | ---------- |
+| value    | `string`                  | 否   | -      | 受控值     |
+| onChange | `(value: string) => void` | 否   | -      | 值变化回调 |
+
+## 导出类型
+
+<!-- 【条件章节】仅当组件导出了额外类型时包含 -->
+
+```typescript
+// 列出所有从该组件导出的类型
+export type SomeType = {
+  /* ... */
+}
+```
+
+## API 数据源
+
+<!-- 【条件章节】仅 Effect 副作用组件需要 -->
+<!-- 说明组件内部调用了哪个 API，数据从哪里来 -->
+
+- **内部接口**：`apiService.{methodName}`
+- **可覆盖**：通过 `<ConfigProvider apiService={{ methodName: customFn }}>` 替换默认实现
+
+## 依赖 Props
+
+<!-- 【条件章节】仅当组件的数据或行为依赖其他组件传入的 ID 时包含 -->
+<!-- 典型场景：EffectSeriesSelect 依赖 categoryId + brandId -->
+
+| 依赖属性   | 类型     | 来源                         | 说明               |
+| ---------- | -------- | ---------------------------- | ------------------ |
+| categoryId | `number` | EffectCategoryCascade 的输出 | 不传则加载全部数据 |
+| brandId    | `number` | EffectBrandSelect 的输出     | 不传则不过滤品牌   |
+
+### 联动示例
+
+<!-- 展示多个组件如何配合使用，推荐使用 Form.useWatch -->
+
+```tsx
+const categoryIds = Form.useWatch('categoryIds', form)
+const categoryId = categoryIds?.at(-1)
+const brandId = Form.useWatch('brandId', form)
+
+<Form.Item name="categoryIds" label="分类">
+  <EffectCategoryCascade changeOnSelect />
+</Form.Item>
+<Form.Item name="brandId" label="品牌">
+  <EffectBrandSelect categoryId={categoryId} key={categoryId} />
+</Form.Item>
+<Form.Item name="seriesId" label="系列">
+  <EffectSeriesSelect categoryId={categoryId} brandId={brandId} key={`${categoryId}-${brandId}`} />
+</Form.Item>
+```
+
+## Ref 方法
+
+<!-- 【条件章节】仅当组件通过 forwardRef + useImperativeHandle 暴露方法时包含 -->
+
+```typescript
+interface ComponentNameRef {
+  someMethod: () => void
+}
+```
+
+### 使用方式
+
+```tsx
+const ref = useRef<ComponentNameRef>(null)
+
+<ComponentName ref={ref} />
+
+// 调用
+ref.current?.someMethod()
+```
+
+## 子组件
+
+<!-- 【条件章节】仅复合组件包含（如 CInput.TextArea、OSSImage.PreviewGroup） -->
+
+### ComponentName.SubComponent
+
+> {子组件功能描述}
+
+```tsx
+<ComponentName.SubComponent prop1="value" />
+```
+
+| 属性  | 类型     | 说明 |
+| ----- | -------- | ---- |
+| prop1 | `string` | ...  |
+
+## 常见陷阱
+
+<!-- 列出使用该组件容易犯的错误，格式统一为：❌ 错误 → ✅ 正确 -->
+
+- ❌ `<ComponentName value="string" />` — value 类型是 number，不是 string
+- ✅ `<ComponentName value={123} />`
+
+## 相关组件
+
+<!-- 【条件章节】仅当该组件常与库中其他组件搭配使用时包含 -->
+<!-- 表格格式更利于 Agent 快速解析依赖关系 -->
+
+| 场景         | 组件                    | 说明                                      |
+| ------------ | ----------------------- | ----------------------------------------- |
+| 弹窗中使用   | `WithModal`             | 用 handleElement 触发，在弹窗内渲染本组件 |
+| API 数据覆盖 | `ConfigProvider`        | 通过 apiService prop 替换默认 API 实现    |
+| 级联上游     | `EffectCategoryCascade` | 提供 categoryId 作为本组件的过滤条件      |

package/skills/references/ApiService.md

@@ -0,0 +1,136 @@
+# ApiService
+
+> API 服务接口定义和默认实现（saasApiService），定义了所有 Effect 组件内部调用的 BFF 接口方法。
+
+## 导入
+
+```tsx
+import { saasApiService } from '@xfe-repo/web-components'
+import type { IApiService } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+`ApiService` 通常不直接使用，而是通过 `ConfigProvider` 的 `apiService` 属性注入，Effect 组件内部通过 `useRequestConfig` Hook 获取。
+
+```tsx
+import { ConfigProvider } from '@xfe-repo/web-components'
+
+// 使用默认的 saasApiService（默认行为，无需显式传入）
+;<ConfigProvider apiPayload={payload}>
+  <App />
+</ConfigProvider>
+```
+
+## 进阶用法
+
+### 自定义部分接口
+
+```tsx
+import { ConfigProvider } from '@xfe-repo/web-components'
+import type { IApiService } from '@xfe-repo/web-components'
+
+const customService: Partial<IApiService> = {
+  brandComboBox: async (params, config) => {
+    return await myApi.getBrands(params)
+  },
+}
+
+<ConfigProvider apiService={customService} apiPayload={payload}>
+  <App />
+</ConfigProvider>
+```
+
+### 在组件中获取 API 服务
+
+```tsx
+import { useRequestConfig } from '@xfe-repo/web-components'
+
+function MyComponent() {
+  const { apiService, config } = useRequestConfig()
+
+  const fetchBrands = async () => {
+    const result = await apiService.brandComboBox({}, config)
+    console.log(result)
+  }
+}
+```
+
+## 接口定义
+
+### IApiService
+
+```typescript
+export interface IApiService {
+  // 商品相关
+  categoryListToTree: Request<InQueryCategoryListToTree, OutListToTreeCategoryDto> // 分类树
+  brandComboBox: Request<InQueryBrandComboBox, OutComboBoxBrandDto> // 品牌下拉
+  seriesComboBox: Request<InQuerySeriesComboBox, OutComboBoxSeriesDto> // 系列下拉
+  seriesList: Request<InQuerySeriesList, OutListSeriesDto> // 系列列表
+  skuFindOne: Request<InPathSkuFindOne, OutFindOneSkuDto> // SKU 详情
+  skuListV2: Request<InQuerySkuListV2, OutListSkuV2Dto> // SKU 列表
+  spuList: Request<InQuerySpuList, OutListSpuDto> // SPU 列表
+  productImageSpuSkuList: Request<InQueryProductImageSpuSkuList, OutListProductImageSpuSkuDto> // 商品图片列表
+
+  // 通用服务
+  uploadUploadFile: Request<InUploadFileDto, OutUploadFileDto> // 文件上传
+  uploadRemoteCreate: Request<InRemoteCreateDto, OutRemoteCreateDto> // 远程文件创建
+  commonAddressList: Request<InPathCommonAddressList, OutAddressListDto> // 地址列表
+
+  // 仓库相关
+  storeComboBox: Request<InPathStoreComboBox & InQueryStoreComboBox, OutComboBoxWarehouseStoreDto> // 仓库下拉
+  reservoirList: Request<InQueryReservoirList, OutListReservoirDto> // 库区列表
+  shelveList: Request<InQueryShelveList, OutShelveListV2Dto> // 货架列表
+
+  // 业务相关
+  merchantList: Request<InMerchantListBusDto, OutMerchantListBusDto> // 商户列表
+  businessList: Request<InQueryBusinessList, OutListBusDto> // 业务线列表
+}
+```
+
+### saasApiService
+
+默认的 SaaS BFF 服务实现，包含所有接口方法：
+
+```typescript
+export const saasApiService: IApiService
+```
+
+### useRequestConfig
+
+内部 Hook，返回合并后的请求配置、API 载荷和 API 服务实例。
+
+```typescript
+type OutUseRequestConfig = {
+  config: BFFRequestConfig // 合并后的请求配置（含 baseURL、headers、jwt 等）
+  apiPayload: Partial<IApiPayload>
+  apiService: IApiService
+}
+
+export const useRequestConfig: (config?: BFFRequestConfig) => OutUseRequestConfig
+```
+
+> `useRequestConfig` 必须在 `ConfigProvider` 内部使用，否则会抛出错误。
+
+## 接口与 Effect 组件映射
+
+| 接口方法                        | 依赖的 Effect 组件                           |
+| ------------------------------- | -------------------------------------------- |
+| `categoryListToTree`            | `EffectCategoryCascade`                      |
+| `brandComboBox`                 | `EffectBrandSelect`、`EffectBrandTransfer`   |
+| `seriesComboBox` / `seriesList` | `EffectSeriesSelect`、`EffectSeriesSelectV2` |
+| `skuFindOne` / `skuListV2`      | `EffectSkuSelect`、`EffectSkuTable`          |
+| `spuList`                       | `EffectSpuSelect`                            |
+| `uploadUploadFile`              | `EffectFileUpload`、`RichTextEditor`         |
+| `uploadRemoteCreate`            | `FileUpload`（remote 模式）                  |
+| `commonAddressList`             | `EffectAddressCascade`                       |
+| `storeComboBox`                 | `EffectWarehouseSelect`                      |
+| `reservoirList` / `shelveList`  | `EffectReservoirSelect`                      |
+| `merchantList`                  | `EffectMerchantSelect`                       |
+| `businessList`                  | `EffectScopeSelect`                          |
+
+## 相关组件
+
+| 场景     | 组件             | 说明                          |
+| -------- | ---------------- | ----------------------------- |
+| 全局配置 | `ConfigProvider` | 注入 apiPayload 和 apiService |