docs(changelog): #7539 团期出发推进定时任务 1041 启用与存量待出发团处置（无接口变更）

Refs #7539
2026-09-20 09:29:21 +08:00
@@ -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` 操作人展示兜底；建议新增「卡在待出发」的巡检提示（第三节） |