pit-docs-mcp 1.0.2

package/docs/pitBusinessUi/upload-file-dialog.md

@@ -0,0 +1,86 @@
+# pit-upload-file-dialog 文件上传（弹窗式）
+
+将文件列表管理放入弹窗，提供"上传输入框 + 触发按钮"的外观，点击打开管理弹窗后再保存。
+
+## 前置依赖
+
+与 `PitUploadFile` 一致：需注入 `this.env`、`this.request`、`this.isOk`。
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 已上传文件 ID 串（逗号分隔） | String | `""` |
+| limit | 最大上传数量 | Number | `10` |
+| multiple | 是否支持多选 | Boolean | `false` |
+| fileType | 允许的文件后缀数组 | Array | `[]` |
+| fileSize | 单文件最大体积（MB） | Number | `5000` |
+| drag | 是否支持拖拽 | Boolean | `false` |
+| disabled | 是否禁用 | Boolean | `false` |
+| hasSlice | 是否开启分片上传 | Boolean | `true` |
+| autoSliceSize | 触发分片的文件大小阈值（MB） | Number | `50` |
+| accept | 原生 accept 属性 | String | `"*"` |
+| placeholder | 输入框占位文本 | String | `"请上传文件"` |
+| isUploadInput | 是否显示展示文件名的输入框 | Boolean | `true` |
+| isUploadBtn | 是否显示触发弹窗的按钮 | Boolean | `true` |
+| buttonType | 触发按钮类型 | String | `"primary"` |
+| buttonText | 触发按钮文案 | String | `"上传文件"` |
+| buttonSize | 触发按钮大小 | String | `"small"` |
+| fileBtnText | 弹窗内上传按钮文案 | String | `"点击上传"` |
+| delBtnText | 弹窗内批量清空按钮文案 | String | `"清空列表"` |
+| isHiddenPreviewBtn | 是否显示文件预览按钮 | Boolean | `true` |
+| isHiddenDownloadBtn | 是否显示文件下载按钮 | Boolean | `true` |
+| isHiddenDeleteBtn | 是否显示文件删除按钮 | Boolean | `true` |
+| isHiddenFileBtn | 是否显示上传按钮（弹窗内） | Boolean | `true` |
+| isHiddenFileBatchDelete | 是否显示批量删除按钮 | Boolean | `true` |
+| bucketAccessPolicy | 存储桶访问策略 | String / Number | `null` |
+| otherData | 额外上传参数 | Object | `{}` |
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 点击"确认"后触发（v-model） | `String`（逗号分隔 ID） |
+| file-success | 点击确认后返回文件列表和 ID 串 | `FileList[]`，`String` |
+| preview | 点击文件预览按钮时触发 | `FileItem`，`Number`（index） |
+
+## 示例
+
+### 基础用法
+
+```vue
+<pit-upload-file-dialog v-model="form.attachments" />
+```
+
+### 只读模式（仅预览，不可上传/删除）
+
+```vue
+<pit-upload-file-dialog
+  v-model="form.attachments"
+  :is-hidden-file-btn="false"
+  :is-hidden-delete-btn="false"
+  :is-hidden-file-batch-delete="false"
+  :disabled="true" />
+```
+
+### 监听预览事件
+
+```vue
+<pit-upload-file-dialog
+  v-model="form.attachments"
+  @preview="handlePreview" />
+
+<script>
+methods: {
+  handlePreview(item, index) {
+    // item: { fileUploadRecordId, originalFilename, ... }
+    this.$openFilePreview(item.fileUploadRecordId)
+  }
+}
+</script>
+```
+
+## 注意事项
+
+- 文件不会在点击删除时立即调接口删除，而是**点击确认后才同步 value**。
+- `isHiddenXxx` 命名语义为"是否显示"（`true` 显示，`false` 隐藏），注意不要误读为"是否隐藏"。

package/docs/pitBusinessUi/upload-file.md

@@ -0,0 +1,77 @@
+# pit-upload-file 文件上传
+
+基于 `el-upload` 封装，支持普通上传与分片上传，文件 ID 以逗号分隔字符串存储。
+
+## 前置依赖
+
+- 项目需注入 `this.env.VUE_APP_BASE_API`（上传接口 base URL）
+- 需注入 `this.request`（HTTP 请求方法，分片上传时使用）
+- 需注入 `this.isOk`（接口成功状态码，默认对比 `res.code`）
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 已上传文件 ID（逗号分隔字符串） | String | `""` |
+| limit | 最大上传数量 | Number | `10` |
+| multiple | 是否支持多选文件 | Boolean | `true` |
+| fileType | 允许的文件后缀数组（空数组不限制） | Array | `[]` |
+| fileSize | 单文件最大体积（MB） | Number | `50` |
+| drag | 是否启用拖拽上传 | Boolean | `false` |
+| showFileList | 是否显示文件列表 | Boolean | `true` |
+| showFileTips | 是否显示格式/大小提示 | Boolean | `true` |
+| disabled | 是否禁用 | Boolean | `false` |
+| hasSlice | 是否启用分片上传 | Boolean | `false` |
+| autoSliceSize | 触发分片上传的文件大小阈值（MB） | Number | `50` |
+| accept | 原生 accept 属性 | String | `"*"` |
+| bucketAccessPolicy | 存储桶访问策略 | String / Number | `null` |
+| otherData | 额外上传参数（合并到 POST 请求） | Object | `{}` |
+| fileBtnText | 上传按钮文案 | String | `"点击上传"` |
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 上传/删除文件后更新 ID 串（v-model） | `String`（逗号分隔） |
+| change | 同 input | `String`，`FileResponse` |
+| preview | 文件列表初始化完成后触发 | `Array`（文件对象列表） |
+| file-success | 分片上传成功后触发 | `FileObj`，`FileList` |
+
+## 示例
+
+### 基础用法
+
+```vue
+<pit-upload-file v-model="form.attachments" />
+```
+
+### 限制类型与大小
+
+```vue
+<pit-upload-file
+  v-model="form.attachments"
+  :file-type="['pdf', 'doc', 'docx']"
+  :file-size="20"
+  :limit="5" />
+```
+
+### 启用分片上传（大文件）
+
+```vue
+<pit-upload-file
+  v-model="form.attachments"
+  :has-slice="true"
+  :auto-slice-size="10" />
+```
+
+### 拖拽上传
+
+```vue
+<pit-upload-file v-model="form.attachments" drag />
+```
+
+## 注意事项
+
+- `value` 存储的是文件 ID（`fileUploadRecordId`），不是文件 URL。
+- 组件初始化会根据传入的 ID 串自动调接口获取文件列表展示。
+- 分片上传依赖 `this.request`、`this.env`、`this.isOk` 全局注入，需在项目根实例或混入中提供。

package/docs/pitBusinessUi/upload-list-card.md

@@ -0,0 +1,62 @@
+# pit-upload-list-card 图片卡片上传
+
+图片卡片式多图上传，展示缩略图列表，支持预览、重命名、删除，基于 `el-upload` 的 `picture-card` 模式。
+
+## 前置依赖
+
+- `this.request` / `this.env.VUE_APP_BASE_API` — 上传接口
+- `pit-business-utils` — `reqOssListImage`、`reqOssRename`、`getToken`
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 文件 ID 字符串（逗号分隔）或 ID 数组 | Array / String | `""` |
+| disabled | 是否禁用 | Boolean | `false` |
+| size | 卡片尺寸（`"normal"` / `"small"` / `"mini"`） | String | `"normal"` |
+| limit | 最大上传数量（`0` 表示无限制） | Number | `0` |
+| fileSize | 单文件大小上限（MB） | Number | `50` |
+| accept | 允许的文件类型（MIME 或扩展名） | String | `"image/*"` |
+| multiple | 是否支持多文件同时上传 | Boolean | — |
+| drag | 是否支持拖拽上传 | Boolean | — |
+| beforeUploadCheck | 上传前自定义校验函数（返回 `true` 才继续上传） | Function | `() => true` |
+| isShowDel | 是否显示删除按钮 | Boolean | `true` |
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 上传/删除后更新值（v-model） | `String`（逗号分隔 ID） |
+
+## 示例
+
+### 基础用法
+
+```vue
+<pit-upload-list-card v-model="form.imageIds" />
+```
+
+### 限制数量和格式
+
+```vue
+<pit-upload-list-card
+  v-model="form.photoIds"
+  :limit="9"
+  :file-size="10"
+  accept="image/jpeg,image/png" />
+```
+
+### 只读展示
+
+```vue
+<pit-upload-list-card
+  v-model="form.imageIds"
+  :disabled="true"
+  :is-show-del="false" />
+```
+
+## 注意事项
+
+- 卡片内置支持"重命名"功能，通过弹窗输入新名称后调用 `reqOssRename` API 更新文件名。
+- 点击预览图标调用 `el-image` 内置查看器；点击删除图标（非禁用状态）移除文件。
+- `value` 支持逗号分隔字符串和数组两种格式，组件内部统一转换为文件列表。

package/docs/pitBusinessUi/upload-table.md

@@ -0,0 +1,77 @@
+# pit-upload-table 表格式附件上传
+
+带标题栏和 `el-form-item` 包裹的附件上传组件，内部使用 `PitUploadList` 展示文件列表，点击文件可触发内置预览。
+
+## 前置依赖
+
+- `this.request` / `this.env.VUE_APP_BASE_API` — 上传接口
+- `pit-business-utils` — `fileType`、`reqOssDownload`
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 文件 ID 字符串（逗号分隔） | String | — |
+| label | `el-form-item` 标签文字 | String | 国际化"附件" |
+| propKey | `el-form-item` 的 prop（表单校验字段名） | String | `"fileId"` |
+| title | 区块标题（`noTitle=false` 时显示） | String | 国际化"附件信息" |
+| noTitle | 是否隐藏区块标题 | Boolean | `false` |
+| noFormItem | 是否不渲染 `el-form-item` 包裹 | Boolean | `false` |
+| disabled | 是否禁用上传 | Boolean | `false` |
+| isShowBtn | 是否显示上传按钮 | Boolean | `true` |
+| browse | 是否仅浏览（隐藏预览按钮，用于模型管理） | Boolean | `false` |
+| previewType | 预览类型：`"preview"` / `"openFilePreview"` | String | `"preview"` |
+| previewCallBack | 自定义预览回调（传入后替代内置预览） | Function | `null` |
+| baseUrl | 上传接口 Base URL（覆盖默认） | String | `""` |
+| drag | 是否启用拖拽上传（`null` 时读取全局 `$Business.uploadDefaultDrag`） | Boolean / null | `null` |
+
+> 其余属性通过 `v-bind="$attrs"` / `v-on="$listeners"` 向内透传至 `PitUploadList`。
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 值变化（v-model） | `String`（逗号分隔 ID） |
+| preview | 点击文件名预览时触发 | `fileObj` |
+| download | 点击下载时触发 | `fileObj` |
+
+## Slots
+
+| 插槽名 | 说明 |
+| --- | --- |
+| fileTip | 上传区域下方的提示文字 |
+
+## 示例
+
+### 标准用法（表单内）
+
+```vue
+<pit-upload-table
+  v-model="form.fileId"
+  prop-key="fileId"
+  label="附件材料" />
+```
+
+### 无标题、无 FormItem 包裹
+
+```vue
+<pit-upload-table
+  v-model="form.fileId"
+  no-title
+  no-form-item />
+```
+
+### 自定义上传提示
+
+```vue
+<pit-upload-table v-model="form.fileId">
+  <template slot="fileTip">
+    <span class="text-gray">仅支持 PDF、Word（≤50MB）</span>
+  </template>
+</pit-upload-table>
+```
+
+## 注意事项
+
+- `drag` prop 为 `null` 时，组件读取 `this.$Business.uploadDefaultDrag` 全局配置决定是否显示拖拽区域。
+- 内置预览支持 PDF、Office、视频、BIM 模型等类型（通过 `PitPreview` 分发），具体格式判断依赖 `pit-business-utils` 的 `fileType`。

package/docs/pitBusinessUi/user-transform.md

@@ -0,0 +1,72 @@
+# pit-user-transform 用户穿梭选择器
+
+左右双栏用户选择组件。左栏以懒加载树展示组织架构，支持关键词搜索；右栏显示已选用户列表，支持逐条删除或一键清空。与 `PitTransfer` 系列不同，内置调用用户/组织 API。
+
+## 前置依赖
+
+- `pit-business-utils` — `getImUserSelector`（关键词搜索用户）、`getOrganization`（懒加载组织树）
+- mixin：`getFullName(data)` — 计算用户显示名称（`姓名(账号)`）
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 已选用户数据对象数组 | Array | `[]` |
+| multiple | 是否允许多选（`false` 时点击自动替换当前选中） | Boolean | `false` |
+| height | 组件总高度 | String | `"420px"` |
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 已选用户列表变化（v-model） | `Array`（用户对象数组） |
+
+## 示例
+
+### 单选（选择审批人）
+
+```vue
+<pit-user-transform
+  v-model="form.approver"
+  :multiple="false" />
+
+<!-- form.approver 为长度 ≤ 1 的数组 -->
+```
+
+### 多选（选择抄送人）
+
+```vue
+<pit-user-transform
+  v-model="form.ccUsers"
+  :multiple="true"
+  height="500px" />
+```
+
+### 在弹窗中使用
+
+```vue
+<pit-dialog
+  title="选择用户"
+  :visible.sync="userPickerVisible"
+  width="700px">
+  <pit-user-transform
+    v-model="tempUsers"
+    :multiple="true" />
+  <div slot="footer">
+    <el-button @click="userPickerVisible = false">取消</el-button>
+    <el-button type="primary" @click="confirmUsers">确认</el-button>
+  </div>
+</pit-dialog>
+```
+
+## 交互说明
+
+1. **左栏树**：懒加载组织架构（点击展开），支持在搜索框输入关键词后按 Enter 或点击搜索按钮过滤用户。
+2. **选中高亮**：已在右栏的用户在左树中以不同样式高亮显示。
+3. **右栏操作**：逐条 × 删除 或"清空"按钮一键清除所有已选。
+
+## 注意事项
+
+- 组件注册名为 `user-transform`，但源码中组件名为 `PitUserTransform`（非 `PitUserTransfer`），注意与 `PitTransfer` 系列的区分。
+- `value` 数组中每个用户对象由 API 返回的原始结构组成，`getFullName(data)` mixin 从 `data.name`（姓名）和 `data.loginName`（账号）生成显示文字。
+- 非 `multiple` 模式下，点击新用户自动替换已选用户（右栏始终 ≤ 1 条）。

package/docs/pitBusinessUi/utils.md

@@ -0,0 +1,272 @@
+# 原型工具函数
+
+安装 `PitBusinessUI` 后，以下方法挂载到 `Vue.prototype`，在任意组件中通过 `this.$xxx()` 调用。**所有方法均以 `this` 作为上下文执行**，内部调用 `this.request`、`this.$message` 等，须在组件实例内使用（不可在普通函数中直接调用）。
+
+---
+
+## 文件下载系列
+
+### `$downloadFile(fileId, progressOptions?)`
+
+通过文件 ID 从 OSS 下载单个文件，顶部显示 NProgress 进度条。
+
+**参数**
+
+| 参数 | 说明 | 类型 | 必填 |
+| --- | --- | --- | --- |
+| fileId | 文件上传记录 ID（`fileUploadRecordId`） | String | ✅ |
+| progressOptions | NProgress 配置项（如 `{ minimum: 0.1 }`） | Object | — |
+
+**流程**
+
+1. 调用 `/api/oss/info/:fileId` 获取原始文件名
+2. 调用 `/api/oss/download?fileUploadRecordId=xxx` 以 blob 方式下载
+3. 通过 `js-file-download` 触发浏览器保存对话框
+
+**示例**
+
+```js
+// 下载单个附件
+this.$downloadFile(row.fileUploadRecordId)
+
+// 自定义 NProgress 最小进度
+this.$downloadFile(fileId, { minimum: 0.05 })
+```
+
+---
+
+### `$downloadZip(fileIds, fileName?)`
+
+将多个文件 ID 打包为 ZIP 后下载。
+
+**参数**
+
+| 参数 | 说明 | 类型 | 必填 |
+| --- | --- | --- | --- |
+| fileIds | 文件 ID 数组 | Array\<String\> | ✅ |
+| fileName | ZIP 文件名（含 `.zip` 后缀） | String | — |
+
+**接口**：`POST /api/oss/download-zip`，请求体 `{ parentFileName, fileIds }`
+
+**示例**
+
+```js
+this.$downloadZip(['id1', 'id2', 'id3'], '合同附件.zip')
+```
+
+---
+
+### `$downloadBlob(blob, fileName?, isTip?)`
+
+直接将内存中的 Blob 对象保存为文件，常用于接口返回二进制流的场景。
+
+**参数**
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| blob | Blob 对象 | Blob | — |
+| fileName | 保存的文件名 | String | `"导入模板"` |
+| isTip | 是否弹出下载成功提示 | Boolean | `true` |
+
+**示例**
+
+```js
+this.request({ url: '/api/report/export', responseType: 'blob' }).then(res => {
+  this.$downloadBlob(res.data, '月度报表.xlsx')
+})
+```
+
+---
+
+### `$downloadUrl(url, fileName?, type?)`
+
+通过 XHR 下载远程 URL 的文件内容（GET 请求），不带鉴权头，适合下载公开静态资源（如模板文件）。
+
+**参数**
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| url | 文件完整 URL | String | — |
+| fileName | 保存的文件名 | String | `"导入模板"` |
+| type | Blob MIME 类型 | String | `"text/csv"` |
+
+**示例**
+
+```js
+// 下载 CSV 模板
+this.$downloadUrl(
+  'https://cdn.example.com/templates/import.csv',
+  '标准导入模板.csv',
+  'text/csv'
+)
+
+// 下载 Excel 模板
+this.$downloadUrl(templateUrl, '导入模板.xlsx', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet')
+```
+
+---
+
+### `$exportMeted(response, fileName?)`
+
+将 Axios 响应对象中的 blob 数据保存为文件，自动从响应头 `content-disposition` 提取文件名。
+
+**参数**
+
+| 参数 | 说明 | 类型 |
+| --- | --- | --- |
+| response | Axios 完整响应对象（需设置 `responseType: 'blob'`） | AxiosResponse |
+| fileName | 兜底文件名（优先使用响应头中的文件名） | String |
+
+**示例**
+
+```js
+this.request({
+  url: '/api/export/contract',
+  method: 'post',
+  data: this.queryParams,
+  responseType: 'blob'
+}).then(res => {
+  this.$exportMeted(res, '合同列表导出.xlsx')
+})
+```
+
+---
+
+## 文件预览
+
+### `$openFilePreview(fileId, option?)`
+
+根据文件格式自动选择预览策略，新窗口打开（图片格式使用页内浮层）。
+
+**参数**
+
+| 参数 | 说明 | 类型 | 必填 |
+| --- | --- | --- | --- |
+| fileId | 文件上传记录 ID | String | ✅ |
+| option | 预览选项（见下表） | Object | — |
+
+**option 字段**
+
+| 字段 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| `key` | 预览路由传参方式（`"fileObj"` 或自定义） | String | `"fileObj"` |
+| `watermark` | 水印配置对象（`{ text, watermark_alpha, watermark_angle }`） | Object | `null` |
+| `onBeforeOpend` | 打开新窗口前的回调 | Function(fileInfo) | — |
+| `onOpened` | 新窗口 `onload` 后的回调 | Function(win, fileInfo) | — |
+| `onClosed` | 新窗口关闭后的回调（轮询检测） | Function(win, fileInfo) | — |
+| `onError` | 方法内部异常的回调 | Function(error) | — |
+| `onApiSuccess` | 接口成功回调 | Function(url, response) | — |
+| `onApiError` | 接口失败回调 | Function(url, error) | — |
+
+**预览策略**
+
+| 文件格式 | 策略 |
+| --- | --- |
+| `png / jpg / jpeg / ico` | 页内图片浏览器（`PitPreviewImage` 浮层） |
+| `xlsx / xls / doc / docx / pdf` | 打开 `/previewOffice_0X1` 路由页（`key="fileObj"` 时跳转 `/preview`） |
+| 其他 | 提示"不支持预览" |
+
+**示例**
+
+```js
+// 基础用法
+this.$openFilePreview(row.fileUploadRecordId)
+
+// 携带水印
+this.$openFilePreview(fileId, {
+  watermark: {
+    text: `${this.userInfo.username} ${this.$dayjs().format('YYYY-MM-DD HH:mm:ss')}`,
+    watermark_alpha: 0.2
+  },
+  onClosed: () => {
+    this.$message.info('预览窗口已关闭')
+  }
+})
+```
+
+---
+
+## 通用导入弹窗
+
+### `$openBaseImport(option)`
+
+以编程方式创建并挂载通用导入弹窗，弹窗提供"下载模板"和"上传文件"两步交互，无需在模板中声明组件。
+
+**option 字段**
+
+| 字段 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| `title` | 弹窗标题 | String | `"导入"` |
+| `templateInterface` | 下载模板的接口 URL | String | — |
+| `templateInterfaceMethod` | 下载模板接口请求方法 | String | `"POST"` |
+| `templateParams` | 下载模板接口附加参数 | Object | `{}` |
+| `templateFileName` | 模板保存文件名（优先于响应头） | String | — |
+| `importInterface` | 上传导入的接口 URL | String | — |
+| `importInterfaceMethod` | 上传接口请求方法 | String | `"POST"` |
+| `importParams` | 上传接口附加 URL 参数 | Object | `{}` |
+| `importData` | 上传接口附加 FormData 字段 | Object | `{}` |
+| `limit` | 单次上传文件数量限制 | Number | `1` |
+| `category` | OSS 文件分类标识 | String | `""` |
+| `accept` | 允许的文件类型 | String | `".xls,.xlsx,.xlsb,.xlsm,.xlst"` |
+| `importResponseType` | 导入接口响应类型 | String | `"blob"` |
+| `beforeUpload` | 自定义上传前钩子（替换默认上传按钮行为） | Function(app) | `null` |
+| `beforeImportParams` | 修改 FormData 的钩子 | Function(formData) | `null` |
+| `beforeHttpRequest` | 完全接管 HTTP 请求的钩子 | Function(file) | `null` |
+| `success` | 导入成功回调 | Function(app, responseData) | — |
+| `close` | 弹窗关闭回调 | Function(app) | — |
+
+**返回值**：弹窗 Vue 实例 `app`，可调用 `app.close()` 编程关闭。
+
+**示例**
+
+```js
+// 基础用法：模板下载 + 文件上传
+this.$openBaseImport({
+  title: '导入合同',
+  templateInterface: '/api/contract/importTemplate',
+  importInterface: '/api/contract/import',
+  importData: { projectId: this.projectId },
+  success(app, data) {
+    app.close()               // 关闭弹窗
+    this.$message.success('导入成功')
+    this.loadTable()          // 刷新列表
+  }
+})
+
+// 导入成功后需要下载错误报告（接口返回 blob）
+this.$openBaseImport({
+  title: '批量导入人员',
+  templateInterface: '/api/user/template',
+  importInterface: '/api/user/import',
+  importResponseType: 'blob',
+  success(app, blobData) {
+    // 如果后端返回了错误报表 blob，直接下载
+    this.$downloadBlob(blobData, '导入结果.xlsx')
+    app.close()
+  }
+})
+
+// 自定义上传前操作（如需手动触发上传）
+this.$openBaseImport({
+  beforeUpload: (app) => {
+    // app 是弹窗实例，自行触发文件选择
+    app.$refs.fileInputRef.click()
+  },
+  success(app) { app.close() }
+})
+```
+
+**注意事项**
+
+- `success` 和 `close` 回调中的 `this` **不是组件 this**，是弹窗 Vue 实例（`app`）。若需访问父组件，请用箭头函数 + 外层变量捕获：
+  ```js
+  const self = this
+  this.$openBaseImport({
+    success(app) {
+      app.close()
+      self.loadTable()
+    }
+  })
+  ```
+- 弹窗实例在关闭后自动 `$destroy()` 并从 DOM 移除，无需手动清理。
+- 上传接口固定为 `POST /api/oss/upload`（FormData），导入接口由 `importInterface` 单独配置。