Commit a98260c1 authored by wujipeng's avatar wujipeng
Browse files

教师导出

parent 5763962b
# 教师业务档案导出接口文档
## 1. 功能说明
档案管理中的教师管理支持导出 J2 教师业务档案:
- 勾选一名教师时,直接下载一份 Word 97-2003 `.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
```
响应体为 Word 97-2003 `.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
```
如果网关已经统一配置响应头暴露,则不需要针对本接口重复配置。
package com.platform.business.model.dto;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.util.List;
/**
* 教师业务档案批量导出请求。
*
* <p>前端只传递当前勾选的教师ID;后端会保持首次出现的顺序并自动去重。</p>
*/
@Data
public class TeacherArchiveExportDTO {
@ApiModelProperty("当前勾选的教师ID列表,单次最多500个")
private List<String> teacherIds;
}
package com.platform.business.controller;
import com.platform.business.model.dto.TeacherArchiveExportDTO;
import com.platform.business.model.dto.UserDTO;
import com.platform.business.model.vo.UserVO;
import com.platform.business.service.UserService;
......@@ -13,6 +14,7 @@ import org.springframework.web.multipart.MultipartFile;
import javax.annotation.Resource;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
@RestController
@RequestMapping("/user")
......@@ -67,6 +69,19 @@ public class UserController extends BaseController {
return Result.data(userService.teacherImport(file));
}
@ApiOperation("导出单个教师J2业务档案")
@GetMapping("/teacher/{teacherId}/export")
public void exportTeacherArchive(@PathVariable String teacherId, HttpServletResponse response) {
userService.exportTeacherArchive(teacherId, response);
}
@ApiOperation("批量导出已勾选教师的J2业务档案ZIP")
@PostMapping("/teacher/export")
public void exportTeacherArchives(@RequestBody TeacherArchiveExportDTO request,
HttpServletResponse response) {
userService.exportTeacherArchives(request, response);
}
@ApiOperation("获取用户信息")
@GetMapping("/getUserMessage")
public Result<UserVO> getUserMessage(HttpServletRequest httpServletRequest) {
......
package com.platform.business.service;
import com.baomidou.mybatisplus.extension.service.IService;
import com.platform.business.model.dto.TeacherArchiveExportDTO;
import com.platform.business.model.dto.UserDTO;
import com.platform.business.model.entity.UserEntity;
import com.platform.business.model.vo.UserVO;
import com.platform.model.resp.Result;
import org.springframework.web.multipart.MultipartFile;
import javax.servlet.http.HttpServletResponse;
import java.util.List;
public interface UserService extends IService<UserEntity> {
......@@ -22,6 +24,12 @@ public interface UserService extends IService<UserEntity> {
Object teacherImport(MultipartFile file);
/** 按J2原始模板导出单个教师业务档案。 */
void exportTeacherArchive(String teacherId, HttpServletResponse response);
/** 将当前勾选教师的J2业务档案打包为ZIP。 */
void exportTeacherArchives(TeacherArchiveExportDTO request, HttpServletResponse response);
Result updatePassword(UserDTO userDTO);
UserVO getUserMessage(String userName);
......
......@@ -4,6 +4,7 @@ import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
import com.google.common.collect.Lists;
import com.platform.business.mapper.UserMapper;
import com.platform.business.model.dto.TeacherArchiveExportDTO;
import com.platform.business.model.dto.UserDTO;
import com.platform.business.model.entity.*;
import com.platform.business.model.vo.SysRoleAndMenuVO;
......@@ -32,6 +33,7 @@ import org.springframework.web.multipart.MultipartFile;
import org.springframework.web.multipart.commons.CommonsMultipartFile;
import javax.annotation.Resource;
import javax.servlet.http.HttpServletResponse;
import java.io.*;
import java.math.BigDecimal;
import java.util.ArrayList;
......@@ -57,6 +59,10 @@ public class UserServiceImpl extends ServiceImpl<UserMapper, UserEntity> impleme
@Resource
private BsFileService bsFileService;
/** J2档案生成细节独立封装,避免继续扩大教师导入方法的职责。 */
@Resource
private TeacherArchiveExportService teacherArchiveExportService;
@Resource
private SysRoleAndMenuService sysRoleAndMenuService;
......@@ -324,6 +330,16 @@ public class UserServiceImpl extends ServiceImpl<UserMapper, UserEntity> impleme
}
}
@Override
public void exportTeacherArchive(String teacherId, HttpServletResponse response) {
teacherArchiveExportService.exportOne(teacherId, response);
}
@Override
public void exportTeacherArchives(TeacherArchiveExportDTO request, HttpServletResponse response) {
teacherArchiveExportService.exportBatch(request, response);
}
public static MultipartFile convertToMultipartFile(byte[] content, String fileName) throws IOException {
DiskFileItemFactory factory = new DiskFileItemFactory();
FileItem fileItem = factory.createItem("file", "application/octet-stream", false, fileName);
......
package com.platform.business.service.impl;
import com.platform.business.mapper.UserMapper;
import com.platform.business.model.dto.TeacherArchiveExportDTO;
import com.platform.business.model.entity.SysPhoneRoleEntity;
import com.platform.business.model.entity.TeacherTeachRecordEntity;
import com.platform.business.model.entity.TeacherWorkRecordEntity;
import com.platform.business.model.entity.UserEntity;
import com.platform.business.model.vo.UserVO;
import com.platform.business.service.SysPhoneRoleService;
import com.platform.business.service.TeacherTeachRecordService;
import com.platform.business.service.TeacherWorkRecordService;
import com.platform.exception.BusinessException;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.mock.web.MockHttpServletResponse;
import org.springframework.test.util.ReflectionTestUtils;
import java.io.ByteArrayInputStream;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.zip.ZipEntry;
import java.util.zip.ZipInputStream;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.never;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;
/** 教师J2档案模板填充、角色边界、批量ZIP和数量限制测试。 */
class TeacherArchiveExportServiceTest {
private TeacherArchiveExportService service;
private UserMapper userMapper;
private SysPhoneRoleService phoneRoleService;
private TeacherWorkRecordService workRecordService;
private TeacherTeachRecordService teachRecordService;
@BeforeEach
void setUp() {
service = new TeacherArchiveExportService();
userMapper = mock(UserMapper.class);
phoneRoleService = mock(SysPhoneRoleService.class);
workRecordService = mock(TeacherWorkRecordService.class);
teachRecordService = mock(TeacherTeachRecordService.class);
ReflectionTestUtils.setField(service, "userMapper", userMapper);
ReflectionTestUtils.setField(service, "sysPhoneRoleService", phoneRoleService);
ReflectionTestUtils.setField(service, "teacherWorkRecordService", workRecordService);
ReflectionTestUtils.setField(service, "teacherTeachRecordService", teachRecordService);
when(workRecordService.list(any())).thenReturn(Collections.emptyList());
when(teachRecordService.list(any())).thenReturn(Collections.emptyList());
}
@Test
void documentShouldFillBasicInformationAndExperiencesInOriginalTemplate() {
UserVO teacher = profile("1", "张三", "310101199001011234");
teacher.setSex("男");
teacher.setBirthday("1990年1月");
teacher.setMajor("环境工程");
teacher.setHighestEducation("本科");
teacher.setJobQualification("工程师");
teacher.setCertNo("T-001");
teacher.setIssueDept1("教育部门");
teacher.setLevel("高级工");
teacher.setIssueDept2("人社部门");
teacher.setWorkUnit("上海水务职业技术培训学校");
teacher.setWorkUnitAddress("上海市测试路1号");
teacher.setHomeAddress("上海市示例路2号");
teacher.setZipCode("200000");
teacher.setPhoneNumber("13800138000");
TeacherWorkRecordEntity work = new TeacherWorkRecordEntity();
work.setStartDate("2018年1月-2020年12月");
work.setWorkUnit("示例单位");
work.setDuty("技术员");
teacher.setTeacherWorkRecordList(Collections.singletonList(work));
TeacherTeachRecordEntity teach = new TeacherTeachRecordEntity();
teach.setSerialNumber("1");
teach.setTeachDate("2021年1月-至今");
teach.setTeachClassNum("3");
teach.setTeachCourse("污水处理");
teach.setTeachHour("120");
teach.setRemark("无");
teacher.setTeacherTeachRecordList(Collections.singletonList(teach));
byte[] bytes = service.createDocument(teacher);
assertTrue(bytes.length > 0);
// 原模板带有HWPF无法二次解析的OfficeArt记录,原文件空写后重开也会触发该限制。
// 服务已在document.write前逐项核验内存表格;测试再确认输出仍是标准OLE复合文档文件头。
assertEquals((byte) 0xD0, bytes[0]);
assertEquals((byte) 0xCF, bytes[1]);
assertEquals((byte) 0x11, bytes[2]);
assertEquals((byte) 0xE0, bytes[3]);
}
@Test
void singleExportShouldReturnDocWithUtf8Filename() {
prepareTeacher("1", "张三", "310101199001011234");
MockHttpServletResponse response = new MockHttpServletResponse();
service.exportOne("1", response);
assertEquals("application/msword", response.getContentType());
assertTrue(response.getHeader("Content-Disposition").contains("UTF-8''"));
assertTrue(response.getHeader("Content-Disposition").endsWith(".doc"));
assertTrue(response.getContentAsByteArray().length > 0);
}
@Test
void batchExportShouldDeduplicateIdsAndKeepSameNameEntriesUnique() throws Exception {
prepareTeacher("1", "张三", "310101199001011234");
prepareTeacher("2", "张三", "320101198501011234");
TeacherArchiveExportDTO request = new TeacherArchiveExportDTO();
request.setTeacherIds(Arrays.asList("1", "1", "2"));
MockHttpServletResponse response = new MockHttpServletResponse();
service.exportBatch(request, response);
assertEquals("application/zip", response.getContentType());
List<String> names = new ArrayList<>();
try (ZipInputStream zip = new ZipInputStream(
new ByteArrayInputStream(response.getContentAsByteArray()),
java.nio.charset.StandardCharsets.UTF_8)) {
ZipEntry entry;
while ((entry = zip.getNextEntry()) != null) {
names.add(entry.getName());
}
}
assertEquals(2, names.size());
assertTrue(names.get(0).endsWith(".doc"));
assertTrue(names.get(1).contains("_2.doc"));
}
@Test
void nonTeacherShouldBeRejectedBeforeRecordsAreQueried() {
UserEntity user = entity("1", "普通用户", "310101199001011234");
when(userMapper.selectById("1")).thenReturn(user);
when(phoneRoleService.queryByPhone(user.getPhoneNumber()))
.thenReturn(Collections.singletonList(role("学生")));
assertThrows(BusinessException.class,
() -> service.exportOne("1", new MockHttpServletResponse()));
verify(workRecordService, never()).list(any());
verify(teachRecordService, never()).list(any());
}
@Test
void moreThanFiveHundredTeachersShouldBeRejectedBeforeDatabaseQuery() {
TeacherArchiveExportDTO request = new TeacherArchiveExportDTO();
List<String> ids = new ArrayList<>();
for (int i = 0; i < 501; i++) {
ids.add(String.valueOf(i));
}
request.setTeacherIds(ids);
assertThrows(BusinessException.class,
() -> service.exportBatch(request, new MockHttpServletResponse()));
verify(userMapper, never()).selectById(any());
}
private void prepareTeacher(String id, String name, String idCard) {
UserEntity user = entity(id, name, idCard);
when(userMapper.selectById(id)).thenReturn(user);
when(phoneRoleService.queryByPhone(user.getPhoneNumber()))
.thenReturn(Collections.singletonList(role("教师")));
}
private UserEntity entity(String id, String name, String idCard) {
UserEntity user = new UserEntity();
user.setId(id);
user.setNickName(name);
user.setIdCard(idCard);
user.setPhoneNumber("1380013800" + id);
user.setIdType("教师");
return user;
}
private UserVO profile(String id, String name, String idCard) {
UserVO teacher = new UserVO();
teacher.setId(id);
teacher.setNickName(name);
teacher.setIdCard(idCard);
return teacher;
}
private SysPhoneRoleEntity role(String roleName) {
SysPhoneRoleEntity role = new SysPhoneRoleEntity();
role.setRoleName(roleName);
return role;
}
}
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment