ykt_server_hnswdx/doc/2026-04-27-班级同步新入参适配实现计划.md

统一 records 批量同步体系实现计划（不改 SyncHand、不改策略层）

1. 背景与目标

你已明确：

1. 不在现有 SyncHand 上继续加方法；
2. 直接新增独立的 controller、service 等；

3. 后续还会接入学员、课表、教室等，入参结构统一为：

   {
   "records": [
   {
     "业务对象字段": "..."
   }
   ]
   }
   

本方案目标：

• 新建一套“统一 records 批量同步入口体系”；
• 先落地培训班级场景；
• 为学员/课表/教室预留同构扩展位；
• 保持策略层不改（ISyncDeptStrategy / TrainClassStrategyImpl 等现有策略实现不调整）。

---

2. 设计原则

1. 隔离旧链路：SyncHand 与历史全量接口保持原样，避免影响现网。
2. 统一请求壳：所有新同步接口统一 records 批量模型。
3. 业务分层清晰：
   • Controller：接收请求与基础校验；
   • Application Service（新增）：分流、编排；
   • Adapter/Mapper（新增）：DTO -> 领域对象（如 ResourceDept）；
   • Strategy（复用）：落库与远程副作用。
4. 先复用后扩展：优先复用现有策略与常量，避免重复实现。

---

3. 总体架构（新增）

新增一条并行链路（与 SyncHand 并存）：

BatchSyncController
-> TrainBatchSyncService（培训班级）
-> TrainClassRecordMapper（records -> ResourceDept）
-> 复用策略 ISyncDeptStrategy(TRAIN_CLASS)
-> syncDept(...) / syncDelDept(...)

未来扩展：

• TraineeBatchSyncService
• CourseBatchSyncService
• ClassroomBatchSyncService

它们共享同一 BatchSyncRequest<T> 请求壳与统一处理约定。

---

4. 需新增内容清单

4.1 Controller（新增，不改 SyncHand）

建议新增文件：

• ruoyi-server/ruoyi-server-sync/src/main/java/org/dromara/server/sync/controller/BatchSyncController.java

建议路由：

• POST /batch-sync/train/class
• 未来可扩展：
  • POST /batch-sync/train/trainee
  • POST /batch-sync/train/course
  • POST /batch-sync/train/classroom

职责：

• 接收 BatchSyncRequest<TrainClassRecordRequest>；
• 调用对应 service；
• 返回 R<Void> 或后续统一结果对象。

4.2 请求模型（新增）

建议新增：

1. BatchSyncRequest<T>：统一壳，字段 List<T> records
2. TrainClassRecordRequest：培训班级记录 DTO

培训班级字段：

• classId
• className
• year
• senester（兼容你给的外部字段拼写）
• checkinTime
• startTime
• endTime
• studentNum
• headTeacherName
• delFlag
• tenantId

说明：

• headTeacherName 当前策略链未使用，先保留在请求层。

4.3 Service（新增应用服务）

建议新增文件：

• ruoyi-server/ruoyi-server-sync/src/main/java/org/dromara/server/sync/business/batch/TrainBatchSyncService.java

职责：

1. 校验批次与记录；
2. DTO 转 ResourceDept；
3. 按 delFlag 分流：
   • 删除集合 -> syncDelDept(...)
   • 新增/更新集合 -> syncDept(...)
4. 记录处理统计日志（总数、成功分流数、删除数、映射失败数）。

4.4 记录映射器（新增）

建议新增文件：

• ruoyi-server/ruoyi-server-sync/src/main/java/org/dromara/server/sync/business/batch/mapper/TrainClassRecordMapper.java

职责：

• 将 TrainClassRecordRequest 映射为 ResourceDept，复用现有策略所需字段结构。

字段映射（与现有策略兼容）：

• classId -> dept_id
• className -> dept_name
• year -> year(Integer)
• senester(1/2) -> semester(上学期/下学期)
• checkinTime -> checkDate + payBegin
• startTime -> beginDate
• endTime -> endDate + payEnd
• studentNum -> planCount（为空设默认值，防止 planCount.longValue() NPE）
• tenantId -> tenantId（为空回退默认租户）
• 固定值：chooseRoom=0,canEat=1,operatorId=FULL_SYNC_ADMIN

---

5. 兼容与扩展策略

5.1 与现有系统兼容

1. SyncHand 不改。
2. 现有 SyncTrainService.syncTrainClass() 不改。
3. 现有策略层不改。
4. 新旧接口可并行使用。

5.2 面向未来扩展

后续新增学员/课表/教室时，仅需：

1. 新增对应 RecordRequest DTO；
2. 新增对应 *BatchSyncService；
3. 新增对应 mapper（转换为现有策略入参对象）；
4. 在 BatchSyncController 增加一个路由方法。

统一约束：

• 全部使用 BatchSyncRequest<T>.records。
• 都采用“分流 + 复用策略层”的执行模型。

---

6. 校验与错误处理约定

入口/服务层最小校验：

1. records 非空；
2. 必填字段非空（classId/className/year/senester/checkinTime/startTime/endTime）；
3. senester 仅允许 1/2；
4. 时间格式统一（建议 yyyy-MM-dd HH:mm:ss，兼容日期字符串）；
5. studentNum 为空时默认 100。

错误处理：

• 记录级映射失败：记日志并计数；
• 策略执行异常：抛 ServiceException；
• 返回层先维持 R<Void>，后续可扩展批次结果对象。

---

7. 实施步骤（合并更新版）

1. 新增统一请求壳 BatchSyncRequest<T>。
2. 新增培训班级 DTO：TrainClassRecordRequest。
3. 新增 BatchSyncController 与 POST /batch-sync/train/class。
4. 新增 TrainBatchSyncService。
5. 新增 TrainClassRecordMapper 并完成字段映射。
6. 在 service 内实现 delFlag 分流并复用策略层调用。
7. 增加统计日志与异常日志。
8. 联调验证新增/更新/删除与混合批次。
9. 回归验证旧接口（SyncHand）完全不受影响。

---

8. 验证计划

8.1 功能验证

1. delFlag=0：验证 sys_dept 新增/更新 + 团客新增/更新。
2. delFlag=1：验证 sys_dept 删除 + 团客删除。
3. 混合批次：验证分流正确。

8.2 异常验证

1. 必填字段缺失。
2. senester 值非法。
3. 时间格式异常。
4. studentNum 为空默认值生效。
5. tenantId 缺失时默认租户生效。

8.3 回归验证

1. GET /hand/sync/train/class 行为不变。
2. 原策略层行为不变（年份/学期/班级层级、团客同步逻辑不变）。

---

9. 风险与注意事项

1. 策略层当前是“记录级失败日志，不一定导致批次失败”，会存在“接口成功但部分失败”。
2. headTeacherName 暂无落库目标字段，本期仅接收保留。
3. 外部字段 senester 拼写建议在 DTO 层做兼容映射，内部命名可标准化。
4. 分流执行顺序建议固定（先删后增改或先增改后删），并在文档中明确，避免同 classId 混合批次歧义。

---

10. 交付物

1. 新增独立批量同步入口（controller）。
2. 新增培训班级批量同步 service 与 mapper。
3. 新增统一 records 请求壳与班级 DTO。
4. 在不改 SyncHand、不改策略层前提下实现等效业务闭环。
5. 验证记录与回归结果。