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.
5.7 KiB
5.7 KiB
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-1-2_同步任务.md（u76/u88-u135/u230-u260/u270-u331）。
- 新表 dt_sync_task：任务编号（格式
SYNC-MMDD-序号）/触发方式（手动/自动）/执行状态/开始·结束时间/部门变更·人员变更·异常数计数/进度百分比/失败明细（失败对象·接口错误·处理结果，JSON 列）。 - 同步设置 dt_sync_settings（单例行即可）：自动同步启停/每日执行时间/重试规则（间隔≥1min、次数≥1）/并发规则/最近修改人·时间；「当前计划」「下次执行时间」为出参派生不落库。
- POST /sync/dingtalk 任务化：发起即建任务行、返回任务编号（执行可异步，进度与计数写任务行）。⚠️ 现契约返
DtSyncResultDTO计数——响应改型是本票显式拍板项（推荐：返回任务编号，计数改走 detail；已核实一期 demo/E2E 不调此接口，调用方仅文档示例）。 - POST /sync/tasks/page：筛选（任务编号/开始时间范围/触发方式/执行状态）+ 分页，时间倒序；列对齐原型（任务编号/开始时间/触发方式/执行状态/部门变更/人员变更/异常数）。（矩阵素材原文 GET，改为 POST 对齐全仓 page 惯例：users/roles/rule/*/log page 均 POST 带筛选 body；detail 类轻查询才走 GET）
- GET /sync/tasks/detail?id=：执行结果/失败对象/接口错误/处理结果/进度；「重新同步」前端复用发起端点，不另建。
- GET /sync/settings + POST /sync/settings：查询/保存（重试规则边界校验：间隔≥1min、次数≥1）。
- 自动同步调度：@Scheduled 参照 CustomerReminderJob 先例，按设置每日触发（触发方式=自动）；下次执行时间由设置推导。
- lastSyncTime 迁表：一期 Redis 暂存（key
crm:auth:sync:last-sync-time）改由任务表最新成功行推导，UserStatsDTO.lastSyncTime数据源切换；Redis 兼容读取过渡策略票内定（推荐直接切换，同步成功即有任务行）。 - tag/文档：新端点沿用「A7 后台管理/用户管理/同步任务」；bruno 文档新增 5 份（发起改造 1 + page/detail/settings 2 + 既有 dingtalk 示例改型）。
- 错误码接续 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 条目：独立接口多实现，不写死钉钉 |