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

## 1. 背景与目标

你已明确：
1. 不在现有 `SyncHand` 上继续加方法；
2. 直接新增独立的 controller、service 等；
3. 后续还会接入学员、课表、教室等，入参结构统一为：

```json
{
  "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. 验证记录与回归结果。