You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
49 lines
5.7 KiB
49 lines
5.7 KiB
5 hours ago
|
# 01 同步任务模块化（A7-1-2，crm-auth）
|
||
|
|
|
||
|
|
Type: task
|
||
|
|
Status: resolved
|
||
|
|
|
||
|
|
## Question
|
||
|
|
|
||
|
|
把 `POST /api/system/sync/dingtalk` 从阻塞式同步改造为任务化，补齐原型 A7-1-2 同步任务页 5 端点与定时调度。素材：[matrix-a7-1-a7-2.md](../../a7-parity/matrix-a7-1-a7-2.md) §二 + 文本库 `A7-1-2_同步任务.md`（u76/u88-u135/u230-u260/u270-u331）。
|
||
|
|
|
||
|
|
1. **新表 dt_sync_task**：任务编号（格式 `SYNC-MMDD-序号`）/触发方式（手动/自动）/执行状态/开始·结束时间/部门变更·人员变更·异常数计数/进度百分比/失败明细（失败对象·接口错误·处理结果，JSON 列）。
|
||
|
|
2. **同步设置 dt_sync_settings**（单例行即可）：自动同步启停/每日执行时间/重试规则（间隔≥1min、次数≥1）/并发规则/最近修改人·时间；「当前计划」「下次执行时间」为出参派生不落库。
|
||
|
|
3. **POST /sync/dingtalk 任务化**：发起即建任务行、返回任务编号（执行可异步，进度与计数写任务行）。⚠️ 现契约返 `DtSyncResultDTO` 计数——响应改型是本票显式拍板项（推荐：返回任务编号，计数改走 detail；已核实一期 demo/E2E 不调此接口，调用方仅文档示例）。
|
||
|
|
4. **POST /sync/tasks/page**：筛选（任务编号/开始时间范围/触发方式/执行状态）+ 分页，时间倒序；列对齐原型（任务编号/开始时间/触发方式/执行状态/部门变更/人员变更/异常数）。（矩阵素材原文 GET，改为 POST 对齐全仓 page 惯例：users/roles/rule/*/log page 均 POST 带筛选 body；detail 类轻查询才走 GET）
|
||
|
|
5. **GET /sync/tasks/detail?id=**：执行结果/失败对象/接口错误/处理结果/进度；「重新同步」前端复用发起端点，不另建。
|
||
|
|
6. **GET /sync/settings + POST /sync/settings**：查询/保存（重试规则边界校验：间隔≥1min、次数≥1）。
|
||
|
|
7. **自动同步调度**：@Scheduled 参照 CustomerReminderJob 先例，按设置每日触发（触发方式=自动）；下次执行时间由设置推导。
|
||
|
|
8. **lastSyncTime 迁表**：一期 Redis 暂存（key `crm:auth:sync:last-sync-time`）改由任务表最新成功行推导，`UserStatsDTO.lastSyncTime` 数据源切换；Redis 兼容读取过渡策略票内定（推荐直接切换，同步成功即有任务行）。
|
||
|
|
9. **tag/文档**：新端点沿用「A7 后台管理/用户管理/同步任务」；bruno 文档新增 5 份（发起改造 1 + page/detail/settings 2 + 既有 dingtalk 示例改型）。
|
||
|
|
10. 错误码接续 61022+；权限种子 @Order(25)（同步任务菜单；票 02 用 26，两票并行不撞号）。
|
||
|
|
|
||
|
|
验收基线：编译过 + BOM 0 + crm-auth 单测全绿（含 dingtalk 任务化回归 + 设置边界校验行为测试）。
|
||
|
|
|
||
|
|
## Answer
|
||
|
|
|
||
|
|
2026-09-08 落地（resolved）。10 项需求全部实现，验收基线全过：`mvn test -pl crm-auth -am` 全量单测 EXIT=0、BOM 扫描 0、编译过。
|
||
|
|
|
||
|
|
**实现清单**
|
||
|
|
|
||
|
|
- 表/实体：`dt_sync_task`（任务编号 `SYNC-MMdd-序号`/触发方式/执行状态/起止时间/部门·人员·异常三计数/进度/失败明细 JSON）+ `dt_sync_settings` 单例行（启停/每日执行时间/重试间隔·次数/并发/最近修改人·时间）。
|
||
|
|
- 端点 5 个（`SyncTaskController`，全 ADMIN，深 tag「A7 后台管理/用户管理/同步任务」）：POST /sync/dingtalk（任务化）、POST /sync/tasks/page、GET /sync/tasks/detail?id=、GET /sync/settings、POST /sync/settings。
|
||
|
|
- 服务：`DtSyncTaskServiceImpl`（launch 并发占位→61023、单线程 daemon 池 dt-sync-task 异步执行、进度 5/45/90/100、settings 边界校验→61022、page 默认 startTime 倒序）+ `DtSyncScheduleJob`（@Scheduled 每分钟心跳，由 dt_sync_settings 派生判定发起，触发方式=auto）。
|
||
|
|
- **组织拉取 SPI（执行中用户新增拍板）**：`OrgSourcePort` 接口（fetchDepartments/fetchDeptUsers + 嵌套 Dept/User 值对象）+ `DingTalkOrgSource` 实现（SDK/HTTP/token 失效重试/解析/限流全迁入，DtErrorException 翻译为业务异常）+ 装配缝 `crm.auth.org-source`（缺省 dingtalk；后续接企微/自有 OA 新增实现类标注 @ConditionalOnProperty 即可）；编排层 `DtOrgSyncServiceImpl` 平台无关化、零 SDK 依赖。
|
||
|
|
- lastSyncTime：`UserStatsDTO.lastSyncTime` 改由 dt_sync_task 最新成功行 endTime 推导。
|
||
|
|
- 错误码 61022 同步设置参数非法 / 61023 已有同步任务运行中 / 61024 同步任务不存在（README 已登记）；权限种子同步任务菜单 @Order(25)。
|
||
|
|
- 测试：`DtSyncTaskServiceH2Test`（11 用例）/ `DtOrgSyncServiceImplTest`（5 用例）/ `DingTalkOrgSourceTest`（4 用例）。
|
||
|
|
- bruno 文档 5 份 → 文档仓 `A7 后台管理/用户管理/同步任务/`（钉钉组织同步改型 / 同步任务分页 / 同步任务详情 / 读取同步设置 / 保存同步设置）。
|
||
|
|
|
||
|
|
**拍板项实际取舍与偏差**
|
||
|
|
|
||
|
|
| 票面 | 实际 |
|
||
|
|
| --- | --- |
|
||
|
|
| ③ 返任务编号，计数改走 detail | 采纳并加强：返 `DtSyncLaunchDTO{taskId, taskNo}` 两者都给（前端轮询 detail 用 id） |
|
||
|
|
| ④ tasks/page 改 POST | 已落实（表单绑定筛选，ADR-0017） |
|
||
|
|
| ⑧ lastSyncTime 直接切换 | 采纳；Redis 兼容读取未保留（一期无存量调用方，同步成功即有任务行） |
|
||
|
|
| 进度「已处理/总数」逐条粒度 | 未做，阶段粒度 5/45/90/100（listener 回报 45/90）；原型无逐条强诉求 |
|
||
|
|
| partial_failed 状态 | 枚举保留对齐原型文案；一期同步粒度失败即整体 all_failed，不产生该状态 |
|
||
|
|
| 重试规则 | 仅落设置 + 边界校验（61022），自动重试执行未实现（票面 2/6 项未显式要求执行行为） |
|
||
|
|
| 组织拉取解耦（用户新增拍板） | 见实现清单 SPI 条目：独立接口多实现，不写死钉钉 |
|