@xfe-repo/web-components 1.6.2 → 1.7.1

package/skills/xfe-web-components/references/ConfigProvider.md

@@ -0,0 +1,198 @@
+# ConfigProvider
+
+> 全局配置提供者，集成 Ant Design 配置、API 服务、国际化和主题，是所有 Effect 组件的运行基础。
+
+## 导入
+
+```tsx
+import { ConfigProvider, ConfigContext } from '@xfe-repo/web-components'
+import type { ConfigProviderProps, IApiPayload, IConfigContext } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+```tsx
+import { ConfigProvider } from '@xfe-repo/web-components'
+import zhCN from 'antd/locale/zh_CN'
+
+function App() {
+  return (
+    <ConfigProvider
+      locale={zhCN}
+      apiPayload={{
+        jwt: jwtInstance,
+        apiEnv: 'production',
+        business: 'eshetang',
+        getUserToken: () => localStorage.getItem('token') || '',
+        setUserToken: (token) => localStorage.setItem('token', token),
+        removeUserToken: () => localStorage.removeItem('token'),
+      }}
+    >
+      <YourApp />
+    </ConfigProvider>
+  )
+}
+```
+
+## 进阶用法
+
+### 自定义 API 服务
+
+通过 `apiService` 覆盖默认的 SaaS BFF 服务实现，适用于非标准后端或 Mock 场景。自定义方法会与默认 `saasApiService` 合并（浅合并，自定义优先）。
+
+```tsx
+import { ConfigProvider } from '@xfe-repo/web-components'
+
+const customApiService = {
+  categoryListToTree: async (params, config) => {
+    // 自定义分类树接口实现
+    return await myCustomApi.getCategoryTree(params)
+  },
+  brandComboBox: async (params, config) => {
+    // 自定义品牌下拉接口实现
+    return await myCustomApi.getBrands(params)
+  },
+}
+
+function App() {
+  return (
+    <ConfigProvider apiService={customApiService}>
+      <YourApp />
+    </ConfigProvider>
+  )
+}
+```
+
+### 在子组件中消费 Context
+
+```tsx
+import { useContext } from 'react'
+import { ConfigContext } from '@xfe-repo/web-components'
+
+function MyComponent() {
+  const configContext = useContext(ConfigContext)
+
+  // 获取 API 服务和认证信息
+  const { apiService, apiPayload } = configContext!
+  const token = apiPayload.getUserToken?.()
+
+  return <div>当前环境：{apiPayload.apiEnv}</div>
+}
+```
+
+## Props
+
+```typescript
+interface ConfigProviderProps {
+  /** SaaS BFF 认证信息，使用自定义 apiService 时可不传 */
+  apiPayload?: Partial<IApiPayload>
+  /** 自定义 API 服务实现，会覆盖默认的 SaaS BFF 服务 */
+  apiService?: Partial<IApiService>
+  /** antd 国际化语言包 */
+  locale?: Locale
+  /** antd 主题配置 */
+  theme?: ThemeConfig
+  /** antd App 组件的 className */
+  className?: string
+  /** 子组件 */
+  children: React.ReactNode
+}
+```
+
+| 属性       | 类型                   | 必填 | 默认值           | 说明                                            |
+| ---------- | ---------------------- | ---- | ---------------- | ----------------------------------------------- |
+| apiPayload | `Partial<IApiPayload>` | 否   | `{}`             | SaaS BFF 认证信息，包含 JWT、环境、Token 管理等 |
+| apiService | `Partial<IApiService>` | 否   | `saasApiService` | 自定义 API 服务，与默认实现浅合并               |
+| locale     | `Locale`               | 否   | -                | antd 国际化语言包                               |
+| theme      | `ThemeConfig`          | 否   | -                | antd 主题配置                                   |
+| className  | `string`               | 否   | -                | 传递给 antd App 组件的 className                |
+| children   | `React.ReactNode`      | 是   | -                | 子组件                                          |
+
+## 导出类型
+
+### IApiPayload
+
+API 认证载荷，包含运行环境和 Token 管理方法：
+
+```typescript
+type IApiPayload = {
+  jwt: JWT // JWT 实例（来自 @xfe-repo/web-service）
+  apiEnv: ApiEnv // API 环境标识（来自 @xfe-repo/web-utils/env）
+  business: Business // 业务线标识（来自 @xfe-repo/web-utils/env）
+  getUserToken: () => string // 获取当前用户 Token
+  setUserToken: (token: string) => void // 设置用户 Token
+  removeUserToken: () => void // 移除用户 Token
+}
+```
+
+### IApiService
+
+API 服务接口，定义了所有 Effect 组件内部调用的接口方法：
+
+```typescript
+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> // 业务线列表
+}
+```
+
+### IConfigContext
+
+Context 值类型：
+
+```typescript
+type IConfigContext = {
+  apiPayload: Partial<IApiPayload>
+  apiService: IApiService
+}
+```
+
+### ConfigContext
+
+```typescript
+const ConfigContext: React.Context<IConfigContext | null>
+```
+
+## 常见陷阱
+
+- ❌ 未在应用入口包裹 `ConfigProvider`，直接使用 Effect 组件：
+  ```tsx
+  // 所有 Effect 组件会因为缺少 Context 而报错
+  <EffectBrandSelect />
+  ```
+- ✅ 在应用最外层包裹 `ConfigProvider`：
+
+  ```tsx
+  <ConfigProvider apiPayload={payload}>
+    <EffectBrandSelect />
+  </ConfigProvider>
+  ```
+
+- ❌ 传入完整的 `apiService` 对象但遗漏了某些方法 —— 不会报错但运行时调用缺失方法会崩溃
+- ✅ 只覆盖需要自定义的方法，其余自动使用默认的 `saasApiService`：
+  ```tsx
+  <ConfigProvider apiService={{ brandComboBox: myBrandApi }}>
+  ```
+
+## 相关组件
+
+| 场景     | 组件                    | 说明                                                   |
+| -------- | ----------------------- | ------------------------------------------------------ |
+| 品牌选择 | `EffectBrandSelect`     | 依赖 ConfigProvider 提供 apiService.brandComboBox      |
+| 分类选择 | `EffectCategoryCascade` | 依赖 ConfigProvider 提供 apiService.categoryListToTree |
+| 文件上传 | `EffectFileUpload`      | 依赖 ConfigProvider 提供 apiService.uploadUploadFile   |
+| 商品范围 | `EffectScopeSelect`     | 内部聚合多个 Effect 组件，间接依赖 ConfigProvider      |

package/skills/xfe-web-components/references/Countdown.md

@@ -0,0 +1,109 @@
+# Countdown
+
+> 倒计时组件，支持 `date`（天时分秒格式）和 `second`（纯秒数）两种展示模式。
+
+## 导入
+
+```tsx
+import { Countdown, formatDate } from '@xfe-repo/web-components'
+import type { CountdownProps } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+### 秒数模式（默认）
+
+```tsx
+import { Countdown } from '@xfe-repo/web-components'
+
+function Timer() {
+  return <Countdown init={60} />  {/* 显示: 60, 59, 58... */}
+}
+```
+
+### 日期模式
+
+```tsx
+<Countdown init={3661} mode="date" />  {/* 显示: 0天01:01:01 */}
+```
+
+## 进阶用法
+
+### 自定义结束文案
+
+```tsx
+<Countdown
+  init={10}
+  mode="date"
+  onEnd={() => '已过期'} // 倒计时结束后显示"已过期"
+/>
+```
+
+### 监听每秒变化
+
+```tsx
+<Countdown
+  init={300}
+  mode="date"
+  onInterval={(remainSeconds) => {
+    if (remainSeconds <= 10) {
+      console.log('即将过期')
+    }
+  }}
+/>
+```
+
+### 自定义日期格式
+
+```tsx
+<Countdown
+  init={7200}
+  mode="date"
+  // 显示: 02小时00分00秒
+  formatStr="HH小时MM分SS秒"
+/>
+```
+
+## Props
+
+```typescript
+export interface CountdownProps {
+  init: number | string
+  onEnd?: () => string | void
+  onInterval?: (s: number) => string | void
+  mode?: 'date' | 'second'
+  formatStr?: string
+  className?: string
+}
+```
+
+| 属性       | 类型                            | 必填 | 默认值           | 说明                                                  |
+| ---------- | ------------------------------- | ---- | ---------------- | ----------------------------------------------------- |
+| init       | `number \| string`              | 是   | -                | 初始倒计时秒数，或直接显示的字符串                    |
+| mode       | `'date' \| 'second'`            | 否   | -                | 展示模式。`date` 格式化为天时分秒；不传则直接显示秒数 |
+| formatStr  | `string`                        | 否   | `'DD天HH:MM:SS'` | 日期模式的格式字符串，支持 DD/HH/MM/SS                |
+| onEnd      | `() => string \| void`          | 否   | -                | 倒计时结束回调，返回字符串则替换显示内容              |
+| onInterval | `(s: number) => string \| void` | 否   | -                | 每秒触发，参数为剩余秒数                              |
+| className  | `string`                        | 否   | -                | 自定义 className                                      |
+
+## 导出类型
+
+### formatDate
+
+```typescript
+export function formatDate(s: number, formatStr?: string): string
+```
+
+独立的秒数格式化函数，将秒数转换为 `DD天HH:MM:SS` 格式。
+
+## 常见陷阱
+
+- ❌ `init` 传入字符串类型时，倒计时不会启动，仅静态展示该字符串
+- ✅ 需要倒计时功能必须传入 `number` 类型
+
+## 相关组件
+
+| 场景     | 组件      | 说明              |
+| -------- | --------- | ----------------- |
+| 正向计时 | `Counter` | 从 0 开始递增计数 |
+| 实时时钟 | `Clock`   | 展示当前时间      |

package/skills/xfe-web-components/references/Counter.md

@@ -0,0 +1,75 @@
+# Counter
+
+> 正向计数器组件，`loading` 为 true 时开始从初始值递增，停止时触发结束回调。
+
+## 导入
+
+```tsx
+import { Counter } from '@xfe-repo/web-components'
+import type { CounterProps } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+```tsx
+import { Counter } from '@xfe-repo/web-components'
+import { useState } from 'react'
+
+function Timer() {
+  const [running, setRunning] = useState(false)
+
+  return (
+    <div>
+      <Counter loading={running} />
+      <button onClick={() => setRunning(!running)}>{running ? '停止' : '开始'}</button>
+    </div>
+  )
+}
+```
+
+## 进阶用法
+
+### 自定义递增步长
+
+```tsx
+<Counter loading={true} interval={5} />  {/* 每秒增加 5 */}
+```
+
+### 结束回调
+
+```tsx
+<Counter
+  loading={isProcessing}
+  onEnd={() => '已完成'} // loading 变为 false 时显示"已完成"
+  onInterval={(value) => console.log('当前计数:', value)}
+/>
+```
+
+## Props
+
+```typescript
+export interface CounterProps {
+  loading: boolean
+  onEnd?: () => string | void
+  onInterval?: (s: number) => string | void
+  interval?: number
+  className?: string
+  init?: number | string
+}
+```
+
+| 属性       | 类型                            | 必填 | 默认值 | 说明                                 |
+| ---------- | ------------------------------- | ---- | ------ | ------------------------------------ |
+| loading    | `boolean`                       | 是   | -      | 是否正在计数                         |
+| init       | `number \| string`              | 否   | `0`    | 初始值                               |
+| interval   | `number`                        | 否   | `1`    | 每秒递增的步长                       |
+| onEnd      | `() => string \| void`          | 否   | -      | 停止时回调，返回字符串则替换显示内容 |
+| onInterval | `(s: number) => string \| void` | 否   | -      | 每秒触发，参数为当前计数值           |
+| className  | `string`                        | 否   | -      | 自定义 className                     |
+
+## 相关组件
+
+| 场景     | 组件        | 说明               |
+| -------- | ----------- | ------------------ |
+| 倒计时   | `Countdown` | 从指定秒数递减到 0 |
+| 实时时钟 | `Clock`     | 展示当前时间       |

package/skills/xfe-web-components/references/Currency.md

@@ -0,0 +1,112 @@
+# Currency
+
+> 金额展示组件，支持分/角/元单位自动换算，统一以"￥"前缀展示。
+
+## 导入
+
+```tsx
+import { Currency } from '@xfe-repo/web-components'
+import type { CurrencyProps, CurrencyUnit } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+```tsx
+import { Currency } from '@xfe-repo/web-components'
+
+// 后端返回金额单位为"分"
+function Price() {
+  return <Currency>{9990}</Currency>  {/* 显示: ￥99.90 */}
+}
+```
+
+> ⚠️ **`unit` 默认为 `'fen'`（分）**。如果后端返回的金额单位已经是"元"，必须显式设置 `unit="yuan"`，否则金额将被放大 100 倍。
+
+## 进阶用法
+
+### 指定单位
+
+```tsx
+<Currency unit="yuan">{99.9}</Currency>   {/* 显示: ￥99.90 */}
+<Currency unit="jiao">{999}</Currency>    {/* 显示: ￥99.90 */}
+<Currency unit="fen">{9990}</Currency>    {/* 显示: ￥99.90 */}
+```
+
+### 自定义小数位
+
+```tsx
+<Currency toFixed={0}>{9990}</Currency>   {/* 显示: ￥100 */}
+<Currency toFixed={3}>{9990}</Currency>   {/* 显示: ￥99.900 */}
+```
+
+### 空值和脱敏值处理
+
+```tsx
+<Currency>{undefined}</Currency>           {/* 显示: -- */}
+<Currency>{null}</Currency>                {/* 显示: -- */}
+<Currency>{'***'}</Currency>               {/* 显示: ￥ *** */}
+```
+
+### 在 Table 列渲染中使用
+
+最常见场景（85%+ 使用率）：
+
+```tsx
+const columns = [
+  {
+    title: '金额',
+    dataIndex: 'amount',
+    render: (amount: number) => <Currency>{amount}</Currency>,
+    align: 'center' as const,
+  },
+]
+```
+
+## Props
+
+```typescript
+export type CurrencyUnit = 'yuan' | 'jiao' | 'fen'
+
+export interface CurrencyProps {
+  unit?: CurrencyUnit
+  toFixed?: number
+  children?: number | string
+  className?: string
+}
+```
+
+| 属性      | 类型                        | 必填 | 默认值  | 说明                                  |
+| --------- | --------------------------- | ---- | ------- | ------------------------------------- |
+| unit      | `'yuan' \| 'jiao' \| 'fen'` | 否   | `'fen'` | 金额单位，自动换算为元                |
+| toFixed   | `number`                    | 否   | `2`     | 保留的小数位数                        |
+| children  | `number \| string`          | 否   | -       | 金额值，为 null/undefined 时显示 `--` |
+| className | `string`                    | 否   | -       | 自定义 className                      |
+
+## 常见陷阱
+
+- ❌ 后端返回"元"但未指定 unit，金额放大 100 倍：
+  ```tsx
+  // 后端返回 price = 99.9 (元)
+  <Currency>{price}</Currency>  {/* 显示: ￥0.99 — 错误！ */}
+  ```
+- ✅ 根据后端单位正确设置 unit：
+
+  ```tsx
+  <Currency unit="yuan">{price}</Currency>  {/* 显示: ￥99.90 — 正确 */}
+  ```
+
+- ⚠️ 空值防御：`children` 为 `null`/`undefined` 时显示为 `--`。如需区分"未填写"与"零元"，应在外层判断：
+  ```tsx
+  render: (amount) => (amount != null ? <Currency>{amount}</Currency> : '-')
+  ```
+
+### 汇总金额
+
+```tsx
+const total = items.reduce((sum, item) => sum + (item.amount ?? 0), 0)
+<Currency>{total}</Currency>
+```
+
+## 导出类型
+
+> 类型定义见上方 Props 部分的 `CurrencyUnit`。

package/skills/xfe-web-components/references/EffectAddressCascade.md

@@ -0,0 +1,110 @@
+# EffectAddressCascade
+
+> 省市区三级地址级联选择器，基于 Ant Design Cascader 实现异步按需加载，数据通过 `apiService.commonAddressList` 自动获取。
+
+## 导入
+
+```tsx
+import { EffectAddressCascade } from '@xfe-repo/web-components'
+import type { SelectItem } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+```tsx
+import { EffectAddressCascade } from '@xfe-repo/web-components'
+import type { SelectItem } from '@xfe-repo/web-components'
+
+function MyForm() {
+  const handleChange = (selectedList?: SelectItem[]) => {
+    // selectedList: [{ value: '省ID', label: '省名', index: 0 }, { value: '市ID', label: '市名', index: 1 }, ...]
+    console.log('选中地址：', selectedList)
+  }
+
+  return <EffectAddressCascade onChange={handleChange} />
+}
+```
+
+## 进阶用法
+
+### 设置默认值
+
+通过 `defaultValue` 传入省、市、区的 ID 数组来设置初始选中值：
+
+```tsx
+<EffectAddressCascade defaultValue={['110000', '110100', '110101']} onChange={(selectedList) => console.log(selectedList)} />
+```
+
+### 禁用状态
+
+```tsx
+<EffectAddressCascade disabled defaultValue={['110000', '110100', '110101']} />
+```
+
+## Props
+
+```typescript
+type SelectItem = { value: string; label: string; index: number }
+
+type Props = {
+  className?: string
+  onChange?: (value?: SelectItem[]) => void
+  defaultValue?: string[]
+  disabled?: boolean
+}
+```
+
+| 属性         | 类型                             | 必填 | 默认值 | 说明                               |
+| ------------ | -------------------------------- | ---- | ------ | ---------------------------------- |
+| onChange     | `(value?: SelectItem[]) => void` | 否   | -      | 选中值变化回调，返回各级选中项数组 |
+| defaultValue | `string[]`                       | 否   | -      | 默认选中值，省/市/区 ID 组成的数组 |
+| disabled     | `boolean`                        | 否   | -      | 禁用状态                           |
+| className    | `string`                         | 否   | -      | 自定义样式类名                     |
+
+## 导出类型
+
+```typescript
+// 选中项数据结构
+export type SelectItem = {
+  value: string // 地区 ID
+  label: string // 地区名称
+  index: number // 在当前级别选项列表中的索引
+}
+```
+
+## API 数据源
+
+- **内部接口**：`apiService.commonAddressList`
+- **请求参数**：`{ pid: string }`（父级地区 ID，首次加载传空字符串获取省份列表）
+- **加载方式**：异步按需加载（`loadData`），选中省后加载市，选中市后加载区
+- **可覆盖**：通过 `<ConfigProvider apiService={{ commonAddressList: customFn }}>` 替换默认实现
+
+## 常见陷阱
+
+- ❌ 期望 `onChange` 返回字符串数组（如 `['省ID', '市ID', '区ID']`）：
+  ```tsx
+  // onChange 返回的是 SelectItem[] 对象数组，不是简单字符串数组
+  ```
+- ✅ 从 `SelectItem[]` 中提取所需字段：
+
+  ```tsx
+  <EffectAddressCascade
+    onChange={(selectedList) => {
+      const ids = selectedList?.map((item) => item.value) // ['110000', '110100', '110101']
+      const names = selectedList?.map((item) => item.label) // ['北京', '北京市', '东城区']
+    }}
+  />
+  ```
+
+- ❌ 将组件当作受控组件使用（无 `value` prop）
+- ✅ 本组件仅支持 `defaultValue` 设置初始值，不支持受控模式
+
+## 使用提示
+
+> 💡 与 Form.Item 集成时可能需要 `valuePropName="defaultValue"` 解决非受控模式兼容问题。
+
+## 相关组件
+
+| 场景     | 组件             | 说明                                         |
+| -------- | ---------------- | -------------------------------------------- |
+| API 配置 | `ConfigProvider` | 提供 `apiService.commonAddressList` 接口实现 |