接入医科大开放平台数据同步

新增 com.gxwebsoft.gxmu.openplat:开放平台客户端(oauth 鉴权、token 缓存与失效
重取、分页拉取)、部门/教师/班级/学生四段同步、异步编排与手动同步接口、学生认领、
学生名册查询与导出、每天 03:30 的定时任务、同步记录。

关键设计:
- 名册与登录账号分离,学生通过「认领」(手机号自动 / 学号姓名自助)关联 sys_user
- 组织数据以 sys_organization 为唯一载体,gxmu_college 废弃
- 平台无可用增量字段,只做全量拉取 + 幂等 upsert
- 上游消失只停用不删除,且只作用于同步来源的记录(避免误停用人工维护的研究生班)
- 平台权威字段按白名单覆盖,人工字段不触碰
- 码表可配置并保留原始码,码值实测存在两套编码混用,不做硬编码
- 手动同步为异步:提交返回批次号,前端轮询 /status 看分段进度

性能:
- 班级/部门由逐条 update 改为多行 upsert,班级 1584 条 41s -> 0.19s
- 码表解析加进程内缓存,学生同步由 >17 分钟不完成 -> 170 秒完成 98187 行

迁移脚本需手动执行(可重复执行):
  sql/20260912_create_openplat_sync_tables.sql
  sql/20260912_add_openplat_menu.sql

离线单测 43 个;另有联网集成测试 OpenPlatformClientIT(需 -Dopenplat.it=true)。
This commit is contained in:
2026-09-15 15:54:49 +08:00
parent f379291e4f
commit cd54039f28
51 changed files with 4586 additions and 3 deletions
@@ -2,9 +2,28 @@ package com.gxwebsoft.gxmu.mapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.gxwebsoft.gxmu.entity.ClassInfo;
import org.apache.ibatis.annotations.Param;
import java.util.List;
/**
* 班级管理Mapper
*/
public interface ClassInfoMapper extends BaseMapper<ClassInfo> {
/**
* 批量新增或更新(开放平台班级同步用)。
*
* <p>幂等键为 {@code uk_gxmu_class_code(tenant_id, class_code)};
* 只覆盖平台权威字段,人工维护的 sort_number / counselor_phone / create_time 不动,
* 见 docs/adr/0005。
*
* <p>用一条多行语句代替逐条 save/update:实测公网数据库单条往返 25ms,
* 1584 条逐条发要 41 秒,多行 upsert 只要 0.2 秒。
*
* @param list 班级列表
* @return 影响行数
*/
int batchUpsert(@Param("list") List<ClassInfo> list);
}
@@ -0,0 +1,37 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.gxwebsoft.gxmu.mapper.ClassInfoMapper">
<!--
开放平台班级同步的批量写入。
ON DUPLICATE KEY UPDATE 里只列「平台权威字段」(docs/adr/0005):
sort_number / counselor_phone 属人工维护,同步不触碰;create_time 不重复刷新。
幂等键是 uk_gxmu_class_code(tenant_id, class_code)。
-->
<insert id="batchUpsert">
INSERT INTO gxmu_class (
college_id, class_code, class_name, grade_year, counselor_name, counselor_phone,
student_count, sort_number, status, remark, tenant_id,
create_time, update_time, deleted
) VALUES
<foreach collection="list" item="item" separator=",">
(
#{item.collegeId}, #{item.classCode}, #{item.className}, #{item.gradeYear},
#{item.counselorName}, #{item.counselorPhone}, #{item.studentCount},
#{item.sortNumber}, #{item.status}, #{item.remark}, #{item.tenantId},
#{item.createTime}, #{item.updateTime}, #{item.deleted}
)
</foreach>
ON DUPLICATE KEY UPDATE
class_name = VALUES(class_name),
college_id = VALUES(college_id),
grade_year = VALUES(grade_year),
counselor_name = VALUES(counselor_name),
student_count = VALUES(student_count),
status = VALUES(status),
remark = VALUES(remark),
update_time = VALUES(update_time),
deleted = VALUES(deleted)
</insert>
</mapper>