Section 同步改造后的调用链路

一、目标说明

本次改造将 section 同步从“controller 直接调用专用批处理 service”的方式，收敛为“controller + 公共编排 service + 业务处理器”的统一批量同步架构。

目标收益：

统一批次校验、分片、并发、错误归集和状态汇总逻辑
业务类只保留 section 专属的校验、映射和单分片下发逻辑
为后续 course/classroom 等同步类型复用同一套编排链路

二、改造后的主调用链

1. HTTP 入口

文件：ruoyi-server/ruoyi-server-sync/src/main/java/org/dromara/server/sync/controller/SyncReceiveController.java

入口方法：

syncSections(BatchSyncRequest<SectionRecordRequest> request)

职责：

接收 /api/sync/receive/sections 请求
设置 request.businessType = SyncResourceConstants.SECTION
调用 CommonBatchSyncService.sync(request)
返回 BatchSyncResult

2. 公共批量编排层

文件：ruoyi-server/ruoyi-server-sync/src/main/java/org/dromara/server/sync/business/batch/CommonBatchSyncService.java

主方法：

sync(BatchSyncRequest<T> request)

职责：

校验 request 和 records
根据 businessType 获取业务处理器
创建批次记录 SyncBatchTrackerService.start(...)
逐条校验并转换记录
收集校验失败错误
将有效记录按 100 条分片
单片串行执行，多片按每轮最多 5 片并发执行
聚合所有分片的成功数与错误明细
保存错误明细并结束批次
返回统一 BatchSyncResult

关键内部方法：

getHandler(...)：根据 businessType 获取处理器
partition(...)：按固定大小切分分片
executeChunks(...)：执行分片，同步或并发
buildResult(...)：构造最终返回结果
resolveStatus(...)：计算批次状态

3. 业务处理器抽象

文件：ruoyi-server/ruoyi-server-sync/src/main/java/org/dromara/server/sync/business/batch/BatchSyncBusinessHandler.java

作用：定义公共编排层与具体业务处理器之间的统一契约。

核心方法：

getBusinessType()
getApiName()
getResourceType()
resolveTenantId(...)
validateRecord(...)
getBizKey(...)
toDispatchDto(...)
dispatchChunk(...)

4. section 业务处理器

文件：ruoyi-server/ruoyi-server-sync/src/main/java/org/dromara/server/sync/business/batch/SectionBatchSyncService.java

注册方式：

@Service(SyncResourceConstants.SECTION)

实现接口：

BatchSyncBusinessHandler<SectionRecordRequest, RemoteSectionSyncBatchDto>

职责拆分：

validateRecord(...)
- 校验 section 单条记录的必填字段
getBizKey(...)
- 提取 sectionId 作为错误定位主键
toDispatchDto(...)
- 将请求对象转换为 RemoteSectionSyncBatchDto
dispatchChunk(...)
- 执行单个分片的远端 section 同步
- 解析远端返回结果
- 转换远端错误为本地 SyncBatchErrorRecord
syncSections(...)
- 兼容旧入口，内部委托给 CommonBatchSyncService

5. 远端 Dubbo 接口

接口文件：ruoyi-api/ruoyi-api-ecs/src/main/java/org/dromara/ecs/api/RemoteSectionSyncService.java

实现文件：ruoyi-modules/ruoyi-ecs/src/main/java/org/dromara/ecs/dubbo/RemoteSectionSyncServiceImpl.java

调用方法：

syncSectionBatch(List<RemoteSectionSyncBatchDto> records)

职责：

接收 server-sync 下发的 section 分片数据
转换为 ECS 内部 DTO
调用 ISyncSectionService.receiveSectionBatch(...)
返回远端批量处理结果 RemoteBatchSyncResultDto

6. ECS 内部同步服务

文件：ruoyi-modules/ruoyi-ecs/src/main/java/org/dromara/ecs/service/sync/SyncSectionServiceImpl.java

核心方法：

receiveSectionBatch(...)
processSection(...)

职责：

先处理 delFlag=1 的删除组
再处理 delFlag=0 的新增/修改组
单条处理时：
- 删除组：按 otherId 更新删除标记
- 非删除组：按 otherId 判断新增或修改

7. 持久化层

文件：

ruoyi-modules/ruoyi-ecs/src/main/java/org/dromara/ecs/service/impl/EcsSectionServiceImpl.java
ruoyi-modules/ruoyi-ecs/src/main/java/org/dromara/ecs/mapper/EcsSectionMapper.java

职责：

queryByOtherId(...)：查询已存在记录
insertByBo(...)：新增课表
updateByBo(...)：更新课表
updateDelFlagByOtherId(...)：按 otherId + tenantId 更新删除标记

三、改造后的完整执行时序

外部系统调用 /api/sync/receive/sections
SyncReceiveController.syncSections(...)
设置 businessType = SECTION
CommonBatchSyncService.sync(...)
SpringUtils.getBean("SECTION", BatchSyncBusinessHandler.class) 获取 SectionBatchSyncService
SyncBatchTrackerService.start(...) 创建批次
公共层逐条校验 section 数据并转换为 RemoteSectionSyncBatchDto
公共层按 100 条切分分片
单分片同步执行；多分片每轮最多 5 片并发执行
每个分片调用 SectionBatchSyncService.dispatchChunk(...)
dispatchChunk(...) 调用 RemoteSectionSyncService.syncSectionBatch(...)
RemoteSectionSyncServiceImpl.syncSectionBatch(...) 转内部 DTO 后调用 SyncSectionServiceImpl.receiveSectionBatch(...)
ECS 内部完成删除/新增/修改处理
分片结果返回到公共层
公共层聚合 success/error
SyncBatchTrackerService.saveErrors(...) 保存错误明细
SyncBatchTrackerService.finish(...) 更新批次状态
controller 返回 BatchSyncResult

四、当前分片与并发规则

在 CommonBatchSyncService 中约定：

CHUNK_SIZE = 100
MAX_PARALLEL_CHUNKS = 5

执行规则：

只有 1 个分片：当前线程同步执行
多于 1 个分片：按窗口执行，每轮最多并发 5 个分片
并发线程池复用 threadPoolTaskExecutor

五、错误归集规则

错误来源分两类：

1. 校验失败

发生位置：公共编排层

处理方式：

不进入远端调用
直接通过 SyncBatchTrackerService.error(...) 构造 VALIDATION_ERROR

2. 业务失败 / 远端失败

发生位置：section 分片处理器或远端服务