# 教师业务档案导出接口文档 ## 1. 功能说明 档案管理中的教师管理支持导出 J2 教师业务档案: - 勾选一名教师时,直接下载一份可由 Word/WPS 打开的 `.doc` 文件。 - 勾选多名教师时,下载 ZIP 压缩包,每名教师对应一份 `.doc` 文件。 - 本文接口路径均为相对业务服务路径,鉴权 Token 沿用项目现有请求拦截器。 ## 2. 单个教师档案导出 ### 2.1 请求 ```http GET /user/teacher/{teacherId}/export ``` 路径参数: | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `teacherId` | String | 是 | 教师用户 ID | 请求示例: ```http GET /user/teacher/1896453829184000001/export ``` ### 2.2 成功响应 ```http Content-Type: application/msword Content-Disposition: attachment; filename*=UTF-8''%E5%BC%A0%E4%B8%89_J2%E6%95%99%E5%B8%88%E4%B8%9A%E5%8A%A1%E6%A1%A3%E6%A1%88.doc ``` 响应体为保留 J2 原模板版式、可由 Word/WPS 直接打开的 `.doc` 文件数据。 文件名格式: ```text 教师姓名_J2教师业务档案.doc ``` ## 3. 批量教师档案导出 ### 3.1 请求 ```http POST /user/teacher/export Content-Type: application/json ``` 请求体示例: ```json { "teacherIds": [ "1896453829184000001", "1896453829184000002" ] } ``` 请求字段: | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `teacherIds` | String[] | 是 | 当前勾选的教师 ID;后端自动去重,单次最多导出 500 名教师 | ### 3.2 成功响应 ```http Content-Type: application/zip Content-Disposition: attachment; filename*=UTF-8''J2%E6%95%99%E5%B8%88%E4%B8%9A%E5%8A%A1%E6%A1%A3%E6%A1%88_20261028113000.zip ``` 响应体为 ZIP 文件的二进制数据。 ZIP 文件名格式: ```text J2教师业务档案_yyyyMMddHHmmss.zip ``` ZIP 内文件名示例: ```text 张三_1234_J2教师业务档案.doc 李四_5678_J2教师业务档案.doc ``` 同名且身份证后四位相同时,后端会自动追加教师 ID,避免 ZIP 内文件被覆盖。 ## 4. 前端调用规则 - 只勾选一名教师:调用单个导出接口,直接下载 `.doc`。 - 勾选两名及以上教师:调用批量导出接口,下载 `.zip`。 - 未勾选教师:前端提示“请选择需要导出的教师”,不发送请求。 - 请求必须设置 `responseType: 'blob'`,否则二进制文件可能损坏。 - 下载按钮建议在请求期间显示加载状态,防止用户重复提交。 ## 5. Axios 调用示例 ### 5.1 文件名解析与下载 ```javascript /** * 从 Content-Disposition 响应头中解析 UTF-8 文件名。 */ function getDownloadFileName(disposition, fallbackName) { if (!disposition) { return fallbackName } const utf8Match = disposition.match(/filename\*=UTF-8''([^;]+)/i) if (utf8Match) { return decodeURIComponent(utf8Match[1]) } const normalMatch = disposition.match(/filename="?([^";]+)"?/i) return normalMatch ? normalMatch[1] : fallbackName } /** * 将后端返回的 Blob 保存为本地文件。 */ function saveBlob(blob, fileName) { const url = URL.createObjectURL(blob) const link = document.createElement('a') link.href = url link.download = fileName document.body.appendChild(link) link.click() link.remove() URL.revokeObjectURL(url) } ``` ### 5.2 单个教师导出 ```javascript export async function exportTeacherArchive(teacherId) { const response = await axios.get( `/user/teacher/${encodeURIComponent(teacherId)}/export`, { responseType: 'blob' } ) const fileName = getDownloadFileName( response.headers['content-disposition'], 'J2教师业务档案.doc' ) saveBlob(response.data, fileName) } ``` ### 5.3 批量教师导出 ```javascript export async function exportTeacherArchives(teacherIds) { const response = await axios.post( '/user/teacher/export', { teacherIds }, { responseType: 'blob' } ) const fileName = getDownloadFileName( response.headers['content-disposition'], 'J2教师业务档案.zip' ) saveBlob(response.data, fileName) } ``` ### 5.4 根据勾选数量调用接口 ```javascript async function handleExport(selectedRows) { const teacherIds = selectedRows.map(item => item.id) if (teacherIds.length === 0) { ElMessage.warning('请选择需要导出的教师') return } try { if (teacherIds.length === 1) { await exportTeacherArchive(teacherIds[0]) } else { await exportTeacherArchives(teacherIds) } } catch (error) { const message = await readBlobError(error) ElMessage.error(message) } } ``` ## 6. Blob 错误响应处理 由于请求设置了 `responseType: 'blob'`,后端返回的 JSON 业务错误也可能被 Axios 包装为 Blob。前端应统一解析: ```javascript async function readBlobError(error) { const data = error?.response?.data if (!(data instanceof Blob)) { return error?.message || '导出失败' } try { const text = await data.text() const result = JSON.parse(text) return result.msg || result.message || '导出失败' } catch (e) { return '导出失败' } } ``` ## 7. 业务错误说明 | 场景 | 错误信息 | | --- | --- | | 未选择教师 | 请选择需要导出的教师 | | 超过数量限制 | 单次最多导出500名教师 | | 教师不存在 | 教师不存在或已删除 | | 选择了非教师用户 | 所选用户不是教师,无法导出教师业务档案 | | 身份证超过模板容量 | 教师身份证号超过J2模板的18位容量 | | 从业经历过多 | 从业经历超过J2模板预留的N行 | | 任教经历过多 | 任教经历超过J2模板预留的N行 | | 模板结构异常 | J2模板结构已变化,请重新确认字段映射 | | 单份文件生成失败 | 生成教师J2业务档案失败 | | ZIP 生成失败 | 批量导出教师业务档案失败 | | HTTP 响应写出失败 | 写出教师业务档案失败 | ## 8. 跨域响应头配置 前端需要读取 `Content-Disposition` 获取后端生成的文件名。如果前端和网关存在跨域访问,网关必须暴露该响应头: ```http Access-Control-Expose-Headers: Content-Disposition ``` 如果网关已经统一配置响应头暴露,则不需要针对本接口重复配置。