feat: 异步函数调用+ 统一提示

Author: wkylin

src/components/hooks/useAsyncTip/README.md

@@ -0,0 +1,95 @@
+# useAsyncTip Hook 使用说明
+
+useAsyncTip 用于“包一层异步函数调用 + 统一提示”。它主要解决：
+
+- 每次请求都要手写 loading/success/error 提示
+- message 互相覆盖/误伤（只关闭当前请求的 loading）
+- 错误结构不统一（复用 service/request.js 的错误映射能力）
+
+该实现基于 antd v6：通过 App.useApp() 注入的 message 实例（见 src/utils/message.ts）。
+
+## 主要功能
+
+1. 调用开始：显示 loading（带 key，可被后续更新/关闭）
+
+2. 调用成功：显示 success（successText 可配置）
+
+3. 调用失败：
+
+- 如果你提供 onError：仅关闭 loading，并把错误交给你处理（比如跳转/上报/自定义提示）
+- 否则：根据错误对象提取文案并提示；同时尽量避免与 service 层重复弹错
+
+## API
+
+```ts
+useAsyncTip(fn, options?, deps?)
+```
+
+- fn: (...args) => Promise<any> | any
+- options?:
+  - loadingText?: string // loading 文案，默认 "加载中..."
+  - successText?: string // 成功文案，默认 "完成"
+  - onError?: (err) => void // 自定义失败处理（提供后 hook 不再默认弹错）
+- deps?: React.DependencyList // 可选；不传时默认依赖 [fn, options]
+
+## 行为约定（结合 service/request.js）
+
+- 成功判断：
+  - 返回值是业务包裹对象且包含 code：code === 0 或 200 视为成功
+  - 否则如果返回 { success: boolean }：success 为 true 视为成功
+- 错误文案：优先使用 err.message / 后端返回的 message/msg；
+  同时复用 RequestUtils.getHttpErrorMessage/getNetworkErrorMessage 做兜底。
+
+## 基本用法
+
+```tsx
+import useAsyncTip from '@hooks/useAsyncTip'
+import request from '@src/service/request'
+
+const save = useAsyncTip(
+	(payload) => request.post('/api/save', payload),
+	{ loadingText: '保存中...', successText: '保存成功' }
+)
+
+<Button onClick={() => save({ a: 1 })}>保存</Button>
+```
+
+## 自定义失败处理（比如跳转错误页/上报）
+
+```tsx
+const loadDetail = useAsyncTip((id) => request.get('/api/detail', { id }), {
+  loadingText: '加载中...',
+  successText: '加载完成',
+  onError: (err) => {
+    // 这里可以做：上报、跳转、或者自己弹提示
+    // showMessage.error('加载失败')
+  },
+})
+```
+
+## 重要提示
+
+- 本 hook 使用的提示能力来自 src/utils/message.ts，要求在应用根部已正确 setMessageInstance。
+- 如果 service 层（request.js/http.js）已经开启了 showError，hook 默认会尽量避免重复弹错。
+
+## 根组件初始化 message（与 theme.tsx 对应）
+
+项目使用 antd v6 的 App 上下文来获取 message 实例，并注入到 src/utils/message.ts：
+
+```tsx
+import { useEffect } from 'react'
+import { App as AntdApp } from 'antd'
+import { setMessageInstance } from '@utils/message'
+
+const ThemeIndex = () => {
+	const { message } = AntdApp.useApp()
+
+	useEffect(() => {
+		setMessageInstance(message)
+	}, [message])
+
+	return (...)
+}
+```
+
+完整实现可参考：src/theme.tsx

src/components/hooks/useAsyncTip/index.tsx

@@ -0,0 +1,112 @@
+import { useCallback, type DependencyList } from 'react'
+import { showMessage } from '@src/utils/message'
+import { RequestUtils } from '@src/service/request'
+
+type AnyFn = (...args: any[]) => any
+type TipHandler = (val: any) => void
+
+type UseAsyncTipOptions = {
+  loadingText?: string
+  successText?: string
+  onError?: TipHandler
+}
+
+const isBusinessEnvelope = (val: any) => {
+  return !!(val && typeof val === 'object' && Object.hasOwn(val, 'code'))
+}
+
+const isOk = (res: any) => {
+  if (!res || typeof res !== 'object') return !!res
+  // 兼容 { success: true/false }
+  if (Object.hasOwn(res, 'success')) return !!res.success
+  // 兼容 { code: 0/200 }
+  if (isBusinessEnvelope(res)) return res.code === 0 || res.code === 200
+  // 兼容 axios error 分支可能返回 { status: 4xx/5xx, data: {...} }
+  if (Object.hasOwn(res, 'status')) return res.status >= 200 && res.status < 300
+  return true
+}
+
+const getErrorMessage = (err: any) => {
+  if (!err) return '请求失败'
+  if (typeof err === 'string') return err
+
+  // request.js 的自定义错误可能带 status / code / response
+  const status = err.status || err.response?.status
+  if (typeof status === 'number') {
+    return err.message || RequestUtils.getHttpErrorMessage(status) || '请求失败'
+  }
+
+  // axios 网络错误会有 code
+  if (typeof err.code === 'string') {
+    return err.message || RequestUtils.getNetworkErrorMessage(err.code) || '网络连接异常'
+  }
+
+  // axios interceptor 里可能 resolve(err.response) 或抛出 { data: ... }
+  const data = err.data || err.response?.data
+  if (data && typeof data === 'object') {
+    return data.message || data.msg || data.error || data.code || err.message || '请求失败'
+  }
+
+  return err.message || err.msg || (err.error && (err.error.message || err.error.code)) || '请求失败'
+}
+
+const shouldShowErrorByDefault = (err: any) => {
+  // request.js/http.js 默认会 showError/isShowError=true 并自行 showMessage.error
+  // 这里尽量避免重复弹错：如果错误包含明显的 service 痕迹（status/code/response），默认不再重复提示
+  if (err && typeof err === 'object') {
+    if ('response' in err || 'status' in err || 'code' in err) return false
+  }
+  return true
+}
+
+export default (fn: AnyFn, options?: UseAsyncTipOptions, deps?: DependencyList) => {
+  const callback = useCallback(
+    (...args: any[]) => {
+      const key = `async-tip-${Date.now()}-${Math.random().toString(16).slice(2)}`
+      const loadingText = options?.loadingText || '加载中...'
+      showMessage.loading(loadingText, key)
+
+      let handled = false
+
+      return Promise.resolve()
+        .then(() => fn(...args))
+        .then((res) => {
+          if (isOk(res)) {
+            showMessage.open({
+              type: 'success',
+              content: options?.successText || '完成',
+              key,
+              duration: 0.5,
+            })
+            return res
+          }
+
+          handled = true
+          if (typeof options?.onError === 'function') {
+            showMessage.destroy(key)
+            options.onError(res)
+          } else if (shouldShowErrorByDefault(res)) {
+            showMessage.open({ type: 'error', content: getErrorMessage(res), key, duration: 2 })
+          } else {
+            showMessage.destroy(key)
+          }
+          return Promise.reject(res)
+        })
+        .catch((err) => {
+          if (!handled) {
+            if (typeof options?.onError === 'function') {
+              showMessage.destroy(key)
+              options.onError(err)
+            } else if (shouldShowErrorByDefault(err)) {
+              showMessage.open({ type: 'error', content: getErrorMessage(err), key, duration: 2 })
+            } else {
+              showMessage.destroy(key)
+            }
+          }
+          return Promise.reject(err)
+        })
+    },
+    Array.isArray(deps) ? deps : [fn, options]
+  )
+  return callback
+}

src/components/stateless/FixTabPanel/README.md

@@ -1,46 +1,51 @@
-// FixTabPanel 组件使用说明
-//
-// FixTabPanel 是一个增强的可滚动面板组件，集成了滚动进度条功能。
-// 进度条使用粘性定位（sticky），在滚动时会固定在容器顶部。
-//
-// ## 基本用法：
-// `jsx
-// import FixTabPanel from '@stateless/FixTabPanel'
-//
-// <FixTabPanel style={{ height: '400px' }}>
-//   <div>可滚动的内容</div>
-// </FixTabPanel>
-// `
-//
-// ## 高级用法：
-// `jsx
-// <FixTabPanel
-//   showScrollProgress={true}
-//   scrollProgressProps={{
-//     height: 4,
-//     color: '#ff6b6b',
-//     position: 'sticky',
-//     springConfig: { stiffness: 200 }
-//   }}
-//   className="custom-panel"
-//   style={{ height: '400px', border: '1px solid #ccc' }}
-// >
-//   <div>内容</div>
-// </FixTabPanel>
-// `
-//
-// ## Props：
-// - `showScrollProgress?: boolean` - 是否显示滚动进度条（默认 true）
-// - `scrollProgressProps?: object` - 滚动进度条的配置属性
-// - 继承所有 `div` 的 HTML 属性
-//
-// ## 重要提示：
-// - **必须设置高度**: FixTabPanel 需要明确的 `height` 样式才能正确显示滚动条
-// - **粘性定位**: 进度条使用 `position: sticky`，会在滚动时固定在容器顶部
-//
-// ## 特性：
-// - ✅ 相对定位容器
-// - ✅ 粘性定位滚动进度条
-// - ✅ 返回顶部按钮
-// - ✅ 可自定义进度条样式
-// - ✅ 支持所有标准 div 属性
+# FixTabPanel 组件使用说明
+
+FixTabPanel 是一个增强的可滚动面板组件，集成了滚动进度条功能。
+进度条使用粘性定位（sticky），在滚动时会固定在容器顶部。
+
+## 基本用法：
+
+```jsx
+import FixTabPanel from '@stateless/FixTabPanel'
+
+;<FixTabPanel style={{ height: '400px' }}>
+  <div>可滚动的内容</div>
+</FixTabPanel>
+```
+
+## 高级用法：
+
+```jsx
+<FixTabPanel
+  showScrollProgress={true}
+  scrollProgressProps={{
+    height: 4,
+    color: '#ff6b6b',
+    position: 'sticky',
+    springConfig: { stiffness: 200 },
+  }}
+  className="custom-panel"
+  style={{ height: '400px', border: '1px solid #ccc' }}
+>
+  <div>内容</div>
+</FixTabPanel>
+```
+
+## Props：
+
+- `showScrollProgress?: boolean` - 是否显示滚动进度条（默认 true）
+- `scrollProgressProps?: object` - 滚动进度条的配置属性
+- 继承所有 `div` 的 HTML 属性
+
+## 重要提示：
+
+- **必须设置高度**: FixTabPanel 需要明确的 `height` 样式才能正确显示滚动条
+- **粘性定位**: 进度条使用 `position: sticky`，会在滚动时固定在容器顶部
+
+## 特性：
+
+- ✅ 相对定位容器
+- ✅ 粘性定位滚动进度条
+- ✅ 返回顶部按钮
+- ✅ 可自定义进度条样式
+- ✅ 支持所有标准 div 属性