pit-docs-mcp 1.0.2

package/docs/pitBusinessUtils/i18n.md

@@ -0,0 +1,130 @@
+# i18n — 国际化集成
+
+提供将本库内置语言包合并到项目 i18n 实例的工具，以及库内部独立的翻译函数，兼容 vue-i18n v8、v9+ 和其他 i18n 方案。
+
+## 引用方式
+
+```js
+import locale, { setI18nInstance, t } from 'pit-business-utils'
+```
+
+---
+
+## 函数列表
+
+### `locale(i18n)`（默认导出）
+
+将本库内置语言包（中文 + 英文）合并到项目的 i18n 实例中，使库内的提示文本跟随项目语言切换。  
+**在项目初始化时调用一次即可。**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `i18n` | `Object` | ✅ | 项目的 i18n 实例（vue-i18n 或其他 i18n 库实例） |
+
+| — | — |
+|---|---|
+| **返回值** | `void` |
+
+**兼容方案：**
+- vue-i18n v8：调用 `i18n.mergeLocaleMessage('zh', messages)` 方式合并
+- vue-i18n v9+（Composition API）：调用 `i18n.global.mergeLocaleMessage(...)` 合并
+- 其他 i18n 库：使用 `Object.assign` 直接合并消息对象
+
+```js
+// main.js
+import Vue from 'vue'
+import VueI18n from 'vue-i18n'
+import locale from 'pit-business-utils'
+import i18n from './i18n' // 项目自己的 i18n 实例
+
+Vue.use(VueI18n)
+locale(i18n)  // 合并库语言包到项目 i18n
+
+new Vue({ i18n, render: h => h(App) }).$mount('#app')
+```
+
+---
+
+### `setI18nInstance(instance)`
+
+将项目的 i18n 实例注入到库内部，使库内 `t()` 函数能调用项目 i18n 实例进行翻译。  
+通常在调用 `locale(i18n)` 后紧接着调用。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `instance` | `Object` | ✅ | vue-i18n 实例或兼容 `.t(key)` 方法的 i18n 对象 |
+
+| — | — |
+|---|---|
+| **返回值** | `void` |
+
+```js
+import { setI18nInstance } from 'pit-business-utils'
+import i18n from './i18n'
+
+setI18nInstance(i18n)
+```
+
+---
+
+### `getI18nInstance()`
+
+获取当前注入的 i18n 实例（通常用于库内部使用，业务代码一般无需调用）。
+
+| — | — |
+|---|---|
+| **参数** | 无 |
+| **返回值** | `Object`，当前注入的 i18n 实例 |
+
+---
+
+### `t(key)`
+
+库内部通用翻译函数，优先使用注入的 i18n 实例翻译，未注入时回退到库内置语言包查找，仍未找到则返回 key 本身。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `key` | `string` | ✅ | 翻译键，支持点分隔的路径，如 `"validate.phone"` |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，翻译后的文本；未找到时返回 `key` 本身 |
+
+```js
+import { t } from 'pit-business-utils'
+
+t('validate.phone')  // "请输入正确的手机号"（中文环境）
+t('validate.phone')  // "Please enter a valid phone number"（英文环境）
+```
+
+---
+
+## 完整初始化示例
+
+```js
+// main.js
+import Vue from 'vue'
+import VueI18n from 'vue-i18n'
+import locale, { setI18nInstance } from 'pit-business-utils'
+import i18n from './i18n'
+
+Vue.use(VueI18n)
+
+// 1. 合并库语言包到项目 i18n
+locale(i18n)
+// 2. 注入 i18n 实例到库内部（使 t() 生效）
+setI18nInstance(i18n)
+
+new Vue({
+  i18n,
+  render: h => h(App)
+}).$mount('#app')
+```
+
+---
+
+## 注意事项
+
+- 如果项目没有使用 i18n，可以跳过 `locale` 和 `setI18nInstance` 的调用，库内提示文本将默认显示中文。
+- `locale()` 和 `setI18nInstance()` 只需在应用启动时调用一次，不需要在每个组件中重复调用。
+- 库内置语言包含 `zh`（中文）和 `en`（英文）两种语言，键名格式为 `"pit.xxx"`。

package/docs/pitBusinessUtils/jwks.md

@@ -0,0 +1,82 @@
+# jwks — JWKS 公钥加密
+
+通过 JWKS（JSON Web Key Set）端点获取 RSA 公钥，并使用该公钥对敏感数据（如密码）进行加密，适合登录场景中前端加密密码后再传输。
+
+## 引用方式
+
+```js
+import { getJwks } from 'pit-business-utils'
+```
+
+---
+
+## 环境变量依赖
+
+> ⚠️ **使用前必须在项目中配置以下环境变量：**
+
+| 变量名 | 说明 |
+|--------|------|
+| `VUE_APP_BASE_JWKS_KID` | JWKS 密钥集中目标密钥的 Key ID（`kid`），用于从密钥集中匹配正确的公钥 |
+
+```bash
+# .env.production
+VUE_APP_BASE_JWKS_KID=your-key-id-here
+```
+
+---
+
+## 函数
+
+### `getJwks(value, url)`
+
+从 JWKS 端点获取公钥，并使用 RSA 算法加密指定值。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `value` | `string` | ✅ | 需要加密的明文字符串（通常为用户密码） |
+| `url` | `string` | ✅ | JWKS 接口端点 URL，返回标准 JWKS JSON 格式数据 |
+
+| — | — |
+|---|---|
+| **返回值** | `Promise<string>`，RSA 加密后的密文字符串（十六进制格式） |
+
+---
+
+## 使用示例
+
+```js
+import { getJwks } from 'pit-business-utils'
+
+// 登录时对密码进行加密
+async function login(username, password) {
+  const jwksUrl = `${process.env.VUE_APP_BASE_API}/.well-known/jwks.json`
+  const encryptedPassword = await getJwks(password, jwksUrl)
+
+  await request.post('/api/auth/login', {
+    username,
+    password: encryptedPassword
+  })
+}
+```
+
+---
+
+## 工作流程
+
+```
+1. fetch(url)            → 获取 JWKS JSON 数据
+2. 匹配 kid             → 从 keys 数组中找到 kid === VUE_APP_BASE_JWKS_KID 的密钥
+3. 提取 kty/e/n         → 解析 RSA 公钥参数
+4. KEYUTIL.getKey(jwk)  → 构造 RSA 公钥对象（jsrsasign 库）
+5. Cipher.encrypt(value, pubKey, 'RSAOAEP') → 执行加密
+6. 返回加密后的十六进制字符串
+```
+
+---
+
+## 注意事项
+
+- `VUE_APP_BASE_JWKS_KID` 未配置或与服务端密钥集中的 `kid` 不匹配时，函数将无法找到公钥，**会抛出错误**。
+- 该函数依赖 `jsrsasign` 库（已内置在本库中），无需单独安装。
+- 加密使用 `RSAOAEP` 算法（OAEP 填充的 RSA），服务端需配套使用对应的私钥解密。
+- 每次调用都会发出一次 HTTP 请求获取 JWKS，如登录页频繁使用建议自行缓存 JWKS 响应。

package/docs/pitBusinessUtils/oss.md

@@ -0,0 +1,391 @@
+# oss — OSS 文件服务 API
+
+封装了与 OSS 文件服务后端的全部接口调用，涵盖普通上传、分片上传、下载、预览、删除、重命名等完整文件生命周期管理。
+
+## 引用方式
+
+```js
+import {
+  reqOssUpload,
+  reqOssDownload,
+  reqOssList,
+  reqOssRemove,
+  reqOssPresignedObjectUrl,
+  // ... 其他接口按需引入
+} from 'pit-business-utils'
+```
+
+---
+
+## 接口列表
+
+### 普通上传
+
+#### `reqOssUpload(data, uploadProgress)`
+
+上传单个文件，支持监听上传进度。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `FormData` | ✅ | 包含 `file` 字段的 FormData 对象 |
+| `uploadProgress` | `Function(progressEvent)` | — | 上传进度回调，`progressEvent.loaded / progressEvent.total` 计算百分比 |
+
+| — | — |
+|---|---|
+| **接口** | `POST /api/oss/upload` |
+| **返回值** | `Promise<{ fileUploadRecordId, fileName, fileSize, ... }>` |
+
+```js
+const formData = new FormData()
+formData.append('file', file)
+
+const res = await reqOssUpload(formData, (e) => {
+  const percent = Math.round((e.loaded / e.total) * 100)
+  console.log(`上传进度：${percent}%`)
+})
+```
+
+---
+
+### 分片上传（大文件推荐）
+
+大文件建议使用分片上传，分三步完成：
+
+**Step 1：创建分片上传任务**
+
+#### `reqOssMultipartUploadPost(data)`
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `Object` | ✅ | `{ fileName, fileSize, contentType }` |
+
+| — | — |
+|---|---|
+| **接口** | `POST /api/oss/multipart-upload` |
+| **返回值** | `Promise<{ uploadId, key }>` — `uploadId` 用于后续分片上传 |
+
+---
+
+**Step 2：逐片上传**
+
+#### `reqOssMultipartUploadPut(data)`
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `Object` | ✅ | `{ uploadId, key, partNumber, file }` — `partNumber` 从 1 开始 |
+
+| — | — |
+|---|---|
+| **接口** | `PUT /api/oss/multipart-upload` |
+| **返回值** | `Promise<{ eTag }>` — 每片返回的 ETag |
+
+---
+
+**Step 3：合并分片**
+
+#### `reqOssCompleteMultipartUpload(data)`
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `Object` | ✅ | `{ uploadId, key, parts: [{ partNumber, eTag }] }` |
+
+| — | — |
+|---|---|
+| **接口** | `PUT /api/oss/complete-multipart-upload` |
+| **返回值** | `Promise<{ fileUploadRecordId, ... }>` |
+
+**分片上传完整示例：**
+
+```js
+const CHUNK_SIZE = 5 * 1024 * 1024 // 5MB 每片
+
+async function uploadLargeFile(file) {
+  // Step 1
+  const { uploadId, key } = await reqOssMultipartUploadPost({
+    fileName: file.name, fileSize: file.size, contentType: file.type
+  })
+
+  // Step 2
+  const parts = []
+  const totalChunks = Math.ceil(file.size / CHUNK_SIZE)
+  for (let i = 0; i < totalChunks; i++) {
+    const chunk = file.slice(i * CHUNK_SIZE, (i + 1) * CHUNK_SIZE)
+    const { eTag } = await reqOssMultipartUploadPut({
+      uploadId, key, partNumber: i + 1, file: chunk
+    })
+    parts.push({ partNumber: i + 1, eTag })
+  }
+
+  // Step 3
+  const result = await reqOssCompleteMultipartUpload({ uploadId, key, parts })
+  return result.fileUploadRecordId
+}
+```
+
+---
+
+### 下载
+
+#### `reqOssDownload(data)`
+
+下载单个文件（Blob 格式）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `Object` | ✅ | `{ fileUploadRecordId }` |
+
+| — | — |
+|---|---|
+| **接口** | `GET /api/oss/download`（responseType: blob）|
+| **返回值** | `Promise<Blob>` |
+
+```js
+const blob = await reqOssDownload({ fileUploadRecordId: 'xxx' })
+downloadTemplate(blob, '文件名.pdf')
+```
+
+---
+
+#### `reqOssMultipartDownload(data)`
+
+分片下载（适合大文件下载场景）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `Object` | ✅ | `{ fileUploadRecordId, rangeStart, rangeEnd }` |
+
+| — | — |
+|---|---|
+| **接口** | `GET /api/oss/multipart-download` |
+
+---
+
+#### `downloadZip(data)`
+
+批量下载多个文件，服务端打包为 ZIP 后返回。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `Object` | ✅ | `{ fileUploadRecordIds: string[] }` |
+
+| — | — |
+|---|---|
+| **接口** | `POST /api/oss/download-zip`（responseType: blob）|
+| **返回值** | `Promise<Blob>` |
+
+```js
+const blob = await downloadZip({ fileUploadRecordIds: ['id1', 'id2'] })
+downloadTemplate(blob, '批量下载.zip')
+```
+
+---
+
+### 查询
+
+#### `reqOssList(data)`
+
+查询文件列表。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `Object` | ✅ | 查询参数，如 `{ pageNum, pageSize, fileName }` |
+
+| — | — |
+|---|---|
+| **接口** | `GET /api/oss/list` |
+
+---
+
+#### `reqOssInfo(fileUploadRecordId)`
+
+查询单个文件详情。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `fileUploadRecordId` | `string` | ✅ | 文件 ID |
+
+| — | — |
+|---|---|
+| **接口** | `GET /api/oss/info/:id` |
+| **返回值** | `Promise<{ fileName, fileSize, fileType, url, ... }>` |
+
+```js
+const fileInfo = await reqOssInfo('file-id-xxx')
+console.log(fileInfo.fileName, fileInfo.fileSize)
+```
+
+---
+
+#### `reqOssInfoByYz(fileUploadRecordId)`
+
+获取永中在线预览所需的文件信息。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `fileUploadRecordId` | `string` | ✅ | 文件 ID |
+
+| — | — |
+|---|---|
+| **接口** | `GET /api/oss/officePreview/:id` |
+
+---
+
+#### `reqOssListImage(data)`
+
+查询图片类文件列表（按业务 ID 批量获取关联图片）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `string` | ✅ | 业务关联 ID 字符串 |
+
+| — | — |
+|---|---|
+| **接口** | `GET /api/oss/getList/:data` |
+
+---
+
+#### `reqOssHasStored(data)`
+
+检查文件是否已存储（秒传功能，通过文件 MD5 判断）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `Object` | ✅ | `{ md5, fileName }` |
+
+| — | — |
+|---|---|
+| **接口** | `GET /api/oss/has-stored` |
+| **返回值** | `Promise<{ stored: boolean, fileUploadRecordId? }>` |
+
+```js
+const { stored, fileUploadRecordId } = await reqOssHasStored({ md5: fileMd5, fileName })
+if (stored) {
+  // 秒传：文件已存在，无需重新上传
+  onSuccess(fileUploadRecordId)
+}
+```
+
+---
+
+#### `reqOssPresignedObjectUrl(data)`
+
+获取文件的临时预签名访问 URL（直接访问 OSS，有时效限制）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `Object` | ✅ | `{ fileUploadRecordId }` |
+
+| — | — |
+|---|---|
+| **接口** | `GET /api/oss/presigned-object-url` |
+| **返回值** | `Promise<string>` — 带签名的临时 URL |
+
+```js
+const url = await reqOssPresignedObjectUrl({ fileUploadRecordId: 'xxx' })
+window.open(url)
+```
+
+---
+
+### 操作
+
+#### `reqOssRemove(fileUploadRecordId)`
+
+删除文件。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `fileUploadRecordId` | `string` | ✅ | 文件 ID |
+
+| — | — |
+|---|---|
+| **接口** | `DELETE /api/oss/remove/:id` |
+
+```js
+await reqOssRemove('file-id-xxx')
+```
+
+---
+
+#### `reqOssRename(data)`
+
+重命名文件。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `Object` | ✅ | `{ fileUploadRecordId, fileName }` — 传 `application/x-www-form-urlencoded` 格式 |
+
+| — | — |
+|---|---|
+| **接口** | `PUT /api/oss/rename` |
+
+```js
+await reqOssRename({ fileUploadRecordId: 'xxx', fileName: '新文件名.pdf' })
+```
+
+---
+
+#### `getUpdateFileId(id)`
+
+内容相同的文件重新生成 fileId（用于更新文件后保持 ID 关联）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | `string` | ✅ | 原文件 ID |
+
+| — | — |
+|---|---|
+| **接口** | `GET /api/oss/update-file/:id` |
+
+---
+
+#### `batchCopyFile(data)`
+
+批量复制文件（通常用于归档或初始数据备份）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `Object` | ✅ | `{ fileUploadRecordIds: string[] }` |
+
+| — | — |
+|---|---|
+| **接口** | `POST /api/oss/batch-copy-file` |
+
+---
+
+#### `reqFileTransform(fileId)`
+
+将文件转换为其他格式（如 Office 转 PDF）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `fileId` | `string` | ✅ | 文件 ID |
+
+| — | — |
+|---|---|
+| **接口** | `POST /api/project/file-transform?fileId=:id`（responseType: blob）|
+| **返回值** | `Promise<Blob>` |
+
+---
+
+#### `excelToPdfPreview(data)`
+
+将 Excel 文件转换为 PDF 格式以供预览。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `Object` | ✅ | `{ fileUploadRecordId }` |
+
+| — | — |
+|---|---|
+| **接口** | `POST /api/oss/excelToPdfPreview`（responseType: blob）|
+| **返回值** | `Promise<Blob>` |
+
+---
+
+## 注意事项
+
+- 所有接口均依赖 `request` 模块，需要宿主项目完成 `window.setConfigCallback` 等三个拦截器的配置。
+- 分片上传时，`partNumber` 从 **1** 开始计数（非 0）。
+- `downloadZip`、`reqOssDownload`、`excelToPdfPreview` 返回的是 Blob，需配合 `downloadTemplate` 等工具函数触发浏览器下载。
+- `reqOssPresignedObjectUrl` 返回的 URL 有时效性，请在获取后尽快使用，不要长期缓存。

package/docs/pitBusinessUtils/passwordValidate.md

@@ -0,0 +1,120 @@
+# passwordValidate — 密码强度校验
+
+提供三个密码强度校验函数，覆盖从简单正则到企业级复杂度规则的多种场景。
+
+## 引用方式
+
+```js
+import { passwordValidate, passwordValidateMsg, checkPasswordComplexity } from 'pit-business-utils'
+```
+
+---
+
+## 函数对比
+
+| 函数 | 适用场景 | 返回值 |
+|------|----------|--------|
+| `passwordValidate(pwd)` | 仅需 true/false 判断 | `boolean` |
+| `passwordValidateMsg(pwd)` | 需要向用户展示具体失败原因 | `string（失败） \| undefined（通过）` |
+| `checkPasswordComplexity(pwd)` | 简化场景，只需基本复杂度验证 | `string（失败原因） \| true（通过）` |
+
+---
+
+## 密码规则说明（`passwordValidate` / `passwordValidateMsg`）
+
+以下规则**全部满足**才视为通过：
+
+| 规则 | 说明 |
+|------|------|
+| 长度 | 12 ~ 16 位 |
+| 字符组成 | 同时包含大写字母、小写字母、数字、特殊字符（`!#@*&.?%~/+=$_^-`）|
+| 无重复 | 不允许 4 位及以上相同字符（如 `aaaa`、`1111`） |
+| 无字母连续 | 不允许 4 位字母连续序列（如 `abcd`、`wxyz`） |
+| 无数字连续 | 不允许 4 位数字连续序列（如 `1234`、`6789`） |
+| 无键盘横向连续 | 不允许键盘上横向 4 连按键（如 `qwer`、`asdf`） |
+| 无键盘斜向连续 | 不允许键盘斜向 4 连按键 |
+| 无 ASCII 连续 | 不允许任意 3 位 ASCII 码差值为 1 的连续字符 |
+
+---
+
+## 函数详情
+
+### `passwordValidate(pwd)`
+
+全量密码强度校验，适合在提交前做最终验证。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `pwd` | `string` | ✅ | 待校验的密码字符串 |
+
+| — | — |
+|---|---|
+| **返回值** | `boolean`，满足所有规则返回 `true`，否则 `false` |
+
+```js
+if (!passwordValidate(form.newPassword)) {
+  this.$message.error('密码不符合安全要求')
+  return
+}
+```
+
+---
+
+### `passwordValidateMsg(pwd)`
+
+校验密码强度并返回**具体失败原因**（i18n 文本），通过时无返回值（`undefined`）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `pwd` | `string` | ✅ | 待校验的密码字符串 |
+
+| — | — |
+|---|---|
+| **返回值** | `string`（不通过时，具体的失败原因）或 `undefined`（通过时） |
+
+```js
+const errMsg = passwordValidateMsg(form.password)
+if (errMsg) {
+  this.$message.warning(errMsg) // 如 "密码不能包含4个及以上连续相同字符"
+  return
+}
+// 密码合法，继续提交
+```
+
+---
+
+### `checkPasswordComplexity(password)`
+
+简化版密码复杂度校验：仅验证长度（12-16位）和字符种类（大写、小写、数字、特殊字符），**不检查连续/重复字符规则**，适合实时输入反馈场景。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `password` | `string` | ✅ | 待校验的密码字符串 |
+
+| — | — |
+|---|---|
+| **返回值** | `true`（验证通过）或 `string`（验证失败的错误提示文本） |
+
+```js
+// 配合 Element UI 自定义校验器
+const validatePass = (rule, value, callback) => {
+  const result = checkPasswordComplexity(value)
+  if (result !== true) {
+    callback(new Error(result))
+  } else {
+    callback()
+  }
+}
+
+rules: {
+  password: [{ validator: validatePass, trigger: 'blur' }]
+}
+```
+
+---
+
+## 注意事项
+
+- `passwordValidate` 和 `passwordValidateMsg` 使用**完整规则**，安全性更强，推荐在修改密码场景使用。
+- `checkPasswordComplexity` 规则相对宽松，适合注册场景的实时格式检查。
+- 如果项目配置了 `i18n`，`passwordValidateMsg` 返回的错误文本会自动走国际化翻译。