diff --git a/changelogs-v2/2026-09/20_7539_团期出发推进定时任务1041启用与存量待出发团处置-修复-管理后台.md b/changelogs-v2/2026-09/20_7539_团期出发推进定时任务1041启用与存量待出发团处置-修复-管理后台.md new file mode 100644 index 00000000..44153bd4 --- /dev/null +++ b/changelogs-v2/2026-09/20_7539_团期出发推进定时任务1041启用与存量待出发团处置-修复-管理后台.md @@ -0,0 +1,89 @@ +--- +schema: "hl-changelog/v2" +ticket: "7539" +title: "团期出发推进定时任务 1041 已启用 + 存量待出发团处置(无接口变更)" +consumer: "admin" +author: "jw(GIT)" +change_type: "修复" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "2026-09-20" +status_note: "本单没有新增、修改、删除任何 HTTP 端点,请求/响应字段全部不变,change_type 取「修复」是按 17_7868 先例(校验器只允许 新增接口/修改接口/删除接口/修复/前端* 几类,接口三类要求逐端点模板而本单无端点可列)。本条是「定时任务已启用」的行为通告:团期状态从此会按天自动流转,前端看板/列表需要知道。gateway_status=verified 指本单的运维接口 POST /admin/job/1041/resume 与 GET /admin/job 经测试网关实测通过(工单 #7539 AC-6/AC-11,17/17 验收后于 2026-09-20 关单)。frontend_status=pending 是因为「出发门不过闸静默卡住」这条需要前端/运营侧配合做巡检展示,见第三节。" +updated_at: "2026-09-20" +base: "dev-v3" +--- + +# order-v3: 团期出发推进定时任务 1041 已启用 + 存量待出发团处置(无接口变更) + +> **服务**: hl-user-service(任务注册)/ hl-order-service-v3(实际推进逻辑) +> **PR**: 无(本单为运维处置单,不含代码变更) +> **Issue**: [#7539](https://git.1814.love:8443/wx/HL/issues/7539) +> **日期**: 2026-09-20 +> **影响范围**: 无对外接口变化;团期状态会按天自动流转,前端看板、团期列表、团期详情的状态取值分布会变 + +--- + +## ⚠️ 关键变化 + +- **本单没有任何可调用的新接口**:没有新增、修改、删除任何 HTTP 端点,请求/响应字段、枚举、路径全部不变。 +- **定时任务 1041「团期出发推进」已启用**(此前为 `PAUSED`)。从此每天 `00:10` 自动把**出发日 ≤ 当天**且通过七项出发门的 `PENDING_DEPARTURE` 团推进为 `TRAVELLING`,并写 `BATCH_DEPART` 时间线。 +- **1042「团期出行完毕」同样在跑**:每天 `00:20` 把**返团日 < 当天**的 `TRAVELLING` 团推进为 `TRIP_FINISHED`,写 `BATCH_TRIP_FINISH` 时间线。 +- **前端不需要改任何调用**,但要知道:同一个团的 `batchStatus` 现在会在无人操作的情况下跨天变化,任何「按状态缓存/固化」的前端逻辑需要复核。 + +--- + +## 一、行为说明 + +| 任务 | 时间 | 扫描条件 | 结果状态 | 时间线事件 | 操作人 | +|------|------|----------|----------|------------|--------| +| 1041 团期出发推进 | 每天 00:10 | `PENDING_DEPARTURE` 且出发日 ≤ 当天,且七项出发门全过 | `TRAVELLING` | `BATCH_DEPART` | `SYSTEM`(`operatorId` 为空) | +| 1042 团期出行完毕 | 每天 00:20 | `TRAVELLING` 且返团日 < 当天 | `TRIP_FINISHED` | `BATCH_TRIP_FINISH` | `SYSTEM`(`operatorId` 为空) | + +- 日期以**产品侧实时班期**为准,不是订单侧的下单快照——同一个团这两个日期可能不一致,判定跟产品侧走。 +- `1043` / `1044` 仍为 `PAUSED`,本单不启,不要把「团堆在 `TRAVELLING` 之后的环节」误判成本单回归。 +- 时间线里这两条事件的 `operatorType` 是 `SYSTEM`、`operatorId` 为空,前端展示操作人时需要兜底,不能直接拿 `operatorId` 去查管理员。 + +## 二、七项出发门(由 #7528 交付,本单只是把闸门后面的任务打开) + +`FORMED`(已成团)、`RESOURCE_READY`(资源就绪)、`MATERIAL_CONFIRMED`(物资已确认)、 +`SUB_ORDERS_CONFIRMED`(子订单已确认)、`TRAVELER_PROFILE`(出行人资料齐)、 +`CONTRACT_INSURANCE`(合同保险齐)、`PRIMARY_REPORTER`(已设主报账人)。 + +团期详情接口既有的 `departureGates` 字段会逐项返回 `passed`,**字段本身没变**,本单只是让它有了实际意义:不过闸的团不会被推进。 + +## 三、⚠️ 需要前端/运营配合的一点:不过闸是「静默卡住」 + +出发门不过时,1041 的处理是**静默跳过**——不抛错、不改状态、不发通知,只在团期时间线写一条 +`BATCH_DEPARTURE_BLOCKED`(`from`/`to` 都是 `PENDING_DEPARTURE`,`content` 写明是哪一门没过)。 +**没有任何人会被主动告知**,团会一直停在「待出发」。 + +临时办法(在有专门的告警/看板前): + +1. 定期调 `GET /v3/admin/order/group-batch?batchStatus=PENDING_DEPARTURE&pageNo=1&pageSize=100` 盘点; +2. 对出发日已过仍在列表里的团,调团期详情看 `departureGates` 里 `passed=false` 的那一项; +3. 或直接看该团的 `status-logs` 里最近一条 `BATCH_DEPARTURE_BLOCKED` 的 `content`。 + +建议前端在团期详情/看板对「出发日已过 + 状态仍为待出发」的团做一个显眼标记,把阻塞门直接显示出来。 + +## 四、存量处置结论 + +- 启用前的存量 `PENDING_DEPARTURE` 团清点结果为 **0 个**,因此没有发生任何流团/清退处置。 +- 2026-09-20 复核:全库 `PENDING_DEPARTURE` = 0、`TRAVELLING` = 0、`TRIP_FINISHED` = 1。 + +## 五、实测记录(TEST) + +- 出发门端到端:构造「恰好一项不满足(物资未确认)」的团,cron 跑过后该团**没有** `BATCH_DEPART`、状态仍为 `PENDING_DEPARTURE`,并写出当天的 `BATCH_DEPARTURE_BLOCKED`,`content` 恰是被破的那一门。 +- 正样本:`2100509904627191810` 于 `2026-09-18 00:10:00` 被 1041 推成 `TRAVELLING`,于 `2026-09-20 00:20:00` 被 1042 推成 `TRIP_FINISHED`,两条系统留痕齐全。 +- 任务注册:`GET /admin/job` 中 `jobId=1041` 为 `status=ACTIVE`、`cronExpression="0 10 0 * * ?"`、`invokeTarget=groupBatchLifecycleJob.processDepartures()`;`sys_job_log` 中 09-15 ~ 09-20 每天 `1041 00:10 SUCCESS`、`1042 00:20 SUCCESS`,无失败。 + +## 六、前端是否需要改动 + +| 项 | 结论 | +|----|------| +| 接口路径 / 入参 / 出参 | **不变**,无需改动 | +| 状态枚举 | **不变**(`PENDING_DEPARTURE` / `TRAVELLING` / `TRIP_FINISHED` 均为既有值) | +| 需要留意 | 状态会跨天自动变化;`SYSTEM` 操作人展示兜底;建议新增「卡在待出发」的巡检提示(第三节) |