Skip to content
GitLab
Menu
Projects
Groups
Snippets
Loading...
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in
Toggle navigation
Menu
Open sidebar
邬吉朋
practical_train
Commits
a98260c1
Commit
a98260c1
authored
Oct 28, 2026
by
wujipeng
Browse files
教师导出
parent
5763962b
Changes
8
Hide whitespace changes
Inline
Side-by-side
docs/教师业务档案导出接口文档.md
0 → 100644
View file @
a98260c1
# 教师业务档案导出接口文档
## 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
```
如果网关已经统一配置响应头暴露,则不需要针对本接口重复配置。
practical-api/practical-business-api/src/main/java/com/platform/business/model/dto/TeacherArchiveExportDTO.java
0 → 100644
View file @
a98260c1
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
;
}
practical-business/src/main/java/com/platform/business/controller/UserController.java
View file @
a98260c1
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
)
{
...
...
practical-business/src/main/java/com/platform/business/service/UserService.java
View file @
a98260c1
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
);
...
...
practical-business/src/main/java/com/platform/business/service/impl/TeacherArchiveExportService.java
0 → 100644
View file @
a98260c1
package
com.platform.business.service.impl
;
import
com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper
;
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
com.platform.utils.DozerUtils
;
import
org.apache.poi.hwpf.HWPFDocument
;
import
org.apache.poi.hwpf.usermodel.Range
;
import
org.apache.poi.hwpf.usermodel.Table
;
import
org.apache.poi.hwpf.usermodel.TableCell
;
import
org.apache.poi.hwpf.usermodel.TableIterator
;
import
org.apache.poi.hwpf.usermodel.TableRow
;
import
org.springframework.core.io.ClassPathResource
;
import
org.springframework.stereotype.Service
;
import
org.springframework.util.StringUtils
;
import
javax.annotation.Resource
;
import
javax.servlet.http.HttpServletResponse
;
import
java.io.ByteArrayOutputStream
;
import
java.io.InputStream
;
import
java.net.URLEncoder
;
import
java.nio.charset.StandardCharsets
;
import
java.text.SimpleDateFormat
;
import
java.util.ArrayList
;
import
java.util.Date
;
import
java.util.HashSet
;
import
java.util.LinkedHashSet
;
import
java.util.List
;
import
java.util.Set
;
import
java.util.zip.ZipEntry
;
import
java.util.zip.ZipOutputStream
;
/**
* 教师J2业务档案导出服务。
*
* <p>J2模板是Word 97-2003二进制文档,必须使用HWPF在模板副本上填值。
* 每次生成都会重新读取classpath模板,既保留原表格、合并单元格和打印版式,
* 也避免并发请求共享同一个可变的HWPFDocument。</p>
*/
@Service
public
class
TeacherArchiveExportService
{
private
static
final
String
TEMPLATE
=
"templates/teacher/J2-teacher-business-archive.doc"
;
private
static
final
int
MAX_EXPORT_COUNT
=
500
;
private
static
final
String
WORD_CONTENT_TYPE
=
"application/msword"
;
@Resource
private
UserMapper
userMapper
;
@Resource
private
SysPhoneRoleService
sysPhoneRoleService
;
@Resource
private
TeacherWorkRecordService
teacherWorkRecordService
;
@Resource
private
TeacherTeachRecordService
teacherTeachRecordService
;
/** 导出单个教师时直接返回DOC,不额外套ZIP。 */
public
void
exportOne
(
String
teacherId
,
HttpServletResponse
response
)
{
UserVO
teacher
=
loadTeacher
(
teacherId
);
byte
[]
document
=
createDocument
(
teacher
);
writeResponse
(
response
,
WORD_CONTENT_TYPE
,
safeFilePart
(
teacher
.
getNickName
(),
"未知教师"
)
+
"_J2教师业务档案.doc"
,
document
);
}
/**
* 批量导出会先在内存中生成完整ZIP,再写入HTTP响应。
* 这样任意一名教师资料或模板生成失败时都不会向客户端发送半个压缩包。
*/
public
void
exportBatch
(
TeacherArchiveExportDTO
request
,
HttpServletResponse
response
)
{
List
<
String
>
teacherIds
=
normalizeTeacherIds
(
request
);
try
(
ByteArrayOutputStream
output
=
new
ByteArrayOutputStream
();
ZipOutputStream
zip
=
new
ZipOutputStream
(
output
,
StandardCharsets
.
UTF_8
))
{
Set
<
String
>
usedNames
=
new
HashSet
<>();
for
(
String
teacherId
:
teacherIds
)
{
UserVO
teacher
=
loadTeacher
(
teacherId
);
String
entryName
=
uniqueEntryName
(
teacher
,
usedNames
);
zip
.
putNextEntry
(
new
ZipEntry
(
entryName
));
zip
.
write
(
createDocument
(
teacher
));
zip
.
closeEntry
();
}
zip
.
finish
();
String
fileName
=
"J2教师业务档案_"
+
new
SimpleDateFormat
(
"yyyyMMddHHmmss"
).
format
(
new
Date
())
+
".zip"
;
writeResponse
(
response
,
"application/zip"
,
fileName
,
output
.
toByteArray
());
}
catch
(
BusinessException
e
)
{
throw
e
;
}
catch
(
Exception
e
)
{
throw
new
BusinessException
(
"批量导出教师业务档案失败"
);
}
}
/**
* 读取教师及两类经历,并在导出边界再次校验“教师”业务角色。
* 不能只相信前端列表来源,否则手工构造ID可能导出学员或管理员资料。
*/
private
UserVO
loadTeacher
(
String
teacherId
)
{
String
normalizedId
=
trimToNull
(
teacherId
);
if
(
normalizedId
==
null
)
{
throw
new
BusinessException
(
"教师ID不能为空"
);
}
UserEntity
entity
=
userMapper
.
selectById
(
normalizedId
);
if
(
entity
==
null
||
Boolean
.
TRUE
.
equals
(
entity
.
getDelFlag
()))
{
throw
new
BusinessException
(
"教师不存在或已删除"
);
}
List
<
SysPhoneRoleEntity
>
roles
=
sysPhoneRoleService
.
queryByPhone
(
entity
.
getPhoneNumber
());
boolean
teacherRole
=
roles
!=
null
&&
roles
.
stream
()
.
anyMatch
(
role
->
role
!=
null
&&
"教师"
.
equals
(
role
.
getRoleName
()));
if
(!
teacherRole
)
{
throw
new
BusinessException
(
"所选用户不是教师,无法导出教师业务档案"
);
}
UserVO
teacher
=
DozerUtils
.
convertBean
(
entity
,
UserVO
.
class
);
teacher
.
setTeacherWorkRecordList
(
teacherWorkRecordService
.
list
(
new
LambdaQueryWrapper
<
TeacherWorkRecordEntity
>()
.
eq
(
TeacherWorkRecordEntity:
:
getUserId
,
normalizedId
)
.
orderByAsc
(
TeacherWorkRecordEntity:
:
getId
)));
teacher
.
setTeacherTeachRecordList
(
teacherTeachRecordService
.
list
(
new
LambdaQueryWrapper
<
TeacherTeachRecordEntity
>()
.
eq
(
TeacherTeachRecordEntity:
:
getUserId
,
normalizedId
)
.
orderByAsc
(
TeacherTeachRecordEntity:
:
getSerialNumber
)
.
orderByAsc
(
TeacherTeachRecordEntity:
:
getId
)));
return
teacher
;
}
/**
* 根据导入功能已经确认过的J2行列坐标反向填充模板。
*
* <p>HWPF的Range在较早位置插入文本后不会可靠地重算所有旧Range引用,
* 因此必须先填较后的经历行,再按第7行到第0行、单行内从右到左写基本信息,
* 最后才处理位于表格之前的封面。这个顺序不可改为自然的从上到下写入。</p>
*/
byte
[]
createDocument
(
UserVO
teacher
)
{
try
(
InputStream
input
=
new
ClassPathResource
(
TEMPLATE
).
getInputStream
();
HWPFDocument
document
=
new
HWPFDocument
(
input
);
ByteArrayOutputStream
output
=
new
ByteArrayOutputStream
())
{
Table
table
=
firstTable
(
document
);
validateTemplate
(
table
);
List
<
Integer
>
workRows
=
new
ArrayList
<>();
List
<
Integer
>
teachRows
=
new
ArrayList
<>();
locateExperienceRows
(
table
,
workRows
,
teachRows
);
List
<
TeacherWorkRecordEntity
>
workRecords
=
nullToEmpty
(
teacher
.
getTeacherWorkRecordList
());
List
<
TeacherTeachRecordEntity
>
teachRecords
=
nullToEmpty
(
teacher
.
getTeacherTeachRecordList
());
validateRecordCapacity
(
workRecords
.
size
(),
teachRecords
.
size
(),
workRows
.
size
(),
teachRows
.
size
());
// 经历位于表格后半部分,必须优先按“最后一条到第一条”写入。
for
(
int
i
=
teachRecords
.
size
()
-
1
;
i
>=
0
;
i
--)
{
writeTeachRecord
(
table
.
getRow
(
teachRows
.
get
(
i
)),
teachRecords
.
get
(
i
));
}
for
(
int
i
=
workRecords
.
size
()
-
1
;
i
>=
0
;
i
--)
{
writeWorkRecord
(
table
.
getRow
(
workRows
.
get
(
i
)),
workRecords
.
get
(
i
));
}
// 基本信息同样从后向前写;身份证的18个单字符格也必须从第18格倒序处理。
put
(
table
,
7
,
5
,
teacher
.
getPhoneNumber
());
put
(
table
,
7
,
3
,
teacher
.
getZipCode
());
put
(
table
,
7
,
1
,
teacher
.
getHomeAddress
());
put
(
table
,
6
,
3
,
teacher
.
getWorkUnitAddress
());
put
(
table
,
6
,
1
,
teacher
.
getWorkUnit
());
put
(
table
,
5
,
3
,
teacher
.
getIssueDept2
());
put
(
table
,
5
,
1
,
teacher
.
getLevel
());
put
(
table
,
4
,
3
,
teacher
.
getIssueDept1
());
put
(
table
,
4
,
1
,
teacher
.
getCertNo
());
put
(
table
,
3
,
1
,
teacher
.
getJobQualification
());
put
(
table
,
2
,
3
,
teacher
.
getHighestEducation
());
put
(
table
,
2
,
1
,
teacher
.
getMajor
());
writeIdCard
(
table
,
teacher
.
getIdCard
());
put
(
table
,
0
,
5
,
teacher
.
getBirthday
());
put
(
table
,
0
,
3
,
teacher
.
getSex
());
put
(
table
,
0
,
1
,
teacher
.
getNickName
());
// 原模板含HWPF无法稳定二次解析的OfficeArt记录,因此在写出前直接核验内存模型。
// 这与项目内B2旧版Word模板的处理方式一致,可在不重开文件的情况下发现错位或漏填。
verifyTableContent
(
document
,
table
,
teacher
,
workRecords
,
teachRecords
);
// 封面位于所有表格之前,必须最后填充,以免前方插入导致表格Range整体偏移。
fillCover
(
document
,
teacher
.
getNickName
());
String
filledText
=
document
.
getText
().
toString
();
if
(
StringUtils
.
hasText
(
teacher
.
getNickName
())
&&
!
filledText
.
contains
(
teacher
.
getNickName
()))
{
throw
new
BusinessException
(
"J2模板字段填充校验失败"
);
}
document
.
write
(
output
);
return
output
.
toByteArray
();
}
catch
(
BusinessException
e
)
{
throw
e
;
}
catch
(
Exception
e
)
{
throw
new
BusinessException
(
"生成教师J2业务档案失败"
);
}
}
private
void
verifyTableContent
(
HWPFDocument
document
,
Table
table
,
UserVO
teacher
,
List
<
TeacherWorkRecordEntity
>
workRecords
,
List
<
TeacherTeachRecordEntity
>
teachRecords
)
{
String
text
=
document
.
getText
().
toString
();
requireText
(
text
,
teacher
.
getNickName
(),
"姓名"
);
requireText
(
text
,
teacher
.
getMajor
(),
"所学专业"
);
requireText
(
text
,
teacher
.
getCertNo
(),
"教师资格证编号"
);
for
(
TeacherWorkRecordEntity
record
:
workRecords
)
{
requireText
(
text
,
record
.
getWorkUnit
(),
"从业经历单位"
);
requireText
(
text
,
record
.
getDuty
(),
"从业经历职务"
);
}
for
(
TeacherTeachRecordEntity
record
:
teachRecords
)
{
requireText
(
text
,
record
.
getTeachCourse
(),
"任教课程"
);
requireText
(
text
,
record
.
getTeachDate
(),
"任教起迄日期"
);
}
String
idCard
=
trimToNull
(
teacher
.
getIdCard
());
if
(
idCard
!=
null
)
{
for
(
int
index
=
0
;
index
<
idCard
.
length
();
index
++)
{
String
cellText
=
cleanCellText
(
table
.
getRow
(
1
).
getCell
(
index
+
1
));
if
(!
cellText
.
contains
(
String
.
valueOf
(
idCard
.
charAt
(
index
))))
{
throw
new
BusinessException
(
"J2模板身份证号第"
+
(
index
+
1
)
+
"位填充校验失败"
);
}
}
}
}
private
void
requireText
(
String
documentText
,
String
expected
,
String
fieldName
)
{
String
normalized
=
trimToNull
(
expected
);
if
(
normalized
!=
null
&&
!
documentText
.
contains
(
normalized
))
{
throw
new
BusinessException
(
"J2模板"
+
fieldName
+
"填充校验失败"
);
}
}
private
Table
firstTable
(
HWPFDocument
document
)
{
TableIterator
iterator
=
new
TableIterator
(
document
.
getRange
());
if
(!
iterator
.
hasNext
())
{
throw
new
BusinessException
(
"J2模板中未找到教师基本情况表"
);
}
return
iterator
.
next
();
}
/** 模板升级时立即报错,避免行列改变后把敏感字段写入错误位置。 */
private
void
validateTemplate
(
Table
table
)
{
if
(
table
.
numRows
()
<
11
||
table
.
getRow
(
0
).
numCells
()
<
6
||
table
.
getRow
(
1
).
numCells
()
<
19
||
table
.
getRow
(
7
).
numCells
()
<
6
)
{
throw
new
BusinessException
(
"J2模板结构已变化,请重新确认字段映射"
);
}
}
/**
* 经历区不硬编码结束行:以“任教经历”和“序号”标题切换分区,
* 同时用列数排除说明文字行,从而兼容模板中预留行数的小幅调整。
*/
private
void
locateExperienceRows
(
Table
table
,
List
<
Integer
>
workRows
,
List
<
Integer
>
teachRows
)
{
boolean
teachingSection
=
false
;
for
(
int
rowIndex
=
10
;
rowIndex
<
table
.
numRows
();
rowIndex
++)
{
TableRow
row
=
table
.
getRow
(
rowIndex
);
String
firstCell
=
row
.
numCells
()
==
0
?
""
:
cleanCellText
(
row
.
getCell
(
0
));
if
(
"任教经历"
.
equals
(
firstCell
)
||
"序号"
.
equals
(
firstCell
))
{
teachingSection
=
true
;
continue
;
}
if
(!
teachingSection
&&
row
.
numCells
()
>=
3
)
{
workRows
.
add
(
rowIndex
);
}
else
if
(
teachingSection
&&
row
.
numCells
()
>=
6
)
{
teachRows
.
add
(
rowIndex
);
}
}
if
(
workRows
.
isEmpty
()
||
teachRows
.
isEmpty
())
{
throw
new
BusinessException
(
"J2模板经历区域结构已变化,请重新确认字段映射"
);
}
}
private
void
validateRecordCapacity
(
int
workCount
,
int
teachCount
,
int
workCapacity
,
int
teachCapacity
)
{
if
(
workCount
>
workCapacity
)
{
throw
new
BusinessException
(
"从业经历超过J2模板预留的"
+
workCapacity
+
"行"
);
}
if
(
teachCount
>
teachCapacity
)
{
throw
new
BusinessException
(
"任教经历超过J2模板预留的"
+
teachCapacity
+
"行"
);
}
}
/** 单行仍按最右列到最左列写入,保证同一行中的旧Range引用不被前方插入破坏。 */
private
void
writeWorkRecord
(
TableRow
row
,
TeacherWorkRecordEntity
record
)
{
put
(
row
,
2
,
record
.
getDuty
());
put
(
row
,
1
,
record
.
getWorkUnit
());
put
(
row
,
0
,
record
.
getStartDate
());
}
/** 任教经历共有六列,写入顺序同样必须从备注列倒推到序号列。 */
private
void
writeTeachRecord
(
TableRow
row
,
TeacherTeachRecordEntity
record
)
{
put
(
row
,
5
,
record
.
getRemark
());
put
(
row
,
4
,
record
.
getTeachHour
());
put
(
row
,
3
,
record
.
getTeachCourse
());
put
(
row
,
2
,
record
.
getTeachClassNum
());
put
(
row
,
1
,
record
.
getTeachDate
());
put
(
row
,
0
,
record
.
getSerialNumber
());
}
private
void
writeIdCard
(
Table
table
,
String
idCard
)
{
String
value
=
trimToNull
(
idCard
);
if
(
value
==
null
)
{
return
;
}
if
(
value
.
length
()
>
18
)
{
throw
new
BusinessException
(
"教师身份证号超过J2模板的18位容量"
);
}
for
(
int
index
=
value
.
length
()
-
1
;
index
>=
0
;
index
--)
{
put
(
table
,
1
,
index
+
1
,
String
.
valueOf
(
value
.
charAt
(
index
)));
}
}
/**
* 封面没有结构化占位符,因此只在“教师基本情况表”之前的区域定位标签。
* 日期替换先于姓名插入执行,继续遵守从后向前修改的规则;聘用类型按需求保留空白。
*/
private
void
fillCover
(
HWPFDocument
document
,
String
teacherName
)
{
Range
documentRange
=
document
.
getRange
();
String
text
=
documentRange
.
text
();
int
coverEnd
=
text
.
indexOf
(
"教师基本情况表"
);
int
hireLabel
=
text
.
indexOf
(
"聘用类型"
);
if
(
coverEnd
<
0
||
hireLabel
<
0
||
hireLabel
>=
coverEnd
)
{
throw
new
BusinessException
(
"J2模板封面结构已变化,请重新确认字段映射"
);
}
int
year
=
text
.
indexOf
(
"年"
,
hireLabel
);
int
day
=
year
<
0
?
-
1
:
text
.
indexOf
(
"日"
,
year
);
if
(
year
>=
0
&&
day
>=
year
&&
day
<
coverEnd
)
{
Range
dateRange
=
new
Range
(
year
,
day
+
1
,
document
);
dateRange
.
replaceText
(
dateRange
.
text
(),
new
SimpleDateFormat
(
"yyyy年MM月dd日"
).
format
(
new
Date
()));
}
String
normalizedName
=
trimToNull
(
teacherName
);
if
(
normalizedName
!=
null
)
{
String
refreshedText
=
document
.
getRange
().
text
();
int
refreshedCoverEnd
=
refreshedText
.
indexOf
(
"教师基本情况表"
);
int
nameLabel
=
refreshedText
.
indexOf
(
"教师姓名"
);
if
(
nameLabel
<
0
||
nameLabel
>=
refreshedCoverEnd
)
{
throw
new
BusinessException
(
"J2模板封面教师姓名标签已变化,请重新确认字段映射"
);
}
// 不能用replaceText把“教师姓名”替换成包含原词的长文本,否则HWPF会再次命中
// 新插入的“教师姓名”并持续替换。改为在标签末尾的零长度Range中一次性插入值。
int
insertPosition
=
nameLabel
+
"教师姓名"
.
length
();
new
Range
(
insertPosition
,
insertPosition
,
document
).
insertAfter
(
":"
+
normalizedName
);
}
}
private
void
put
(
Table
table
,
int
row
,
int
cell
,
Object
value
)
{
put
(
table
.
getRow
(
row
),
cell
,
value
);
}
private
void
put
(
TableRow
row
,
int
cell
,
Object
value
)
{
String
text
=
value
==
null
?
""
:
String
.
valueOf
(
value
).
trim
();
if
(
text
.
isEmpty
())
{
return
;
}
TableCell
target
=
row
.
getCell
(
cell
);
target
.
insertBefore
(
text
);
}
private
String
cleanCellText
(
TableCell
cell
)
{
return
cell
.
text
().
replace
(
"\r"
,
""
).
replace
(
"\u0007"
,
""
).
trim
();
}
private
List
<
String
>
normalizeTeacherIds
(
TeacherArchiveExportDTO
request
)
{
if
(
request
==
null
||
request
.
getTeacherIds
()
==
null
)
{
throw
new
BusinessException
(
"请选择需要导出的教师"
);
}
LinkedHashSet
<
String
>
unique
=
new
LinkedHashSet
<>();
for
(
String
teacherId
:
request
.
getTeacherIds
())
{
String
normalized
=
trimToNull
(
teacherId
);
if
(
normalized
!=
null
)
{
unique
.
add
(
normalized
);
}
}
if
(
unique
.
isEmpty
())
{
throw
new
BusinessException
(
"请选择需要导出的教师"
);
}
if
(
unique
.
size
()
>
MAX_EXPORT_COUNT
)
{
throw
new
BusinessException
(
"单次最多导出500名教师"
);
}
return
new
ArrayList
<>(
unique
);
}
/**
* ZIP内先用“姓名+身份证后四位”区分同名教师;仍重名时追加教师ID。
* 最后的数字兜底用于防御异常重复数据,确保每名教师都保留独立条目。
*/
private
String
uniqueEntryName
(
UserVO
teacher
,
Set
<
String
>
usedNames
)
{
String
name
=
safeFilePart
(
teacher
.
getNickName
(),
"未知教师"
);
String
idCard
=
trimToNull
(
teacher
.
getIdCard
());
String
suffix
=
idCard
==
null
?
"无身份证"
:
idCard
.
substring
(
Math
.
max
(
0
,
idCard
.
length
()
-
4
));
String
base
=
name
+
"_"
+
safeFilePart
(
suffix
,
"无身份证"
)
+
"_J2教师业务档案"
;
String
candidate
=
base
+
".doc"
;
if
(
usedNames
.
add
(
candidate
))
{
return
candidate
;
}
candidate
=
base
+
"_"
+
safeFilePart
(
teacher
.
getId
(),
"未知ID"
)
+
".doc"
;
int
sequence
=
2
;
while
(!
usedNames
.
add
(
candidate
))
{
candidate
=
base
+
"_"
+
safeFilePart
(
teacher
.
getId
(),
"未知ID"
)
+
"_"
+
sequence
++
+
".doc"
;
}
return
candidate
;
}
private
String
safeFilePart
(
String
value
,
String
fallback
)
{
String
result
=
trimToNull
(
value
);
result
=
result
==
null
?
fallback
:
result
;
result
=
result
.
replaceAll
(
"[\\\\/:*?\"<>|]"
,
"_"
);
return
result
.
length
()
>
60
?
result
.
substring
(
0
,
60
)
:
result
;
}
private
String
trimToNull
(
String
value
)
{
return
value
==
null
||
value
.
trim
().
isEmpty
()
?
null
:
value
.
trim
();
}
private
<
T
>
List
<
T
>
nullToEmpty
(
List
<
T
>
values
)
{
return
values
==
null
?
new
ArrayList
<>()
:
values
;
}
private
void
writeResponse
(
HttpServletResponse
response
,
String
contentType
,
String
fileName
,
byte
[]
bytes
)
{
try
{
String
encoded
=
URLEncoder
.
encode
(
fileName
,
StandardCharsets
.
UTF_8
.
name
())
.
replace
(
"+"
,
"%20"
);
response
.
reset
();
response
.
setContentType
(
contentType
);
response
.
setCharacterEncoding
(
StandardCharsets
.
UTF_8
.
name
());
response
.
setHeader
(
"Content-Disposition"
,
"attachment; filename*=UTF-8''"
+
encoded
);
response
.
setContentLength
(
bytes
.
length
);
response
.
getOutputStream
().
write
(
bytes
);
response
.
flushBuffer
();
}
catch
(
Exception
e
)
{
throw
new
BusinessException
(
"写出教师业务档案失败"
);
}
}
}
practical-business/src/main/java/com/platform/business/service/impl/UserServiceImpl.java
View file @
a98260c1
...
...
@@ -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
);
...
...
practical-business/src/main/resources/templates/teacher/J2-teacher-business-archive.doc
0 → 100644
View file @
a98260c1
File added
practical-business/src/test/java/com/platform/business/service/impl/TeacherArchiveExportServiceTest.java
0 → 100644
View file @
a98260c1
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
;
}
}
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment