pit-docs-mcp 1.0.2

package/docs/pitBusinessUtils/README.md

@@ -0,0 +1,144 @@
+---
+lang: zh-CN
+title: pit-business-utils 工具函数文档
+---
+
+# pit-business-utils
+
+创智艾泰克前端项目工具类库，提供认证管理、HTTP 请求封装、表单校验、文件操作、国际化、OSS 文件服务等前端常用工具函数。
+
+## 安装
+
+```bash
+# 建议带上 --save-exact 参数，避免版本号不一致导致的依赖问题
+npm install pit-business-utils --save-exact
+```
+
+---
+
+## 快速上手
+
+### 1. 请求初始化（必须在 main.js 中配置）
+
+```js
+import { getToken, removeAll, locale, setI18nInstance } from 'pit-business-utils'
+import i18n from './i18n'
+
+// 初始化国际化
+locale(i18n)
+setI18nInstance(i18n)
+
+// 挂载 Vue 根实例（剪贴板、消息提示依赖）
+const vm = new Vue({ i18n, render: h => h(App) }).$mount('#app')
+window.vm = vm
+
+// 注入 Vuex store 和 Router（权限判断依赖）
+window._store = store
+window._router = router
+
+// 配置请求拦截器
+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) return Promise.reject(res)
+  return res
+}
+window.requestCatch = (error) => {
+  if (error.response?.status === 401) { removeAll(); router.push('/login') }
+  return Promise.reject(error)
+}
+```
+
+### 2. 表单校验
+
+```js
+import { formValidate } from 'pit-business-utils'
+
+rules: {
+  phone:  [{ required: true, message: '请输入手机号' }, { validator: formValidate('iphone', '手机号格式错误'), trigger: 'blur' }],
+  idCard: [{ validator: formValidate('idCard', '身份证号格式错误'), trigger: 'blur' }],
+}
+```
+
+### 3. 日期格式化
+
+```js
+import pit from 'pit-business-utils'
+
+pit.toDate(1711036800000)               // "2024-03-22 00:00"
+pit.toDateText(Date.now() - 300000)     // "5分钟前"
+pit.getThatDay(-7)                      // 7天前的日期
+```
+
+### 4. 按钮权限判断
+
+```js
+import pit from 'pit-business-utils'
+
+if (pit.hasBtnP(pit.hasCode.btn_add)) {
+  // 显示新增按钮
+}
+```
+
+### 5. 文件下载
+
+```js
+import { downloadTemplate } from 'pit-business-utils'
+
+const res = await exportApi()
+downloadTemplate(res, '导出数据.xlsx')
+```
+
+---
+
+## 全局依赖汇总
+
+部分功能依赖宿主项目在全局注入变量，**所有全局变量均需在 `main.js` 初始化阶段配置**：
+
+| 全局变量 | 使用该变量的模块 | 说明 |
+|----------|-----------------|------|
+| `window.vm` | clipboard | Vue 根实例，用于调用 `$message` |
+| `window._store` | pit、utils、get-page-title | Vuex store 实例 |
+| `window._router` | pit | Vue Router 实例 |
+| `window.setConfigCallback` | request | 请求拦截配置（注入 token、baseURL 等） |
+| `window.requestThen` | request | 响应成功处理回调 |
+| `window.requestCatch` | request | 响应失败处理回调 |
+
+---
+
+## 环境变量
+
+| 变量名 | 使用模块 | 说明 |
+|--------|----------|------|
+| `VUE_APP_BASE_API` | request | API 基础路径（在 `setConfigCallback` 中使用） |
+| `VUE_APP_BASE_JWKS_KID` | jwks | JWKS 密钥集中目标公钥的 Key ID |
+
+---
+
+## 模块文档目录
+
+| 模块 | 说明 | 文档 |
+|------|------|------|
+| `pit`（默认导出） | 核心工具对象：日期、树结构、存储、权限 | [./pit.md](/pit.md) |
+| `utils` | 通用工具函数集合（约 30 个函数） | [./utils.md](utils.md) |
+| `auth` | 认证令牌管理（localStorage 封装） | [./auth.md](/auth.md) |
+| `request`（默认导出） | axios HTTP 请求封装 | [./request.md](/request.md) |
+| `validate` | 基础格式验证函数 | [./validate.md](/validate.md) |
+| `formValidate` | Element UI 表单正则校验器（含 16 条内置规则） | [./formValidate.md](/formValidate.md) |
+| `passwordValidate` | 密码强度校验（企业级复杂度规则） | [./passwordValidate.md](/passwordValidate.md) |
+| `i18n` / `locale` | 国际化集成（vue-i18n v8/v9+ 兼容） | [./i18n.md](/i18n.md) |
+| `clipboard` | 一键复制文本到剪贴板 | [./clipboard.md](/clipboard.md) |
+| `MyPrint` | 局部打印 Vue 插件 | [./print.md](/print.md) |
+| `scrollTo` | 页面平滑滚动 | [./scroll-to.md](/scroll-to.md) |
+| `jwks` | JWKS 公钥 RSA 加密（登录密码加密） | [./jwks.md](/jwks.md) |
+| `getPageTitle` | 浏览器标签页标题生成 | [./get-page-title.md](/get-page-title.md) |
+| `generateTitle` | 路由/菜单标题生成 | [./generateTitle.md](/generateTitle.md) |
+| OSS 接口（19 个） | OSS 文件上传、下载、预览、删除等 | [./oss.md](/oss.md) |
+| `filePreviewList` | 文件在线预览 URL 获取 | [./filePreview.md](/filePreview.md) |
+
+---

package/docs/pitBusinessUtils/auth.md

@@ -0,0 +1,170 @@
+# auth — 认证令牌管理
+
+管理登录令牌及相关本地存储状态，所有键名统一加 `pit_` 前缀，底层通过 `pit.storageSet/Get/Remove/Clear` 操作 `localStorage`。
+
+## 引用方式
+
+```js
+import { getToken, setToken, removeToken, removeAll } from 'pit-business-utils'
+```
+
+---
+
+## 函数列表
+
+### `getToken()`
+
+获取当前登录令牌。
+
+| — | — |
+|---|---|
+| **参数** | 无 |
+| **返回值** | `string \| null`，存储的 token 值，未设置时返回 `null` |
+
+```js
+const token = getToken()
+if (token) {
+  console.log('已登录，token：', token)
+}
+```
+
+---
+
+### `setToken(token)`
+
+将令牌写入 `localStorage`。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `token` | `string` | ✅ | 登录成功后服务端返回的认证令牌 |
+
+| — | — |
+|---|---|
+| **返回值** | `void` |
+
+```js
+setToken('eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...')
+```
+
+---
+
+### `removeToken()`
+
+删除 `localStorage` 中的令牌，通常在退出登录时调用。
+
+| — | — |
+|---|---|
+| **参数** | 无 |
+| **返回值** | `void` |
+
+```js
+removeToken()
+```
+
+---
+
+### `getLock()`
+
+获取锁屏状态。
+
+> ⚠️ 该功能现已较少使用，保留为兼容老版本。
+
+| — | — |
+|---|---|
+| **参数** | 无 |
+| **返回值** | `string \| null` |
+
+---
+
+### `setLock(lock)`
+
+设置锁屏状态。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `lock` | `string` | ✅ | 锁屏状态标识值 |
+
+| — | — |
+|---|---|
+| **返回值** | `void` |
+
+---
+
+### `removeLock()`
+
+清除锁屏状态。
+
+| — | — |
+|---|---|
+| **参数** | 无 |
+| **返回值** | `void` |
+
+---
+
+### `getPasswordLock()`
+
+获取弱密码锁定状态，用于首次登录强制修改密码的引导流程判断。
+
+| — | — |
+|---|---|
+| **参数** | 无 |
+| **返回值** | `string \| null` |
+
+```js
+if (getPasswordLock()) {
+  // 跳转到修改密码页面
+  router.push('/change-password')
+}
+```
+
+---
+
+### `setPasswordLock(passwordLock)`
+
+设置弱密码锁定标记。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `passwordLock` | `string` | ✅ | 锁定标识，通常传 `"1"` 表示锁定 |
+
+| — | — |
+|---|---|
+| **返回值** | `void` |
+
+---
+
+### `removePasswordLock()`
+
+清除弱密码锁定状态，通常在用户成功修改密码后调用。
+
+| — | — |
+|---|---|
+| **参数** | 无 |
+| **返回值** | `void` |
+
+---
+
+### `removeAll()`
+
+清空所有带 `pit_` 前缀的 `localStorage` 数据，通常在退出登录时调用，彻底清除用户相关缓存。
+
+| — | — |
+|---|---|
+| **参数** | 无 |
+| **返回值** | `void` |
+
+```js
+// 退出登录
+function logout() {
+  removeAll()
+  router.push('/login')
+}
+```
+
+---
+
+## 注意事项
+
+- 所有数据存储在 `localStorage`，浏览器关闭后数据依然保留，刷新页面不丢失。
+- `removeAll()` 只清除以 `pit_` 为前缀的项，不会影响业务系统自行写入 `localStorage` 的其他数据。
+- 令牌存储的实际 key 为 `pit_token`，不建议直接操作 `localStorage`，应通过本模块提供的函数访问。

package/docs/pitBusinessUtils/clipboard.md

@@ -0,0 +1,72 @@
+# clipboard — 剪贴板复制
+
+提供一键复制文本到系统剪贴板的能力，复制成功/失败后自动弹出全局消息提示。
+
+## 引用方式
+
+```js
+import { copyClipboard } from 'pit-business-utils'
+```
+
+---
+
+## 全局依赖
+
+> ⚠️ **使用前必须在宿主项目中完成以下配置：**
+
+| 全局变量 | 作用 |
+|----------|------|
+| `window.vm` | Vue 根实例，用于调用 `window.vm.$message` 弹出提示 |
+
+```js
+// main.js
+const vm = new Vue({ render: h => h(App) }).$mount('#app')
+window.vm = vm
+```
+
+---
+
+## 函数
+
+### `copyClipboard(text, event)`
+
+将指定文本复制到系统剪贴板，复制结果通过全局 `$message` 提示用户。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `text` | `string` | ✅ | 需要复制到剪贴板的文本内容 |
+| `event` | `Event` | ✅ | 触发复制的 DOM 事件对象（如点击事件），用于定位目标元素 |
+
+| — | — |
+|---|---|
+| **返回值** | `void` |
+| **成功提示** | 弹出成功 `$message`，文本来自 i18n |
+| **失败提示** | 弹出错误 `$message`，文本来自 i18n |
+
+### 使用示例
+
+```html
+<!-- 在模板点击事件中直接传入 $event -->
+<template>
+  <el-button @click="handleCopy(record.code, $event)">复制编号</el-button>
+</template>
+```
+
+```js
+import { copyClipboard } from 'pit-business-utils'
+
+methods: {
+  handleCopy(text, event) {
+    copyClipboard(text, event)
+  }
+}
+```
+
+---
+
+## 注意事项
+
+- `event` 参数**不可省略**，`clipboard.js` 底层需要绑定到触发元素上才能执行复制操作。
+- 该函数依赖浏览器的 `execCommand('copy')` 或 Clipboard API（由 `clipboard` 库处理兼容性），在部分旧版或非 HTTPS 环境下可能失败。
+- `window.vm` 必须在 `main.js` 中挂载，否则成功/失败提示无法显示（会报 `TypeError`）。
+- 每次调用都会创建并立即销毁一个 `Clipboard` 实例，不会造成内存泄漏。

package/docs/pitBusinessUtils/filePreview.md

@@ -0,0 +1,60 @@
+# filePreview — 文件预览 API
+
+封装文件在线预览 URL 的获取接口，通常与 `getPreviewUrl`（utils 模块）配合使用。
+
+## 引用方式
+
+```js
+import { filePreviewList } from 'pit-business-utils'
+```
+
+---
+
+## 函数
+
+### `filePreviewList(data)`
+
+批量获取文件的在线预览 URL 列表。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `Array` | ✅ | 预览参数数组，每项包含文件 ID 等信息（具体字段由后端接口定义） |
+
+| — | — |
+|---|---|
+| **接口** | `POST /preview-url` |
+| **返回值** | `Promise<Array>`，包含每个文件对应的预览 URL 信息 |
+
+---
+
+## 使用示例
+
+```js
+import { filePreviewList } from 'pit-business-utils'
+
+// 获取多个文件的预览链接
+const files = [
+  { fileUploadRecordId: 'id-001' },
+  { fileUploadRecordId: 'id-002' }
+]
+
+const previewUrls = await filePreviewList(files)
+// previewUrls: [{ fileUploadRecordId: 'id-001', previewUrl: 'https://...' }, ...]
+```
+
+```js
+// 与 utils 中的 getPreviewUrl 配合使用
+import { getPreviewUrl, filePreviewList } from 'pit-business-utils'
+
+// getPreviewUrl 内部会调用 filePreviewList 获取预览地址
+const url = await getPreviewUrl({ fileId: 'file-id-xxx' }, 'fileId')
+window.open(url)
+```
+
+---
+
+## 注意事项
+
+- 该接口通常不需要直接调用，`utils.getPreviewUrl()` 已将其封装，推荐通过 `getPreviewUrl` 获取预览链接。
+- 接口地址为 `/preview-url`，实际 baseURL 来自宿主项目的 `window.setConfigCallback` 配置。
+- 参数数组中每项的具体字段（如是否需要 `previewType`、`objectName` 等）取决于后端接口定义，请参考后端文档。

package/docs/pitBusinessUtils/formValidate.md

@@ -0,0 +1,75 @@
+# formValidate — 表单正则校验
+
+为 Element UI 表单提供预定义规则校验器以及自定义正则校验能力，返回符合 el-form `rules` 规范的验证函数。
+
+## 引用方式
+
+```js
+import { formValidate } from 'pit-business-utils'
+```
+
+---
+
+## 函数
+
+### `formValidate(type, msg)`
+
+生成适用于 Element UI `el-form` 的字段验证函数。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `type` | `string` | ✅ | 预定义规则名（见下方规则表），或直接传入自定义正则表达式字符串 |
+| `msg` | `string` | — | 校验失败时显示的提示文本；不传则使用 i18n 翻译提示，均无时显示空字符串 |
+
+| — | — |
+|---|---|
+| **返回值** | `Function(rule, value, callback)`，Element UI 校验器回调函数 |
+
+### 使用示例
+
+```js
+// 使用预定义规则
+rules: {
+  phone:   [{ validator: formValidate('iphone', '请输入正确的手机号'), trigger: 'blur' }],
+  email:   [{ validator: formValidate('email'), trigger: 'blur' }],
+  idCard:  [{ validator: formValidate('idCard', '身份证号格式错误'), trigger: 'blur' }],
+}
+```
+
+```js
+// 使用自定义正则字符串
+rules: {
+  postCode: [{ validator: formValidate('^[0-9]{6}$', '邮政编码为6位数字'), trigger: 'blur' }]
+}
+```
+
+---
+
+## 内置校验规则表
+
+| 规则名 | 说明 | 示例合法值 |
+|--------|------|-----------|
+| `iphone` | 手机号（1[3-9]开头，11位数字） | `13812345678` |
+| `password` | 密码（6-16位，必须同时含字母和数字） | `abc12345` |
+| `idCard` | 18位居民身份证号（含校验位X） | `110101199001011234` |
+| `email` | 电子邮箱 | `user@example.com` |
+| `plateNumber` | 车牌号（含新能源车牌） | `粤A12345`、`粤AD12345` |
+| `chinese` | 纯汉字 | `张三` |
+| `enCode` | 字母、数字、点的组合（编码格式） | `A.001`、`abc123` |
+| `enCode2` | 同 `enCode`（字母数字及点） | `node.v1` |
+| `userAccount` | 纯字母数字账号 | `admin123` |
+| `userAccount1` | 字母数字及中文字符账号 | `张三001` |
+| `english` | 纯英文字母（大小写均可） | `HelloWorld` |
+| `fullName` | 字母、数字、汉字组合名称 | `张三A1` |
+| `userCode` | 纯数字编号 | `00123` |
+| `allDate` | 整数或 `.5` 结尾的小数（如工时） | `8`、`4.5` |
+| `bigInt` | 正整数（不含 0 开头） | `100`、`99` |
+| `netUrl` | HTTP / HTTPS / FTP URL | `https://www.example.com` |
+
+---
+
+## 注意事项
+
+- `formValidate` 仅在值**不为空**时触发正则校验；空值不会报错，因此**必填验证需另加 `required: true` 规则**。
+- 自定义正则传入的是正则字符串（如 `'^[0-9]{6}$'`），内部使用 `new RegExp(type)` 构造，注意转义规则。
+- 若项目配置了 i18n，校验失败提示会自动走国际化翻译；如需统一中文提示，在 `msg` 参数中直接传入即可。

package/docs/pitBusinessUtils/generateTitle.md

@@ -0,0 +1,49 @@
+# generateTitle — 路由标题生成
+
+根据路由元信息中的标题字段，生成菜单或面包屑等处展示用的路由标题文本。
+
+## 引用方式
+
+```js
+import { generateTitle } from 'pit-business-utils'
+```
+
+---
+
+## 函数
+
+### `generateTitle(title, fullName)`
+
+优先返回 `fullName`，若 `fullName` 为空则返回 `title`。常用于路由菜单渲染中国际化标题和默认标题的优先级切换。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `title` | `string` | ✅ | 默认标题（备用值，通常为路由 `meta.title`） |
+| `fullName` | `string` | — | 优先显示的完整标题（通常来自后端菜单接口返回的名称） |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，`fullName` 非空时返回 `fullName`，否则返回 `title` |
+
+---
+
+## 使用示例
+
+```js
+generateTitle('项目列表', '工程项目管理')  // "工程项目管理"（优先返回 fullName）
+generateTitle('项目列表', '')              // "项目列表"（fullName 为空，回退）
+generateTitle('项目列表', undefined)       // "项目列表"
+```
+
+```js
+// 在侧边菜单组件中使用
+// route.meta.title 为路由配置中的默认标题
+// route.meta.fullName 为后端菜单接口返回的自定义名称
+<span>{{ generateTitle(route.meta.title, route.meta.fullName) }}</span>
+```
+
+---
+
+## 注意事项
+
+- 逻辑等价于 `fullName || title`，当 `fullName` 为任意 falsy 值（`""`、`null`、`undefined`、`0`）时均返回 `title`。

package/docs/pitBusinessUtils/get-page-title.md

@@ -0,0 +1,65 @@
+# get-page-title — 页面标题生成
+
+根据当前路由页面名称和系统名称，生成浏览器标签页的完整标题字符串，格式为 `"页面名 - 系统名"`。
+
+## 引用方式
+
+```js
+import { getPageTitle } from 'pit-business-utils'
+```
+
+---
+
+## 全局依赖
+
+> ⚠️ **系统标题从 `window._store` 中读取，宿主项目需提前注入。**
+
+| 全局变量 | 读取路径 | 说明 |
+|----------|----------|------|
+| `window._store` | `window._store.state.settings.title` | Vuex store 实例，用于读取系统名称配置 |
+
+若 `window._store` 未注入，则使用默认系统名称 `"工程项目建设管理系统"`。
+
+---
+
+## 函数
+
+### `getPageTitle(key, fullName)`
+
+生成页面标题字符串。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `key` | `string` | — | 保留参数，当前版本未使用，传 `""` 或任意字符串即可 |
+| `fullName` | `string` | — | 当前页面的名称；不传或为空时，仅返回系统名称 |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，格式为 `"页面名 - 系统名"` 或仅 `"系统名"` |
+
+---
+
+## 使用示例
+
+```js
+// 在 Vue Router 的路由守卫中统一设置页面标题
+import { getPageTitle } from 'pit-business-utils'
+
+router.afterEach((to) => {
+  document.title = getPageTitle('', to.meta.title)
+  // to.meta.title = "项目列表" → document.title = "项目列表 - 工程项目建设管理系统"
+})
+```
+
+```js
+getPageTitle('', '项目列表')  // "项目列表 - 工程项目建设管理系统"
+getPageTitle('', '')          // "工程项目建设管理系统"
+getPageTitle('', undefined)   // "工程项目建设管理系统"
+```
+
+---
+
+## 注意事项
+
+- 第一个参数 `key` 为保留参数，当前不参与逻辑，传入任意值均不影响结果。
+- 系统标题优先从 `window._store.state.settings.title` 读取，若 Vuex store 未注入，降级为硬编码的默认值 `"工程项目建设管理系统"`。