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
6525db95
Commit
6525db95
authored
Aug 17, 2026
by
wujipeng
Browse files
管理员-教务管理-教案管理
parent
e34240ea
Changes
16
Hide whitespace changes
Inline
Side-by-side
practical-api/practical-business-api/src/main/java/com/platform/business/model/dto/TeachingPlanAdminQueryDTO.java
0 → 100644
View file @
6525db95
package
com.platform.business.model.dto
;
import
io.swagger.annotations.ApiModelProperty
;
import
lombok.Data
;
import
lombok.EqualsAndHashCode
;
/**
* 管理员端教案分页及导出查询条件。
*
* <p>复用教师端的关键字、状态和授课日期范围字段,并增加教师筛选。管理员身份
* 始终由服务端登录态校验,查询对象不包含任何权限相关字段。</p>
*/
@Data
@EqualsAndHashCode
(
callSuper
=
true
)
public
class
TeachingPlanAdminQueryDTO
extends
TeachingPlanQueryDTO
{
@ApiModelProperty
(
"所属教师用户ID;为空时查询全部教师"
)
private
String
teacherId
;
}
practical-api/practical-business-api/src/main/java/com/platform/business/model/dto/TeachingPlanAdminUpdateDTO.java
0 → 100644
View file @
6525db95
package
com.platform.business.model.dto
;
import
io.swagger.annotations.ApiModelProperty
;
import
lombok.Data
;
import
lombok.EqualsAndHashCode
;
/**
* 管理员编辑及审核教案请求。
*
* <p>正文结构与教师端保持一致;审核人、审核时间由服务端根据当前登录管理员写入,
* 因此本对象故意不暴露 reviewerId、reviewerName 和 reviewTime。</p>
*/
@Data
@EqualsAndHashCode
(
callSuper
=
true
)
public
class
TeachingPlanAdminUpdateDTO
extends
TeachingPlanSaveDTO
{
@ApiModelProperty
(
value
=
"目标状态:DRAFT/PENDING/APPROVED/REJECTED"
,
required
=
true
)
private
String
status
;
@ApiModelProperty
(
"审核意见,可为空,最多2000个字符"
)
private
String
reviewOpinion
;
}
practical-api/practical-business-api/src/main/java/com/platform/business/model/entity/TeachingPlanEntity.java
View file @
6525db95
...
...
@@ -76,6 +76,23 @@ public class TeachingPlanEntity {
/** 审核展示状态:DRAFT、PENDING、APPROVED、REJECTED。 */
private
String
status
;
/** 最近一次执行管理端保存操作的管理员用户 ID。 */
@TableField
(
"reviewer_id"
)
private
String
reviewerId
;
/** 最近一次审核人的姓名快照,避免用户改名后历史展示发生变化。 */
@TableField
(
"reviewer_name"
)
private
String
reviewerName
;
/** 管理员最近一次保存的审核意见,允许为空。 */
@TableField
(
"review_opinion"
)
private
String
reviewOpinion
;
/** 最近一次管理端保存或审核时间。 */
@JsonFormat
(
pattern
=
"yyyy-MM-dd HH:mm:ss"
,
timezone
=
"GMT+8"
)
@TableField
(
"review_time"
)
private
Date
reviewTime
;
/** 逻辑删除标记:0 正常,1 删除。 */
@TableLogic
(
value
=
"0"
,
delval
=
"1"
)
@TableField
(
"del_flag"
)
...
...
practical-api/practical-business-api/src/main/java/com/platform/business/model/vo/TeachingPlanTeacherOptionVO.java
0 → 100644
View file @
6525db95
package
com.platform.business.model.vo
;
import
lombok.Data
;
/** 管理员端教案列表的教师筛选选项,仅返回存在有效教案的教师。 */
@Data
public
class
TeachingPlanTeacherOptionVO
{
/** 教师用户ID,作为分页查询的 teacherId 入参。 */
private
String
teacherId
;
/** 教师当前显示姓名。 */
private
String
teacherName
;
}
practical-api/practical-business-api/src/main/java/com/platform/business/model/vo/TeachingPlanVO.java
View file @
6525db95
...
...
@@ -28,6 +28,19 @@ public class TeachingPlanVO {
private
String
afterClassSummary
;
private
String
status
;
/** 最近一次执行管理端保存操作的管理员用户ID。 */
private
String
reviewerId
;
/** 最近一次审核人姓名快照,不随用户后续改名而改变。 */
private
String
reviewerName
;
/** 最近一次管理员保存的审核意见。 */
private
String
reviewOpinion
;
/** 最近一次管理端保存或审核时间。 */
@JsonFormat
(
pattern
=
"yyyy-MM-dd HH:mm:ss"
,
timezone
=
"GMT+8"
)
private
Date
reviewTime
;
@JsonFormat
(
pattern
=
"yyyy-MM-dd HH:mm:ss"
,
timezone
=
"GMT+8"
)
private
Date
createTime
;
...
...
practical-business/src/main/java/com/platform/business/constant/TeachingPlanConstants.java
View file @
6525db95
...
...
@@ -20,6 +20,12 @@ public final class TeachingPlanConstants {
/** 单个结构化正文的安全上限,防止异常请求占用过多数据库空间。 */
public
static
final
int
MAX_CONTENT_LENGTH
=
20000
;
/** 审核意见对应数据库 VARCHAR(2000)。 */
public
static
final
int
MAX_REVIEW_OPINION_LENGTH
=
2000
;
/** 审核人姓名快照对应数据库 VARCHAR(100)。 */
public
static
final
int
MAX_REVIEWER_NAME_LENGTH
=
100
;
public
static
final
int
MAX_ATTACHMENT_COUNT
=
10
;
public
static
final
long
MAX_ATTACHMENT_SIZE
=
50L
*
1024
*
1024
;
...
...
practical-business/src/main/java/com/platform/business/controller/TeachingPlanAdminController.java
0 → 100644
View file @
6525db95
package
com.platform.business.controller
;
import
com.platform.business.model.dto.TeachingPlanAdminQueryDTO
;
import
com.platform.business.model.dto.TeachingPlanAdminUpdateDTO
;
import
com.platform.business.model.entity.UserEntity
;
import
com.platform.business.model.vo.TeachingPlanTeacherOptionVO
;
import
com.platform.business.model.vo.TeachingPlanVO
;
import
com.platform.business.service.AuthenticatedUserService
;
import
com.platform.business.service.TeachingPlanService
;
import
com.platform.controller.BaseController
;
import
com.platform.model.resp.Result
;
import
com.platform.page.TableDataInfo
;
import
io.swagger.annotations.Api
;
import
io.swagger.annotations.ApiOperation
;
import
org.springframework.util.StringUtils
;
import
org.springframework.web.bind.annotation.GetMapping
;
import
org.springframework.web.bind.annotation.PathVariable
;
import
org.springframework.web.bind.annotation.PostMapping
;
import
org.springframework.web.bind.annotation.PutMapping
;
import
org.springframework.web.bind.annotation.RequestBody
;
import
org.springframework.web.bind.annotation.RequestMapping
;
import
org.springframework.web.bind.annotation.RestController
;
import
javax.annotation.Resource
;
import
javax.servlet.http.HttpServletRequest
;
import
javax.servlet.http.HttpServletResponse
;
import
java.util.List
;
/**
* 管理员端“教务管理-教案管理”接口。
*
* <p>每个入口都会解析当前登录用户并校验“管理员”角色。管理员更新可以跨教师、跨
* 状态执行,但审核人信息始终取登录态,接口不会信任客户端提交的审核人身份。</p>
*/
@Api
(
tags
=
"管理员端-教案管理"
)
@RestController
@RequestMapping
(
"/teaching/plan/admin"
)
public
class
TeachingPlanAdminController
extends
BaseController
{
@Resource
private
TeachingPlanService
teachingPlanService
;
@Resource
private
AuthenticatedUserService
authenticatedUserService
;
@ApiOperation
(
"分页查询全部教师的教案"
)
@PostMapping
(
"/page"
)
public
TableDataInfo
page
(
@RequestBody
(
required
=
false
)
TeachingPlanAdminQueryDTO
query
,
HttpServletRequest
request
)
{
TeachingPlanAdminQueryDTO
safeQuery
=
query
==
null
?
new
TeachingPlanAdminQueryDTO
()
:
query
;
normalizePage
(
safeQuery
);
currentAdmin
(
request
);
startPage
(
safeQuery
.
getPageNum
(),
safeQuery
.
getPageSize
());
return
getDataTable
(
teachingPlanService
.
adminList
(
safeQuery
));
}
@ApiOperation
(
"查询任意有效教案详情"
)
@GetMapping
(
"/{id}"
)
public
Result
<
TeachingPlanVO
>
detail
(
@PathVariable
String
id
,
HttpServletRequest
request
)
{
currentAdmin
(
request
);
return
Result
.
data
(
teachingPlanService
.
adminDetail
(
id
));
}
@ApiOperation
(
"管理员编辑正文并设置任意教案状态"
)
@PutMapping
(
"/{id}"
)
public
Result
<
TeachingPlanVO
>
update
(
@PathVariable
String
id
,
@RequestBody
TeachingPlanAdminUpdateDTO
body
,
HttpServletRequest
request
)
{
UserEntity
admin
=
currentAdmin
(
request
);
return
Result
.
data
(
teachingPlanService
.
adminUpdate
(
id
,
body
,
admin
.
getId
(),
reviewerName
(
admin
)));
}
@ApiOperation
(
"查询存在有效教案的教师筛选选项"
)
@GetMapping
(
"/teachers"
)
public
Result
<
List
<
TeachingPlanTeacherOptionVO
>>
teacherOptions
(
HttpServletRequest
request
)
{
currentAdmin
(
request
);
return
Result
.
data
(
teachingPlanService
.
adminTeacherOptions
());
}
@ApiOperation
(
"按当前筛选条件导出全部教案清单Excel"
)
@PostMapping
(
"/export"
)
public
void
exportList
(
@RequestBody
(
required
=
false
)
TeachingPlanAdminQueryDTO
query
,
HttpServletRequest
request
,
HttpServletResponse
response
)
{
currentAdmin
(
request
);
teachingPlanService
.
exportAdminList
(
query
,
response
);
}
@ApiOperation
(
"导出单份教案Word"
)
@GetMapping
(
"/{id}/export"
)
public
void
exportDetail
(
@PathVariable
String
id
,
HttpServletRequest
request
,
HttpServletResponse
response
)
{
currentAdmin
(
request
);
teachingPlanService
.
exportAdminDetail
(
id
,
response
);
}
/** 统一分页默认值并限制单次最大查询量,避免页面参数导致超大分页。 */
void
normalizePage
(
TeachingPlanAdminQueryDTO
query
)
{
int
pageNum
=
query
.
getPageNum
()
==
null
||
query
.
getPageNum
()
<
1
?
1
:
query
.
getPageNum
();
int
pageSize
=
query
.
getPageSize
()
==
null
||
query
.
getPageSize
()
<
1
?
10
:
query
.
getPageSize
();
query
.
setPageNum
(
pageNum
);
query
.
setPageSize
(
Math
.
min
(
pageSize
,
100
));
}
/** 解析登录用户并校验管理员角色,所有管理端入口统一调用本方法。 */
private
UserEntity
currentAdmin
(
HttpServletRequest
request
)
{
UserEntity
admin
=
authenticatedUserService
.
current
(
request
);
authenticatedUserService
.
requireAdmin
(
admin
);
return
admin
;
}
/**
* 优先保存真实姓名;历史账号没有姓名时依次使用账号、手机号和用户ID,
* 确保审核记录始终有可展示的责任人快照。
*/
private
String
reviewerName
(
UserEntity
admin
)
{
if
(
StringUtils
.
hasText
(
admin
.
getNickName
()))
{
return
admin
.
getNickName
().
trim
();
}
if
(
StringUtils
.
hasText
(
admin
.
getUsername
()))
{
return
admin
.
getUsername
().
trim
();
}
if
(
StringUtils
.
hasText
(
admin
.
getPhoneNumber
()))
{
return
admin
.
getPhoneNumber
().
trim
();
}
return
admin
.
getId
();
}
}
practical-business/src/main/java/com/platform/business/mapper/TeachingPlanMapper.java
View file @
6525db95
package
com.platform.business.mapper
;
import
com.baomidou.mybatisplus.core.mapper.BaseMapper
;
import
com.platform.business.model.dto.TeachingPlanAdminQueryDTO
;
import
com.platform.business.model.dto.TeachingPlanQueryDTO
;
import
com.platform.business.model.entity.TeachingPlanEntity
;
import
com.platform.business.model.vo.TeachingPlanTeacherOptionVO
;
import
com.platform.business.model.vo.TeachingPlanVO
;
import
org.apache.ibatis.annotations.Mapper
;
import
org.apache.ibatis.annotations.Param
;
...
...
@@ -41,4 +43,24 @@ public interface TeachingPlanMapper extends BaseMapper<TeachingPlanEntity> {
/** 仅逻辑删除仍属于当前教师且仍为草稿的教案。 */
int
deleteDraft
(
@Param
(
"id"
)
String
id
,
@Param
(
"teacherId"
)
String
teacherId
);
/** 管理员查询全部教师的教案,分页由控制器中的 PageHelper 提供。 */
List
<
TeachingPlanVO
>
selectAdminList
(
@Param
(
"query"
)
TeachingPlanAdminQueryDTO
query
);
/** 管理员查询任意一条未删除教案,不施加教师归属限制。 */
TeachingPlanVO
selectAdminDetail
(
@Param
(
"id"
)
String
id
);
/**
* 管理员更新前锁定目标记录,确保正文、状态和审核元数据在同一事务中一致写入。
*/
TeachingPlanEntity
selectAdminPlanForUpdate
(
@Param
(
"id"
)
String
id
);
/**
* 管理员原子更新教案正文、任意目标状态和审核信息。
* WHERE 条件仍限制逻辑删除标记,防止并发删除后继续写入。
*/
int
updateAdmin
(
@Param
(
"plan"
)
TeachingPlanEntity
plan
);
/** 查询存在有效教案的教师,供管理端教师筛选下拉框使用。 */
List
<
TeachingPlanTeacherOptionVO
>
selectAdminTeacherOptions
();
}
practical-business/src/main/java/com/platform/business/service/TeachingPlanService.java
View file @
6525db95
package
com.platform.business.service
;
import
com.platform.business.model.dto.TeachingPlanAdminQueryDTO
;
import
com.platform.business.model.dto.TeachingPlanAdminUpdateDTO
;
import
com.platform.business.model.dto.TeachingPlanQueryDTO
;
import
com.platform.business.model.dto.TeachingPlanSaveDTO
;
import
com.platform.business.model.dto.TeachingPlanStatusDTO
;
import
com.platform.business.model.vo.TeachingPlanAttachmentVO
;
import
com.platform.business.model.vo.TeachingPlanTeacherOptionVO
;
import
com.platform.business.model.vo.TeachingPlanVO
;
import
org.springframework.web.multipart.MultipartFile
;
import
javax.servlet.http.HttpServletResponse
;
import
java.util.List
;
/** 教师端教案管理业务接口。所有方法都要求显式传入服务端解析出的当前教师 ID。 */
/**
* 教案管理业务接口。
*
* <p>教师端方法显式接收登录教师 ID 并限制数据归属;管理员端方法由控制器完成角色
* 校验,涉及审核的写操作还显式接收当前管理员 ID 和姓名。</p>
*/
public
interface
TeachingPlanService
{
List
<
TeachingPlanVO
>
list
(
TeachingPlanQueryDTO
query
,
String
teacherId
);
...
...
@@ -30,4 +39,23 @@ public interface TeachingPlanService {
boolean
deleteAttachment
(
String
id
,
String
attachmentId
,
String
teacherId
);
void
downloadAttachment
(
String
id
,
String
attachmentId
,
String
teacherId
);
/** 按管理员筛选条件查询全部教师的教案,分页由控制器负责启动。 */
List
<
TeachingPlanVO
>
adminList
(
TeachingPlanAdminQueryDTO
query
);
/** 查询任意未逻辑删除教案,并装配其有效附件。 */
TeachingPlanVO
adminDetail
(
String
id
);
/** 管理员原子保存正文、任意目标状态及可信审核人快照。 */
TeachingPlanVO
adminUpdate
(
String
id
,
TeachingPlanAdminUpdateDTO
request
,
String
reviewerId
,
String
reviewerName
);
/** 返回至少拥有一份有效教案的教师筛选选项。 */
List
<
TeachingPlanTeacherOptionVO
>
adminTeacherOptions
();
/** 按查询条件导出全部匹配教案,不应用分页参数。 */
void
exportAdminList
(
TeachingPlanAdminQueryDTO
query
,
HttpServletResponse
response
);
/** 将单份教案正文、审核信息和附件名称导出为Word。 */
void
exportAdminDetail
(
String
id
,
HttpServletResponse
response
);
}
practical-business/src/main/java/com/platform/business/service/impl/TeachingPlanServiceImpl.java
View file @
6525db95
...
...
@@ -4,6 +4,8 @@ import com.baomidou.mybatisplus.core.toolkit.IdWorker;
import
com.platform.business.constant.TeachingPlanConstants
;
import
com.platform.business.mapper.TeachingPlanAttachmentMapper
;
import
com.platform.business.mapper.TeachingPlanMapper
;
import
com.platform.business.model.dto.TeachingPlanAdminQueryDTO
;
import
com.platform.business.model.dto.TeachingPlanAdminUpdateDTO
;
import
com.platform.business.model.dto.TeachingPlanQueryDTO
;
import
com.platform.business.model.dto.TeachingPlanSaveDTO
;
import
com.platform.business.model.dto.TeachingPlanStatusDTO
;
...
...
@@ -11,16 +13,37 @@ import com.platform.business.model.entity.BsFileEntity;
import
com.platform.business.model.entity.TeachingPlanAttachmentEntity
;
import
com.platform.business.model.entity.TeachingPlanEntity
;
import
com.platform.business.model.vo.TeachingPlanAttachmentVO
;
import
com.platform.business.model.vo.TeachingPlanTeacherOptionVO
;
import
com.platform.business.model.vo.TeachingPlanVO
;
import
com.platform.business.service.BsFileService
;
import
com.platform.business.service.TeachingPlanService
;
import
com.platform.exception.BusinessException
;
import
org.apache.poi.ss.usermodel.Cell
;
import
org.apache.poi.ss.usermodel.CellStyle
;
import
org.apache.poi.ss.usermodel.FillPatternType
;
import
org.apache.poi.ss.usermodel.Font
;
import
org.apache.poi.ss.usermodel.IndexedColors
;
import
org.apache.poi.ss.usermodel.Row
;
import
org.apache.poi.ss.usermodel.Sheet
;
import
org.apache.poi.xssf.streaming.SXSSFWorkbook
;
import
org.apache.poi.xwpf.usermodel.ParagraphAlignment
;
import
org.apache.poi.xwpf.usermodel.XWPFDocument
;
import
org.apache.poi.xwpf.usermodel.XWPFParagraph
;
import
org.apache.poi.xwpf.usermodel.XWPFRun
;
import
org.apache.poi.xwpf.usermodel.XWPFTable
;
import
org.apache.poi.xwpf.usermodel.XWPFTableCell
;
import
org.apache.poi.xwpf.usermodel.XWPFTableRow
;
import
org.springframework.stereotype.Service
;
import
org.springframework.transaction.annotation.Transactional
;
import
org.springframework.util.StringUtils
;
import
org.springframework.web.multipart.MultipartFile
;
import
javax.annotation.Resource
;
import
javax.servlet.http.HttpServletResponse
;
import
java.io.IOException
;
import
java.io.OutputStream
;
import
java.net.URLEncoder
;
import
java.text.SimpleDateFormat
;
import
java.util.ArrayList
;
import
java.util.Collections
;
import
java.util.Date
;
...
...
@@ -30,7 +53,7 @@ import java.util.Locale;
import
java.util.Map
;
/**
* 教师端教案管理核心业务实现。
* 教师端
与管理员端
教案管理核心业务实现。
*
* <p>服务层不信任客户端提交的数据归属:每个入口都使用 JWT 解析得到的教师 ID,
* 并在查询或更新 SQL 中再次携带该 ID。正文、附件和状态各自还有独立的状态限制,
...
...
@@ -223,6 +246,161 @@ public class TeachingPlanServiceImpl implements TeachingPlanService {
bsFileService
.
downloadFile
(
attachment
.
getFileId
());
}
@Override
public
List
<
TeachingPlanVO
>
adminList
(
TeachingPlanAdminQueryDTO
query
)
{
TeachingPlanAdminQueryDTO
safeQuery
=
query
==
null
?
new
TeachingPlanAdminQueryDTO
()
:
query
;
normalizeAdminQuery
(
safeQuery
);
// 管理列表不装配附件,避免分页结果产生不必要的大对象;详情接口会返回完整附件。
return
teachingPlanMapper
.
selectAdminList
(
safeQuery
);
}
@Override
public
TeachingPlanVO
adminDetail
(
String
id
)
{
requireId
(
id
,
"教案ID不能为空"
);
TeachingPlanVO
plan
=
teachingPlanMapper
.
selectAdminDetail
(
id
);
if
(
plan
==
null
)
{
throw
new
BusinessException
(
"教案不存在"
);
}
fillAttachments
(
Collections
.
singletonList
(
plan
));
return
plan
;
}
@Override
@Transactional
(
rollbackFor
=
Exception
.
class
)
public
TeachingPlanVO
adminUpdate
(
String
id
,
TeachingPlanAdminUpdateDTO
request
,
String
reviewerId
,
String
reviewerName
)
{
requireId
(
id
,
"教案ID不能为空"
);
requireId
(
reviewerId
,
"无法获取当前管理员身份"
);
reviewerName
=
requireText
(
reviewerName
,
"管理员姓名"
,
TeachingPlanConstants
.
MAX_REVIEWER_NAME_LENGTH
);
validateAndNormalizeSaveRequest
(
request
);
String
targetStatus
=
normalizeStatus
(
request
==
null
?
null
:
request
.
getStatus
(),
false
);
String
reviewOpinion
=
trimToNull
(
request
.
getReviewOpinion
());
if
(
reviewOpinion
!=
null
&&
reviewOpinion
.
length
()
>
TeachingPlanConstants
.
MAX_REVIEW_OPINION_LENGTH
)
{
throw
new
BusinessException
(
"审核意见不能超过2000个字符"
);
}
// 行锁使正文、目标状态和审核人快照成为一次原子修改;管理员不受教师状态机限制。
TeachingPlanEntity
current
=
teachingPlanMapper
.
selectAdminPlanForUpdate
(
id
);
if
(
current
==
null
)
{
throw
new
BusinessException
(
"教案不存在"
);
}
TeachingPlanEntity
update
=
toEntity
(
request
);
update
.
setId
(
id
);
update
.
setStatus
(
targetStatus
);
update
.
setReviewerId
(
reviewerId
);
update
.
setReviewerName
(
reviewerName
);
update
.
setReviewOpinion
(
reviewOpinion
);
update
.
setReviewTime
(
new
Date
());
if
(
teachingPlanMapper
.
updateAdmin
(
update
)
!=
1
)
{
throw
new
BusinessException
(
"教案状态已变化,请刷新后重试"
);
}
return
adminDetail
(
id
);
}
@Override
public
List
<
TeachingPlanTeacherOptionVO
>
adminTeacherOptions
()
{
return
teachingPlanMapper
.
selectAdminTeacherOptions
();
}
@Override
public
void
exportAdminList
(
TeachingPlanAdminQueryDTO
query
,
HttpServletResponse
response
)
{
TeachingPlanAdminQueryDTO
safeQuery
=
query
==
null
?
new
TeachingPlanAdminQueryDTO
()
:
query
;
normalizeAdminQuery
(
safeQuery
);
List
<
TeachingPlanVO
>
plans
=
teachingPlanMapper
.
selectAdminList
(
safeQuery
);
// SXSSFWorkbook 只在内存保留固定数量的行,导出较多教案时不会线性占用堆内存。
SXSSFWorkbook
workbook
=
new
SXSSFWorkbook
(
100
);
try
{
Sheet
sheet
=
workbook
.
createSheet
(
"教案清单"
);
String
[]
headers
=
{
"教案ID"
,
"教案标题"
,
"课程名称"
,
"教师"
,
"授课日期"
,
"课时"
,
"状态"
,
"审核人"
,
"审核意见"
,
"审核时间"
,
"更新时间"
};
Row
header
=
sheet
.
createRow
(
0
);
CellStyle
headerStyle
=
createExcelHeaderStyle
(
workbook
);
for
(
int
i
=
0
;
i
<
headers
.
length
;
i
++)
{
Cell
cell
=
header
.
createCell
(
i
);
cell
.
setCellValue
(
headers
[
i
]);
cell
.
setCellStyle
(
headerStyle
);
}
int
rowIndex
=
1
;
for
(
TeachingPlanVO
plan
:
plans
)
{
Row
row
=
sheet
.
createRow
(
rowIndex
++);
writeExcelCell
(
row
,
0
,
plan
.
getId
());
writeExcelCell
(
row
,
1
,
plan
.
getTitle
());
writeExcelCell
(
row
,
2
,
plan
.
getCourseName
());
writeExcelCell
(
row
,
3
,
plan
.
getTeacherName
());
writeExcelCell
(
row
,
4
,
formatDate
(
plan
.
getTeachingDate
(),
"yyyy-MM-dd"
));
writeExcelCell
(
row
,
5
,
plan
.
getClassHours
());
writeExcelCell
(
row
,
6
,
plan
.
getStatus
());
writeExcelCell
(
row
,
7
,
plan
.
getReviewerName
());
writeExcelCell
(
row
,
8
,
plan
.
getReviewOpinion
());
writeExcelCell
(
row
,
9
,
formatDate
(
plan
.
getReviewTime
(),
"yyyy-MM-dd HH:mm:ss"
));
writeExcelCell
(
row
,
10
,
formatDate
(
plan
.
getUpdateTime
(),
"yyyy-MM-dd HH:mm:ss"
));
}
// 使用固定列宽,避免流式工作簿为自动宽度重新跟踪全部历史行。
int
[]
widths
=
{
24
,
28
,
24
,
16
,
14
,
10
,
14
,
16
,
36
,
22
,
22
};
for
(
int
i
=
0
;
i
<
widths
.
length
;
i
++)
{
sheet
.
setColumnWidth
(
i
,
widths
[
i
]
*
256
);
}
writeDownloadResponse
(
response
,
workbook
,
"教案清单.xlsx"
,
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
);
}
catch
(
IOException
e
)
{
throw
new
BusinessException
(
"导出教案清单失败"
);
}
finally
{
// dispose 会删除 SXSSF 写盘产生的临时文件,避免长期运行后占满临时目录。
workbook
.
dispose
();
try
{
workbook
.
close
();
}
catch
(
IOException
ignored
)
{
// 主响应已经处理完成,关闭临时工作簿失败不覆盖原始业务异常。
}
}
}
@Override
public
void
exportAdminDetail
(
String
id
,
HttpServletResponse
response
)
{
TeachingPlanVO
plan
=
adminDetail
(
id
);
try
(
XWPFDocument
document
=
new
XWPFDocument
())
{
XWPFParagraph
title
=
document
.
createParagraph
();
title
.
setAlignment
(
ParagraphAlignment
.
CENTER
);
XWPFRun
titleRun
=
title
.
createRun
();
titleRun
.
setBold
(
true
);
titleRun
.
setFontSize
(
18
);
titleRun
.
setText
(
plan
.
getTitle
());
XWPFTable
summary
=
document
.
createTable
(
1
,
2
);
writeWordTableRow
(
summary
.
getRow
(
0
),
"教师"
,
plan
.
getTeacherName
());
addWordTableRow
(
summary
,
"课程名称"
,
plan
.
getCourseName
());
addWordTableRow
(
summary
,
"授课日期"
,
formatDate
(
plan
.
getTeachingDate
(),
"yyyy-MM-dd"
));
addWordTableRow
(
summary
,
"课时"
,
value
(
plan
.
getClassHours
()));
addWordTableRow
(
summary
,
"状态"
,
plan
.
getStatus
());
addWordSection
(
document
,
"教学目标"
,
plan
.
getTeachingObjectives
());
addWordSection
(
document
,
"教学内容"
,
plan
.
getTeachingContent
());
addWordSection
(
document
,
"教学重点"
,
plan
.
getKeyPoints
());
addWordSection
(
document
,
"教学难点"
,
plan
.
getDifficultPoints
());
addWordSection
(
document
,
"教学方法"
,
plan
.
getTeachingMethods
());
addWordSection
(
document
,
"教学过程"
,
plan
.
getTeachingProcess
());
addWordSection
(
document
,
"课后总结"
,
plan
.
getAfterClassSummary
());
addWordSection
(
document
,
"审核人"
,
plan
.
getReviewerName
());
addWordSection
(
document
,
"审核意见"
,
plan
.
getReviewOpinion
());
addWordSection
(
document
,
"审核时间"
,
formatDate
(
plan
.
getReviewTime
(),
"yyyy-MM-dd HH:mm:ss"
));
addWordSection
(
document
,
"附件"
,
attachmentNames
(
plan
.
getAttachments
()));
writeDownloadResponse
(
response
,
document
,
safeFilename
(
plan
.
getTitle
())
+
"-教案.docx"
,
"application/vnd.openxmlformats-officedocument.wordprocessingml.document"
);
}
catch
(
IOException
e
)
{
throw
new
BusinessException
(
"导出教案失败"
);
}
}
/** 将附件一次性批量装配到列表结果,避免分页结果中出现逐条查询。 */
private
void
fillAttachments
(
List
<
TeachingPlanVO
>
plans
)
{
if
(
plans
==
null
||
plans
.
isEmpty
())
{
...
...
@@ -281,19 +459,41 @@ public class TeachingPlanServiceImpl implements TeachingPlanService {
/** 规范化列表筛选值并验证日期区间。 */
private
void
normalizeQuery
(
TeachingPlanQueryDTO
query
)
{
query
.
setKeyword
(
trimToNull
(
query
.
getKeyword
()));
String
status
=
trimToNull
(
query
.
getStatus
());
status
=
status
==
null
?
TeachingPlanConstants
.
STATUS_ALL
:
status
.
toUpperCase
(
Locale
.
ROOT
);
if
(!
TeachingPlanConstants
.
STATUS_ALL
.
equals
(
status
)
&&
!
TeachingPlanConstants
.
STATUSES
.
contains
(
status
))
{
throw
new
BusinessException
(
"筛选状态只能是 ALL、DRAFT、PENDING、APPROVED 或 REJECTED"
);
}
query
.
setStatus
(
status
);
query
.
setStatus
(
normalizeStatus
(
query
.
getStatus
(),
true
));
if
(
query
.
getStartDate
()
!=
null
&&
query
.
getEndDate
()
!=
null
&&
query
.
getStartDate
().
after
(
query
.
getEndDate
()))
{
throw
new
BusinessException
(
"授课日期开始值不能晚于结束值"
);
}
}
/** 管理端在教师端通用筛选基础上额外清洗 teacherId。 */
private
void
normalizeAdminQuery
(
TeachingPlanAdminQueryDTO
query
)
{
normalizeQuery
(
query
);
query
.
setTeacherId
(
trimToNull
(
query
.
getTeacherId
()));
}
/**
* 统一规范化教案状态。
*
* @param allowAll 查询条件允许使用 ALL;更新请求只能使用四个真实业务状态
*/
private
String
normalizeStatus
(
String
value
,
boolean
allowAll
)
{
String
status
=
trimToNull
(
value
);
if
(
status
==
null
)
{
if
(
allowAll
)
{
return
TeachingPlanConstants
.
STATUS_ALL
;
}
throw
new
BusinessException
(
"目标状态不能为空"
);
}
status
=
status
.
toUpperCase
(
Locale
.
ROOT
);
if
((
allowAll
&&
TeachingPlanConstants
.
STATUS_ALL
.
equals
(
status
))
||
TeachingPlanConstants
.
STATUSES
.
contains
(
status
))
{
return
status
;
}
String
prefix
=
allowAll
?
"筛选状态只能是 ALL、"
:
"教案状态只能是 "
;
throw
new
BusinessException
(
prefix
+
"DRAFT、PENDING、APPROVED 或 REJECTED"
);
}
/** 校验并原地清洗结构化教案字段,保证新增和编辑使用完全相同的规则。 */
private
void
validateAndNormalizeSaveRequest
(
TeachingPlanSaveDTO
request
)
{
if
(
request
==
null
)
{
...
...
@@ -379,6 +579,123 @@ public class TeachingPlanServiceImpl implements TeachingPlanService {
return
vo
;
}
/** 创建管理员清单统一的深色表头样式。 */
private
CellStyle
createExcelHeaderStyle
(
SXSSFWorkbook
workbook
)
{
CellStyle
style
=
workbook
.
createCellStyle
();
style
.
setFillForegroundColor
(
IndexedColors
.
DARK_BLUE
.
getIndex
());
style
.
setFillPattern
(
FillPatternType
.
SOLID_FOREGROUND
);
Font
font
=
workbook
.
createFont
();
font
.
setBold
(
true
);
font
.
setColor
(
IndexedColors
.
WHITE
.
getIndex
());
style
.
setFont
(
font
);
return
style
;
}
/** 所有Excel值按文本写入,避免长ID被电子表格自动转为科学计数法。 */
private
void
writeExcelCell
(
Row
row
,
int
column
,
Object
cellValue
)
{
row
.
createCell
(
column
).
setCellValue
(
value
(
cellValue
));
}
/** 写入Word基本信息表格的一行。 */
private
void
addWordTableRow
(
XWPFTable
table
,
String
label
,
String
content
)
{
writeWordTableRow
(
table
.
createRow
(),
label
,
content
);
}
/** 重置单元格默认段落内容并写入标签和值。 */
private
void
writeWordTableRow
(
XWPFTableRow
row
,
String
label
,
String
content
)
{
while
(
row
.
getTableCells
().
size
()
<
2
)
{
row
.
addNewTableCell
();
}
writeWordCell
(
row
.
getCell
(
0
),
label
);
writeWordCell
(
row
.
getCell
(
1
),
content
);
}
private
void
writeWordCell
(
XWPFTableCell
cell
,
String
content
)
{
cell
.
removeParagraph
(
0
);
XWPFParagraph
paragraph
=
cell
.
addParagraph
();
writeWordText
(
paragraph
.
createRun
(),
content
);
}
/** 将长正文按“标题 + 内容”段落写入Word,并正确保留换行。 */
private
void
addWordSection
(
XWPFDocument
document
,
String
label
,
String
content
)
{
XWPFParagraph
heading
=
document
.
createParagraph
();
XWPFRun
headingRun
=
heading
.
createRun
();
headingRun
.
setBold
(
true
);
headingRun
.
setText
(
label
);
XWPFParagraph
body
=
document
.
createParagraph
();
writeWordText
(
body
.
createRun
(),
content
);
}
private
void
writeWordText
(
XWPFRun
run
,
String
content
)
{
String
[]
lines
=
value
(
content
).
split
(
"\\r?\\n"
,
-
1
);
for
(
int
i
=
0
;
i
<
lines
.
length
;
i
++)
{
if
(
i
>
0
)
{
run
.
addBreak
();
}
run
.
setText
(
lines
[
i
]);
}
}
/** 将附件名称汇总为可读列表;导出不暴露服务器文件路径和文件ID。 */
private
String
attachmentNames
(
List
<
TeachingPlanAttachmentVO
>
attachments
)
{
if
(
attachments
==
null
||
attachments
.
isEmpty
())
{
return
"无"
;
}
StringBuilder
builder
=
new
StringBuilder
();
for
(
int
i
=
0
;
i
<
attachments
.
size
();
i
++)
{
if
(
i
>
0
)
{
builder
.
append
(
'\n'
);
}
builder
.
append
(
i
+
1
).
append
(
". "
).
append
(
value
(
attachments
.
get
(
i
).
getFileName
()));
}
return
builder
.
toString
();
}
private
String
formatDate
(
Date
date
,
String
pattern
)
{
return
date
==
null
?
""
:
new
SimpleDateFormat
(
pattern
).
format
(
date
);
}
private
String
value
(
Object
value
)
{
return
value
==
null
?
""
:
String
.
valueOf
(
value
);
}
/** 清理Windows和浏览器下载文件名中的非法字符,并限制过长标题。 */
private
String
safeFilename
(
String
title
)
{
String
safe
=
value
(
title
).
replaceAll
(
"[\\\\/:*?\"<>|]"
,
"_"
).
trim
();
if
(
safe
.
isEmpty
())
{
safe
=
"未命名"
;
}
return
safe
.
length
()
>
80
?
safe
.
substring
(
0
,
80
)
:
safe
;
}
/** 写入Excel响应,采用RFC 5987格式保证中文文件名跨浏览器可用。 */
private
void
writeDownloadResponse
(
HttpServletResponse
response
,
SXSSFWorkbook
workbook
,
String
filename
,
String
contentType
)
throws
IOException
{
prepareDownloadResponse
(
response
,
filename
,
contentType
);
try
(
OutputStream
output
=
response
.
getOutputStream
())
{
workbook
.
write
(
output
);
output
.
flush
();
}
}
/** 写入Word响应,响应头规则与Excel保持一致。 */
private
void
writeDownloadResponse
(
HttpServletResponse
response
,
XWPFDocument
document
,
String
filename
,
String
contentType
)
throws
IOException
{
prepareDownloadResponse
(
response
,
filename
,
contentType
);
try
(
OutputStream
output
=
response
.
getOutputStream
())
{
document
.
write
(
output
);
output
.
flush
();
}
}
private
void
prepareDownloadResponse
(
HttpServletResponse
response
,
String
filename
,
String
contentType
)
throws
IOException
{
String
encoded
=
URLEncoder
.
encode
(
filename
,
"UTF-8"
).
replace
(
"+"
,
"%20"
);
response
.
setCharacterEncoding
(
"UTF-8"
);
response
.
setContentType
(
contentType
);
response
.
setHeader
(
"Content-Disposition"
,
"attachment; filename*=UTF-8''"
+
encoded
);
}
private
String
requireText
(
String
value
,
String
fieldName
,
int
maxLength
)
{
String
normalized
=
trimToNull
(
value
);
if
(
normalized
==
null
)
{
...
...
practical-business/src/main/resources/com/platform/business/mapper/TeachingPlanMapper.xml
View file @
6525db95
...
...
@@ -19,6 +19,10 @@
p.teaching_process AS teachingProcess,
p.after_class_summary AS afterClassSummary,
p.status,
p.reviewer_id AS reviewerId,
p.reviewer_name AS reviewerName,
p.review_opinion AS reviewOpinion,
p.review_time AS reviewTime,
p.create_time AS createTime,
p.update_time AS updateTime
</sql>
...
...
@@ -106,4 +110,86 @@
AND status = 'DRAFT'
AND del_flag = 0
</update>
<!--
管理员分页和Excel导出复用同一查询。关键字覆盖标题、课程和教师姓名;
LIKE查询保留前后模糊匹配,以符合页面搜索体验。
-->
<select
id=
"selectAdminList"
resultType=
"com.platform.business.model.vo.TeachingPlanVO"
>
SELECT
<include
refid=
"planColumns"
/>
FROM teaching_plan p
LEFT JOIN user u ON u.id = p.teacher_id
WHERE p.del_flag = 0
<if
test=
"query.keyword != null and query.keyword != ''"
>
AND (p.title LIKE CONCAT('%', #{query.keyword}, '%')
OR p.course_name LIKE CONCAT('%', #{query.keyword}, '%')
OR u.nick_name LIKE CONCAT('%', #{query.keyword}, '%'))
</if>
<if
test=
"query.teacherId != null and query.teacherId != ''"
>
AND p.teacher_id = #{query.teacherId}
</if>
<if
test=
"query.status != null and query.status != '' and query.status != 'ALL'"
>
AND p.status = #{query.status}
</if>
<if
test=
"query.startDate != null"
>
AND p.teaching_date
<![CDATA[>=]]>
#{query.startDate}
</if>
<if
test=
"query.endDate != null"
>
AND p.teaching_date
<![CDATA[<=]]>
#{query.endDate}
</if>
ORDER BY p.update_time DESC, p.id DESC
</select>
<select
id=
"selectAdminDetail"
resultType=
"com.platform.business.model.vo.TeachingPlanVO"
>
SELECT
<include
refid=
"planColumns"
/>
FROM teaching_plan p
LEFT JOIN user u ON u.id = p.teacher_id
WHERE p.id = #{id}
AND p.del_flag = 0
</select>
<!-- 行锁必须在事务中调用,管理端不存在教师归属条件。 -->
<select
id=
"selectAdminPlanForUpdate"
resultType=
"com.platform.business.model.entity.TeachingPlanEntity"
>
SELECT *
FROM teaching_plan
WHERE id = #{id}
AND del_flag = 0
FOR UPDATE
</select>
<update
id=
"updateAdmin"
>
UPDATE teaching_plan
SET title = #{plan.title},
course_name = #{plan.courseName},
teaching_date = #{plan.teachingDate},
class_hours = #{plan.classHours},
teaching_objectives = #{plan.teachingObjectives},
teaching_content = #{plan.teachingContent},
key_points = #{plan.keyPoints},
difficult_points = #{plan.difficultPoints},
teaching_methods = #{plan.teachingMethods},
teaching_process = #{plan.teachingProcess},
after_class_summary = #{plan.afterClassSummary},
status = #{plan.status},
reviewer_id = #{plan.reviewerId},
reviewer_name = #{plan.reviewerName},
review_opinion = #{plan.reviewOpinion},
review_time = #{plan.reviewTime},
update_time = CURRENT_TIMESTAMP
WHERE id = #{plan.id}
AND del_flag = 0
</update>
<!-- 只提供拥有有效教案的教师,避免筛选列表出现永远查不到数据的选项。 -->
<select
id=
"selectAdminTeacherOptions"
resultType=
"com.platform.business.model.vo.TeachingPlanTeacherOptionVO"
>
SELECT p.teacher_id AS teacherId,
COALESCE(MAX(u.nick_name), p.teacher_id) AS teacherName
FROM teaching_plan p
LEFT JOIN user u ON u.id = p.teacher_id
WHERE p.del_flag = 0
GROUP BY p.teacher_id
ORDER BY teacherName ASC, p.teacher_id ASC
</select>
</mapper>
practical-business/src/main/resources/sql/teaching_plan.sql
View file @
6525db95
...
...
@@ -18,12 +18,17 @@ CREATE TABLE IF NOT EXISTS teaching_plan (
teaching_process
MEDIUMTEXT
NOT
NULL
COMMENT
'教学过程'
,
after_class_summary
MEDIUMTEXT
NULL
COMMENT
'课后总结'
,
status
VARCHAR
(
16
)
NOT
NULL
DEFAULT
'DRAFT'
COMMENT
'DRAFT/PENDING/APPROVED/REJECTED'
,
reviewer_id
VARCHAR
(
64
)
NULL
COMMENT
'最近一次管理端保存的管理员用户ID'
,
reviewer_name
VARCHAR
(
100
)
NULL
COMMENT
'最近一次审核人姓名快照'
,
review_opinion
VARCHAR
(
2000
)
NULL
COMMENT
'最近一次审核意见'
,
review_time
DATETIME
NULL
COMMENT
'最近一次管理端保存或审核时间'
,
del_flag
TINYINT
NOT
NULL
DEFAULT
0
COMMENT
'逻辑删除:0正常,1删除'
,
create_time
DATETIME
NOT
NULL
DEFAULT
CURRENT_TIMESTAMP
COMMENT
'创建时间'
,
update_time
DATETIME
NOT
NULL
DEFAULT
CURRENT_TIMESTAMP
ON
UPDATE
CURRENT_TIMESTAMP
COMMENT
'更新时间'
,
PRIMARY
KEY
(
id
),
KEY
idx_teaching_plan_teacher_status
(
teacher_id
,
del_flag
,
status
),
KEY
idx_teaching_plan_teacher_date
(
teacher_id
,
del_flag
,
teaching_date
)
KEY
idx_teaching_plan_teacher_date
(
teacher_id
,
del_flag
,
teaching_date
),
KEY
idx_teaching_plan_admin_filter
(
del_flag
,
status
,
teaching_date
,
teacher_id
)
)
ENGINE
=
InnoDB
DEFAULT
CHARSET
=
utf8mb4
COLLATE
=
utf8mb4_unicode_ci
COMMENT
=
'教师教案'
;
CREATE
TABLE
IF
NOT
EXISTS
teaching_plan_attachment
(
...
...
@@ -39,3 +44,75 @@ CREATE TABLE IF NOT EXISTS teaching_plan_attachment (
KEY
idx_teaching_plan_attachment_plan
(
plan_id
,
del_flag
),
KEY
idx_teaching_plan_attachment_file
(
file_id
)
)
ENGINE
=
InnoDB
DEFAULT
CHARSET
=
utf8mb4
COLLATE
=
utf8mb4_unicode_ci
COMMENT
=
'教案附件关联'
;
--
-- 管理端审核字段增量迁移。
-- teaching_plan 可能已由旧版本脚本创建,因此不能只依赖上面的 CREATE TABLE IF NOT EXISTS;
-- 下面逐项检查字段和索引,允许本脚本在开发、测试和生产环境安全重复执行。
-- 旧的已通过/已驳回记录没有可信审核人来源,迁移时有意保持审核字段为 NULL。
--
DELIMITER
$$
DROP
PROCEDURE
IF
EXISTS
migrate_teaching_plan_admin
$$
CREATE
PROCEDURE
migrate_teaching_plan_admin
()
BEGIN
IF
NOT
EXISTS
(
SELECT
1
FROM
information_schema
.
columns
WHERE
table_schema
=
DATABASE
()
AND
table_name
=
'teaching_plan'
AND
column_name
=
'reviewer_id'
)
THEN
ALTER
TABLE
teaching_plan
ADD
COLUMN
reviewer_id
VARCHAR
(
64
)
NULL
COMMENT
'最近一次管理端保存的管理员用户ID'
AFTER
status
;
END
IF
;
IF
NOT
EXISTS
(
SELECT
1
FROM
information_schema
.
columns
WHERE
table_schema
=
DATABASE
()
AND
table_name
=
'teaching_plan'
AND
column_name
=
'reviewer_name'
)
THEN
ALTER
TABLE
teaching_plan
ADD
COLUMN
reviewer_name
VARCHAR
(
100
)
NULL
COMMENT
'最近一次审核人姓名快照'
AFTER
reviewer_id
;
END
IF
;
IF
NOT
EXISTS
(
SELECT
1
FROM
information_schema
.
columns
WHERE
table_schema
=
DATABASE
()
AND
table_name
=
'teaching_plan'
AND
column_name
=
'review_opinion'
)
THEN
ALTER
TABLE
teaching_plan
ADD
COLUMN
review_opinion
VARCHAR
(
2000
)
NULL
COMMENT
'最近一次审核意见'
AFTER
reviewer_name
;
END
IF
;
IF
NOT
EXISTS
(
SELECT
1
FROM
information_schema
.
columns
WHERE
table_schema
=
DATABASE
()
AND
table_name
=
'teaching_plan'
AND
column_name
=
'review_time'
)
THEN
ALTER
TABLE
teaching_plan
ADD
COLUMN
review_time
DATETIME
NULL
COMMENT
'最近一次管理端保存或审核时间'
AFTER
review_opinion
;
END
IF
;
IF
NOT
EXISTS
(
SELECT
1
FROM
information_schema
.
statistics
WHERE
table_schema
=
DATABASE
()
AND
table_name
=
'teaching_plan'
AND
index_name
=
'idx_teaching_plan_admin_filter'
)
THEN
ALTER
TABLE
teaching_plan
ADD
INDEX
idx_teaching_plan_admin_filter
(
del_flag
,
status
,
teaching_date
,
teacher_id
);
END
IF
;
END
$$
CALL
migrate_teaching_plan_admin
()
$$
DROP
PROCEDURE
IF
EXISTS
migrate_teaching_plan_admin
$$
DELIMITER
;
practical-business/src/main/resources/teaching-plan-api.md
View file @
6525db95
#
教师端
教案管理接口
# 教案管理接口
所有
接口统一使用前缀
`/teaching/plan/teacher`
,并从请求头
`Authorization`
解析当前用户。
教师端
接口统一使用前缀
`/teaching/plan/teacher`
,并从请求头
`Authorization`
解析当前用户。
服务端要求用户具有
`phone_role.role_name=教师`
,且不会接收客户端传入的
`teacherId`
。
部署前执行
`src/main/resources/sql/teaching_plan.sql`
创建教案主表和附件关联表。
...
...
@@ -78,3 +78,103 @@
每份教案最多保留 10 个附件,支持 PDF、DOC、DOCX、PPT、PPTX,扩展名不区分大小写,单个附件不得超过
50 MiB。上传和删除附件仅允许在
`DRAFT`
状态执行;下载在任意有效状态均可执行。接口不返回服务器文件路径。
## 5. 管理员端接口约定
管理员接口统一使用前缀
`/teaching/plan/admin`
。每个入口都会从
`Authorization`
中解析当前用户,
并要求
`phone_role.role_name=管理员`
。审核人 ID、审核人姓名和审核时间均由服务端写入,前端无法指定。
管理员使用与教师端相同的简化正文结构,不包含原型中的班级、课程类型、章节、职业等级和结构化教学环节。
管理员可编辑任意有效教案,并可直接设置
`DRAFT`
、
`PENDING`
、
`APPROVED`
或
`REJECTED`
,不受教师端状态机限制。
### 5.1 分页查询
`POST /teaching/plan/admin/page`
```
json
{
"pageNum"
:
1
,
"pageSize"
:
10
,
"keyword"
:
"高处作业"
,
"teacherId"
:
"190000000000000001"
,
"status"
:
"APPROVED"
,
"startDate"
:
"2026-08-01"
,
"endDate"
:
"2026-08-31"
}
```
-
`keyword`
同时模糊匹配教案标题、课程名称和教师姓名。
-
`teacherId`
为空时查询全部教师。
-
`status`
为空或
`ALL`
时查询全部状态,状态值不区分大小写。
-
日期范围按授课日期筛选并包含起止日。
-
页码默认 1,每页默认 10 条,单页最多 100 条。
-
返回项目统一的
`TableDataInfo`
;列表不返回附件,详情接口返回有效附件。
### 5.2 教师筛选选项与详情
-
`GET /teaching/plan/admin/teachers`
:返回至少拥有一份有效教案的教师 ID 和姓名。
-
`GET /teaching/plan/admin/{id}`
:返回任意未逻辑删除的教案详情、审核信息和有效附件。
详情在原有字段基础上增加:
```
json
{
"reviewerId"
:
"190000000000000099"
,
"reviewerName"
:
"教务管理员"
,
"reviewOpinion"
:
"内容完整,同意通过"
,
"reviewTime"
:
"2026-08-17 15:00:00"
}
```
### 5.3 管理员编辑和审核
`PUT /teaching/plan/admin/{id}`
```
json
{
"title"
:
"高处作业安全教案"
,
"courseName"
:
"高处作业安全"
,
"teachingDate"
:
"2026-08-20"
,
"classHours"
:
2
,
"teachingObjectives"
:
"掌握高处作业基本安全要求"
,
"teachingContent"
:
"安全防护用品使用和风险识别"
,
"keyPoints"
:
"正确使用安全带"
,
"difficultPoints"
:
"复杂环境风险识别"
,
"teachingMethods"
:
"讲授、演示与案例讨论"
,
"teachingProcess"
:
"导入、讲授、演示、练习和总结"
,
"afterClassSummary"
:
"课堂目标已完成"
,
"status"
:
"APPROVED"
,
"reviewOpinion"
:
"内容完整,同意通过"
}
```
正文校验规则与教师端一致。
`status`
必填,管理员允许在任意当前状态间直接切换;
`reviewOpinion`
可为空,最多 2000 个字符。正文、状态、审核人快照和审核时间在同一事务中保存。
### 5.4 导出
-
`POST /teaching/plan/admin/export`
:请求体与分页查询一致,但忽略
`pageNum/pageSize`
,将全部匹配记录导出为 Excel。
-
`GET /teaching/plan/admin/{id}/export`
:导出单份 Word 教案,包含全部简化正文、教师信息、审核信息和附件名称。
下载响应使用标准 Office MIME 类型和
`filename*=UTF-8''...`
响应头,前端应以二进制 Blob 接收。
## 6. 数据库升级
新部署和旧环境均执行
`src/main/resources/sql/teaching_plan.sql`
。脚本会创建缺失表,并通过
`information_schema`
幂等补充以下管理端字段和筛选索引:
-
`reviewer_id`
:最近一次管理端保存的管理员用户 ID。
-
`reviewer_name`
:审核人姓名快照。
-
`review_opinion`
:最近一次审核意见。
-
`review_time`
:最近一次管理端保存或审核时间。
-
`idx_teaching_plan_admin_filter`
:管理端状态、日期和教师筛选索引。
历史数据没有可信的审核人来源,因此脚本不会为旧的
`APPROVED/REJECTED`
记录伪造审核信息。
## 7. 常见错误
-
未登录、令牌失效:
`未获取到登录凭证`
或
`登录凭证无效或已过期`
。
-
非管理员调用管理端接口:
`只有管理员可以访问管理端接口`
。
-
教案不存在或已逻辑删除:
`教案不存在`
。
-
非法状态或日期范围:返回对应的业务参数错误。
-
导出流写入失败:
`导出教案清单失败`
或
`导出教案失败`
。
practical-business/src/test/java/com/platform/business/controller/TeachingPlanAdminControllerTest.java
0 → 100644
View file @
6525db95
package
com.platform.business.controller
;
import
com.platform.business.model.dto.TeachingPlanAdminQueryDTO
;
import
com.platform.business.model.dto.TeachingPlanAdminUpdateDTO
;
import
com.platform.business.model.entity.UserEntity
;
import
com.platform.business.model.vo.TeachingPlanVO
;
import
com.platform.business.service.AuthenticatedUserService
;
import
com.platform.business.service.TeachingPlanService
;
import
com.platform.exception.BusinessException
;
import
org.junit.jupiter.api.BeforeEach
;
import
org.junit.jupiter.api.Test
;
import
org.junit.jupiter.api.extension.ExtendWith
;
import
org.mockito.Mock
;
import
org.mockito.junit.jupiter.MockitoExtension
;
import
org.springframework.mock.web.MockHttpServletRequest
;
import
org.springframework.test.util.ReflectionTestUtils
;
import
static
org
.
junit
.
jupiter
.
api
.
Assertions
.
assertEquals
;
import
static
org
.
junit
.
jupiter
.
api
.
Assertions
.
assertThrows
;
import
static
org
.
mockito
.
ArgumentMatchers
.
any
;
import
static
org
.
mockito
.
ArgumentMatchers
.
eq
;
import
static
org
.
mockito
.
Mockito
.
doThrow
;
import
static
org
.
mockito
.
Mockito
.
never
;
import
static
org
.
mockito
.
Mockito
.
verify
;
import
static
org
.
mockito
.
Mockito
.
when
;
/** 管理员教案控制器的分页、角色校验和审核人来源测试。 */
@ExtendWith
(
MockitoExtension
.
class
)
class
TeachingPlanAdminControllerTest
{
@Mock
private
TeachingPlanService
teachingPlanService
;
@Mock
private
AuthenticatedUserService
authenticatedUserService
;
private
TeachingPlanAdminController
controller
;
@BeforeEach
void
setUp
()
{
controller
=
new
TeachingPlanAdminController
();
ReflectionTestUtils
.
setField
(
controller
,
"teachingPlanService"
,
teachingPlanService
);
ReflectionTestUtils
.
setField
(
controller
,
"authenticatedUserService"
,
authenticatedUserService
);
}
@Test
void
normalizePageShouldApplyDefaultsAndMaximum
()
{
TeachingPlanAdminQueryDTO
defaults
=
new
TeachingPlanAdminQueryDTO
();
controller
.
normalizePage
(
defaults
);
assertEquals
(
1
,
defaults
.
getPageNum
());
assertEquals
(
10
,
defaults
.
getPageSize
());
TeachingPlanAdminQueryDTO
oversized
=
new
TeachingPlanAdminQueryDTO
();
oversized
.
setPageNum
(
3
);
oversized
.
setPageSize
(
500
);
controller
.
normalizePage
(
oversized
);
assertEquals
(
3
,
oversized
.
getPageNum
());
assertEquals
(
100
,
oversized
.
getPageSize
());
}
@Test
void
detailShouldStopBeforeServiceWhenUserIsNotAdmin
()
{
MockHttpServletRequest
request
=
new
MockHttpServletRequest
();
UserEntity
ordinaryUser
=
new
UserEntity
();
when
(
authenticatedUserService
.
current
(
request
)).
thenReturn
(
ordinaryUser
);
doThrow
(
new
BusinessException
(
"只有管理员可以访问管理端接口"
))
.
when
(
authenticatedUserService
).
requireAdmin
(
ordinaryUser
);
assertThrows
(
BusinessException
.
class
,
()
->
controller
.
detail
(
"plan-1"
,
request
));
verify
(
teachingPlanService
,
never
()).
adminDetail
(
any
());
}
@Test
void
updateShouldUseAuthenticatedAdministratorAsReviewer
()
{
MockHttpServletRequest
request
=
new
MockHttpServletRequest
();
UserEntity
administrator
=
new
UserEntity
();
administrator
.
setId
(
"admin-1"
);
administrator
.
setNickName
(
"教务管理员"
);
when
(
authenticatedUserService
.
current
(
request
)).
thenReturn
(
administrator
);
when
(
teachingPlanService
.
adminUpdate
(
eq
(
"plan-1"
),
any
(),
eq
(
"admin-1"
),
eq
(
"教务管理员"
)))
.
thenReturn
(
new
TeachingPlanVO
());
controller
.
update
(
"plan-1"
,
new
TeachingPlanAdminUpdateDTO
(),
request
);
verify
(
authenticatedUserService
).
requireAdmin
(
administrator
);
verify
(
teachingPlanService
).
adminUpdate
(
eq
(
"plan-1"
),
any
(),
eq
(
"admin-1"
),
eq
(
"教务管理员"
));
}
}
practical-business/src/test/java/com/platform/business/mapper/TeachingPlanMapperXmlTest.java
0 → 100644
View file @
6525db95
package
com.platform.business.mapper
;
import
org.apache.ibatis.builder.xml.XMLMapperBuilder
;
import
org.apache.ibatis.io.Resources
;
import
org.apache.ibatis.session.Configuration
;
import
org.junit.jupiter.api.Test
;
import
java.io.InputStream
;
import
static
org
.
junit
.
jupiter
.
api
.
Assertions
.
assertTrue
;
/** 确保教案管理端新增SQL在应用启动前即可被MyBatis完整解析和注册。 */
class
TeachingPlanMapperXmlTest
{
@Test
void
mapperXmlShouldParseAndRegisterAdminStatements
()
throws
Exception
{
String
resource
=
"com/platform/business/mapper/TeachingPlanMapper.xml"
;
Configuration
configuration
=
new
Configuration
();
try
(
InputStream
input
=
Resources
.
getResourceAsStream
(
resource
))
{
XMLMapperBuilder
builder
=
new
XMLMapperBuilder
(
input
,
configuration
,
resource
,
configuration
.
getSqlFragments
());
builder
.
parse
();
}
String
namespace
=
"com.platform.business.mapper.TeachingPlanMapper."
;
assertTrue
(
configuration
.
hasStatement
(
namespace
+
"selectAdminList"
));
assertTrue
(
configuration
.
hasStatement
(
namespace
+
"selectAdminDetail"
));
assertTrue
(
configuration
.
hasStatement
(
namespace
+
"selectAdminPlanForUpdate"
));
assertTrue
(
configuration
.
hasStatement
(
namespace
+
"updateAdmin"
));
assertTrue
(
configuration
.
hasStatement
(
namespace
+
"selectAdminTeacherOptions"
));
}
}
practical-business/src/test/java/com/platform/business/service/impl/TeachingPlanAdminServiceImplTest.java
0 → 100644
View file @
6525db95
package
com.platform.business.service.impl
;
import
com.platform.business.constant.TeachingPlanConstants
;
import
com.platform.business.mapper.TeachingPlanAttachmentMapper
;
import
com.platform.business.mapper.TeachingPlanMapper
;
import
com.platform.business.model.dto.TeachingPlanAdminQueryDTO
;
import
com.platform.business.model.dto.TeachingPlanAdminUpdateDTO
;
import
com.platform.business.model.entity.TeachingPlanEntity
;
import
com.platform.business.model.vo.TeachingPlanAttachmentVO
;
import
com.platform.business.model.vo.TeachingPlanVO
;
import
com.platform.business.service.BsFileService
;
import
com.platform.exception.BusinessException
;
import
org.apache.poi.xssf.usermodel.XSSFWorkbook
;
import
org.apache.poi.xwpf.usermodel.XWPFDocument
;
import
org.junit.jupiter.api.Test
;
import
org.junit.jupiter.api.extension.ExtendWith
;
import
org.mockito.ArgumentCaptor
;
import
org.mockito.InjectMocks
;
import
org.mockito.Mock
;
import
org.mockito.junit.jupiter.MockitoExtension
;
import
org.springframework.mock.web.MockHttpServletResponse
;
import
java.io.ByteArrayInputStream
;
import
java.util.Collections
;
import
java.util.Date
;
import
static
org
.
junit
.
jupiter
.
api
.
Assertions
.
assertEquals
;
import
static
org
.
junit
.
jupiter
.
api
.
Assertions
.
assertNotNull
;
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
.
ArgumentMatchers
.
anyList
;
import
static
org
.
mockito
.
Mockito
.
never
;
import
static
org
.
mockito
.
Mockito
.
verify
;
import
static
org
.
mockito
.
Mockito
.
when
;
/** 管理员教案查询、宽松审核、身份审计以及Excel/Word导出的单元测试。 */
@ExtendWith
(
MockitoExtension
.
class
)
class
TeachingPlanAdminServiceImplTest
{
@Mock
private
TeachingPlanMapper
teachingPlanMapper
;
@Mock
private
TeachingPlanAttachmentMapper
attachmentMapper
;
@Mock
private
BsFileService
bsFileService
;
@InjectMocks
private
TeachingPlanServiceImpl
teachingPlanService
;
@Test
void
adminListShouldNormalizeAllSupportedFilters
()
{
when
(
teachingPlanMapper
.
selectAdminList
(
any
())).
thenReturn
(
Collections
.
emptyList
());
TeachingPlanAdminQueryDTO
query
=
new
TeachingPlanAdminQueryDTO
();
query
.
setKeyword
(
" 安全课 "
);
query
.
setTeacherId
(
" teacher-1 "
);
query
.
setStatus
(
"approved"
);
teachingPlanService
.
adminList
(
query
);
assertEquals
(
"安全课"
,
query
.
getKeyword
());
assertEquals
(
"teacher-1"
,
query
.
getTeacherId
());
assertEquals
(
TeachingPlanConstants
.
STATUS_APPROVED
,
query
.
getStatus
());
}
@Test
void
adminListShouldRejectInvalidStatusAndDateRange
()
{
TeachingPlanAdminQueryDTO
invalidStatus
=
new
TeachingPlanAdminQueryDTO
();
invalidStatus
.
setStatus
(
"unknown"
);
assertThrows
(
BusinessException
.
class
,
()
->
teachingPlanService
.
adminList
(
invalidStatus
));
TeachingPlanAdminQueryDTO
invalidDates
=
new
TeachingPlanAdminQueryDTO
();
invalidDates
.
setStartDate
(
new
Date
(
2_000L
));
invalidDates
.
setEndDate
(
new
Date
(
1_000L
));
assertThrows
(
BusinessException
.
class
,
()
->
teachingPlanService
.
adminList
(
invalidDates
));
verify
(
teachingPlanMapper
,
never
()).
selectAdminList
(
invalidDates
);
}
@Test
void
adminUpdateShouldAllowAnyTransitionAndWriteAuthenticatedReviewer
()
{
TeachingPlanEntity
approved
=
new
TeachingPlanEntity
();
approved
.
setId
(
"plan-1"
);
approved
.
setStatus
(
TeachingPlanConstants
.
STATUS_APPROVED
);
when
(
teachingPlanMapper
.
selectAdminPlanForUpdate
(
"plan-1"
)).
thenReturn
(
approved
);
when
(
teachingPlanMapper
.
updateAdmin
(
any
())).
thenReturn
(
1
);
when
(
teachingPlanMapper
.
selectAdminDetail
(
"plan-1"
)).
thenReturn
(
planVo
());
when
(
attachmentMapper
.
selectByPlanIds
(
anyList
())).
thenReturn
(
Collections
.
emptyList
());
TeachingPlanAdminUpdateDTO
request
=
validRequest
();
request
.
setStatus
(
"draft"
);
request
.
setReviewOpinion
(
" 退回草稿重新整理 "
);
teachingPlanService
.
adminUpdate
(
"plan-1"
,
request
,
"admin-1"
,
"教务管理员"
);
ArgumentCaptor
<
TeachingPlanEntity
>
captor
=
ArgumentCaptor
.
forClass
(
TeachingPlanEntity
.
class
);
verify
(
teachingPlanMapper
).
updateAdmin
(
captor
.
capture
());
TeachingPlanEntity
update
=
captor
.
getValue
();
assertEquals
(
TeachingPlanConstants
.
STATUS_DRAFT
,
update
.
getStatus
());
assertEquals
(
"admin-1"
,
update
.
getReviewerId
());
assertEquals
(
"教务管理员"
,
update
.
getReviewerName
());
assertEquals
(
"退回草稿重新整理"
,
update
.
getReviewOpinion
());
assertNotNull
(
update
.
getReviewTime
());
}
@Test
void
adminUpdateShouldRejectMissingPlanAndOversizedOpinion
()
{
TeachingPlanAdminUpdateDTO
missingPlanRequest
=
validRequest
();
missingPlanRequest
.
setStatus
(
TeachingPlanConstants
.
STATUS_APPROVED
);
when
(
teachingPlanMapper
.
selectAdminPlanForUpdate
(
"missing"
)).
thenReturn
(
null
);
assertThrows
(
BusinessException
.
class
,
()
->
teachingPlanService
.
adminUpdate
(
"missing"
,
missingPlanRequest
,
"admin-1"
,
"管理员"
));
TeachingPlanAdminUpdateDTO
oversized
=
validRequest
();
oversized
.
setStatus
(
TeachingPlanConstants
.
STATUS_REJECTED
);
oversized
.
setReviewOpinion
(
repeat
(
'评'
,
TeachingPlanConstants
.
MAX_REVIEW_OPINION_LENGTH
+
1
));
assertThrows
(
BusinessException
.
class
,
()
->
teachingPlanService
.
adminUpdate
(
"plan-1"
,
oversized
,
"admin-1"
,
"管理员"
));
verify
(
teachingPlanMapper
,
never
()).
updateAdmin
(
any
());
}
@Test
void
exportAdminListShouldCreateFilteredExcelWithExpectedHeaders
()
throws
Exception
{
TeachingPlanVO
plan
=
planVo
();
plan
.
setReviewerName
(
"教务管理员"
);
plan
.
setReviewOpinion
(
"内容完整"
);
when
(
teachingPlanMapper
.
selectAdminList
(
any
()))
.
thenReturn
(
Collections
.
singletonList
(
plan
));
MockHttpServletResponse
response
=
new
MockHttpServletResponse
();
TeachingPlanAdminQueryDTO
query
=
new
TeachingPlanAdminQueryDTO
();
query
.
setTeacherId
(
"teacher-1"
);
teachingPlanService
.
exportAdminList
(
query
,
response
);
assertTrue
(
response
.
getContentType
().
contains
(
"spreadsheetml.sheet"
));
assertTrue
(
response
.
getHeader
(
"Content-Disposition"
).
contains
(
".xlsx"
));
try
(
XSSFWorkbook
workbook
=
new
XSSFWorkbook
(
new
ByteArrayInputStream
(
response
.
getContentAsByteArray
())))
{
assertEquals
(
"教案ID"
,
workbook
.
getSheetAt
(
0
).
getRow
(
0
).
getCell
(
0
).
getStringCellValue
());
assertEquals
(
"plan-1"
,
workbook
.
getSheetAt
(
0
).
getRow
(
1
).
getCell
(
0
).
getStringCellValue
());
assertEquals
(
"高处作业安全教案"
,
workbook
.
getSheetAt
(
0
).
getRow
(
1
).
getCell
(
1
).
getStringCellValue
());
}
}
@Test
void
exportAdminDetailShouldCreateWordWithContentAndAttachmentNames
()
throws
Exception
{
TeachingPlanVO
plan
=
planVo
();
plan
.
setReviewerName
(
"教务管理员"
);
plan
.
setReviewOpinion
(
"审核通过"
);
when
(
teachingPlanMapper
.
selectAdminDetail
(
"plan-1"
)).
thenReturn
(
plan
);
TeachingPlanAttachmentVO
attachment
=
new
TeachingPlanAttachmentVO
();
attachment
.
setPlanId
(
"plan-1"
);
attachment
.
setFileName
(
"安全演示.pptx"
);
when
(
attachmentMapper
.
selectByPlanIds
(
anyList
()))
.
thenReturn
(
Collections
.
singletonList
(
attachment
));
MockHttpServletResponse
response
=
new
MockHttpServletResponse
();
teachingPlanService
.
exportAdminDetail
(
"plan-1"
,
response
);
assertTrue
(
response
.
getContentType
().
contains
(
"wordprocessingml.document"
));
assertTrue
(
response
.
getHeader
(
"Content-Disposition"
).
contains
(
".docx"
));
try
(
XWPFDocument
document
=
new
XWPFDocument
(
new
ByteArrayInputStream
(
response
.
getContentAsByteArray
())))
{
StringBuilder
text
=
new
StringBuilder
();
document
.
getParagraphs
().
forEach
(
paragraph
->
text
.
append
(
paragraph
.
getText
()));
document
.
getTables
().
forEach
(
table
->
text
.
append
(
table
.
getText
()));
assertTrue
(
text
.
toString
().
contains
(
"高处作业安全教案"
));
assertTrue
(
text
.
toString
().
contains
(
"审核通过"
));
assertTrue
(
text
.
toString
().
contains
(
"安全演示.pptx"
));
}
}
@Test
void
adminDetailShouldRejectMissingOrDeletedPlan
()
{
when
(
teachingPlanMapper
.
selectAdminDetail
(
"missing"
)).
thenReturn
(
null
);
assertThrows
(
BusinessException
.
class
,
()
->
teachingPlanService
.
adminDetail
(
"missing"
));
}
private
TeachingPlanAdminUpdateDTO
validRequest
()
{
TeachingPlanAdminUpdateDTO
request
=
new
TeachingPlanAdminUpdateDTO
();
request
.
setTitle
(
"高处作业安全教案"
);
request
.
setCourseName
(
"高处作业安全"
);
request
.
setTeachingDate
(
new
Date
());
request
.
setClassHours
(
2
);
request
.
setTeachingObjectives
(
"掌握高处作业基本安全要求"
);
request
.
setTeachingContent
(
"安全防护用品使用和风险识别"
);
request
.
setKeyPoints
(
"正确使用安全带"
);
request
.
setDifficultPoints
(
"复杂环境风险识别"
);
request
.
setTeachingMethods
(
"讲授、演示与案例讨论"
);
request
.
setTeachingProcess
(
"导入、讲授、演示、练习和总结"
);
request
.
setAfterClassSummary
(
"课堂目标已完成"
);
return
request
;
}
private
TeachingPlanVO
planVo
()
{
TeachingPlanVO
plan
=
new
TeachingPlanVO
();
plan
.
setId
(
"plan-1"
);
plan
.
setTeacherId
(
"teacher-1"
);
plan
.
setTeacherName
(
"王老师"
);
plan
.
setTitle
(
"高处作业安全教案"
);
plan
.
setCourseName
(
"高处作业安全"
);
plan
.
setTeachingDate
(
new
Date
());
plan
.
setClassHours
(
2
);
plan
.
setTeachingObjectives
(
"掌握安全要求"
);
plan
.
setTeachingContent
(
"安全防护用品使用"
);
plan
.
setKeyPoints
(
"正确使用安全带"
);
plan
.
setDifficultPoints
(
"风险识别"
);
plan
.
setTeachingMethods
(
"讲授与演示"
);
plan
.
setTeachingProcess
(
"导入、讲授和总结"
);
plan
.
setAfterClassSummary
(
"目标已完成"
);
plan
.
setStatus
(
TeachingPlanConstants
.
STATUS_APPROVED
);
plan
.
setUpdateTime
(
new
Date
());
return
plan
;
}
private
String
repeat
(
char
character
,
int
count
)
{
StringBuilder
builder
=
new
StringBuilder
(
count
);
for
(
int
i
=
0
;
i
<
count
;
i
++)
{
builder
.
append
(
character
);
}
return
builder
.
toString
();
}
}
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