pit-docs-mcp 1.0.2

package/docs/pitBusinessUtils/request.md

@@ -0,0 +1,137 @@
+# request — HTTP 请求封装
+
+基于 `axios` 封装的 HTTP 请求实例，采用**高度解耦设计**：所有业务逻辑（token 注入、错误提示、响应数据解构等）均通过三个 `window` 全局回调函数由宿主项目注入，本库不内置任何业务逻辑。
+
+## 引用方式
+
+```js
+import request from 'pit-business-utils'
+```
+
+---
+
+## 实例配置
+
+| 配置项 | 值 | 说明 |
+|--------|-----|------|
+| `baseURL` | `""` | 空字符串，实际 baseURL 在 `setConfigCallback` 中注入 |
+| `withCredentials` | `false` | 跨域不携带 Cookie |
+| `timeout` | `20000` | 超时时间 20 秒 |
+
+---
+
+## 全局回调注入（必须在应用初始化时配置）
+
+> ⚠️ **以下三个 `window` 函数必须在宿主项目初始化时注入**，否则请求拦截器将报错或无法正常工作。
+
+### `window.setConfigCallback(config)`
+
+**请求拦截回调**，在每次发送请求前调用，用于注入 token、设置 baseURL 等。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `config` | `AxiosRequestConfig` | axios 请求配置对象 |
+
+| — | — |
+|---|---|
+| **必须返回** | 修改后的 `config` 对象 |
+
+---
+
+### `window.requestThen(response)`
+
+**响应成功回调**，在 HTTP 状态码 2xx 时调用，用于统一处理响应数据、业务错误码判断等。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `response` | `AxiosResponse` | axios 完整响应对象 |
+
+| — | — |
+|---|---|
+| **必须返回** | 处理后的数据（通常为 `response.data` 或解构后的业务数据） |
+
+---
+
+### `window.requestCatch(error)`
+
+**响应失败回调**，在 HTTP 状态码非 2xx 或网络错误时调用，用于统一弹出错误提示、处理 401 跳转等。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `error` | `AxiosError` | axios 错误对象 |
+
+| — | — |
+|---|---|
+| **必须返回** | `Promise.reject(error)` 或处理后的值 |
+
+---
+
+## 宿主项目初始化示例
+
+在项目的 `main.js` 或请求初始化文件中添加以下配置：
+
+```js
+import { getToken } from 'pit-business-utils'
+
+// 请求拦截：注入 token 和 baseURL
+window.setConfigCallback = (config) => {
+  config.baseURL = process.env.VUE_APP_BASE_API
+  const token = getToken()
+  if (token) {
+    config.headers['Authorization'] = `Bearer ${token}`
+  }
+  return config
+}
+
+// 响应成功：解构业务数据，处理业务错误码
+window.requestThen = (response) => {
+  const res = response.data
+  if (res.code !== 200) {
+    Vue.prototype.$message.error(res.message || '请求失败')
+    return Promise.reject(new Error(res.message))
+  }
+  return res
+}
+
+// 响应失败：统一错误提示
+window.requestCatch = (error) => {
+  const status = error.response?.status
+  if (status === 401) {
+    // token 失效，跳转登录
+    removeAll()
+    router.push('/login')
+  } else {
+    Vue.prototype.$message.error(error.message || '网络错误，请稍后重试')
+  }
+  return Promise.reject(error)
+}
+```
+
+---
+
+## 在业务模块中使用
+
+```js
+import request from 'pit-business-utils'
+
+// GET 请求
+export const getUserList = (params) =>
+  request.get('/api/user/list', { params })
+
+// POST 请求
+export const createUser = (data) =>
+  request.post('/api/user/create', data)
+
+// 文件下载（responseType: 'blob'）
+export const exportExcel = (params) =>
+  request.get('/api/user/export', { params, responseType: 'blob' })
+```
+
+---
+
+## 注意事项
+
+- 三个 `window` 全局回调 **缺少任何一个都会导致请求出错**，务必在应用入口文件中全部配置。
+- `baseURL` 不在库内配置，必须在 `setConfigCallback` 中通过 `config.baseURL = ...` 设置。
+- 上传进度监听请在调用方传入 `onUploadProgress` 配置，axios 实例本身支持该特性。
+- 超时时间为 20 秒，如需针对单个请求修改，可在调用时传入 `{ timeout: 60000 }`。

package/docs/pitBusinessUtils/scroll-to.md

@@ -0,0 +1,68 @@
+# scroll-to — 平滑滚动
+
+提供平滑滚动页面到指定位置的工具函数，使用 ease-in-out 缓动动画，自动兼容各主流浏览器。
+
+## 引用方式
+
+```js
+import { scrollTo } from 'pit-business-utils'
+```
+
+---
+
+## 函数
+
+### `scrollTo(to, duration, callback)`
+
+将页面平滑滚动到指定的纵向位置，动画完成后可触发回调。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `to` | `number` | ✅ | 目标滚动位置（距页面顶部的像素值），传 `0` 即回到顶部 |
+| `duration` | `number` | — | 动画持续时间（毫秒），默认 `500` |
+| `callback` | `Function` | — | 动画完成后的回调函数 |
+
+| — | — |
+|---|---|
+| **返回值** | `void` |
+
+---
+
+## 使用示例
+
+```js
+import { scrollTo } from 'pit-business-utils'
+
+// 回到顶部（500ms 动画）
+scrollTo(0)
+
+// 滚动到 500px 位置，动画持续 800ms
+scrollTo(500, 800)
+
+// 滚动完成后执行回调
+scrollTo(0, 500, () => {
+  console.log('已回到顶部')
+})
+```
+
+```js
+// 配合 el-backtop 的 click 事件使用
+methods: {
+  backToTop() {
+    scrollTo(0, 400)
+  }
+}
+```
+
+---
+
+## 动画说明
+
+使用 **ease-in-out 二次缓动函数**：动画开始和结束时速度慢，中间速度快，视觉上更自然流畅。内部每帧增量约 20ms，优先使用 `requestAnimationFrame`，在不支持的浏览器中回退为 `setTimeout`。
+
+---
+
+## 注意事项
+
+- `scrollTo` 操作的是 `document.documentElement.scrollTop` / `document.body.scrollTop`，适用于**页面级滚动**，不适用于局部容器内部滚动。
+- 若需要滚动局部容器元素（如 `el-scrollbar`），请直接操作容器元素的 `scrollTop` 属性，或使用对应组件提供的方法。