API Changelog Bot和Claude Opus 5
798b7bcd83
changelog-filename-gate / validate (push) Failing after 2s
原文「若该派单同时参与两条共用关系，两条都会受影响」是源码推演，本次补 2026-09-22 自建班期下的双维度活体读数（两条关系同刻 RELEASED/AUTO_SINGLE_MEMBER、4 条成员行 同刻 left_at、未被软清那条派车行完全未动）。 新增一节写明机制：onClaimReleased 只接单个资源维度、方法体内无跨维度查询， 「两条同时 RELEASED」的成因是同一个动作释放了两个维度的占用，不是维度间有传导。 该区别对前端的实际后果落在手工解除关系上——是否连带另一维度取决于释放集算法， 前端别预测，操作后两个维度都重新拉取。 Refs #8064 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
176 行
14 KiB
Markdown
176 行
14 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "8064"
|
||
title: "fleet: 共用关系成员失去占用后，关系现在会自动收缩（行为变更，无接口契约变化）"
|
||
consumer: "admin"
|
||
author: "wx(GIT)"
|
||
change_type: "修复"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "not_required"
|
||
frontend_owner: ""
|
||
frontend_ref: ""
|
||
target_release: ""
|
||
verified_at: ""
|
||
status_note: "本条无任何接口出入参或错误码变化，变的是同一请求的副作用：共用关系现在会在成员失去占用时自动收缩、剩余不足 2 人时自动解除。gateway_status=verified 的依据是 2026-09-21 经网关 https://api.test.1814.love:9443 的真实调用（建关系 + 两次 soft-clear-assignment），调用流水与库内终态逐条对照一致，不是只看部署登记。本条会让共用关系『自己消失』，前端是否需要改代码取决于两点：有没有缓存 activeShareGroupId、有没有「关系只能人工解除」的假设。这两点后端查证不了，已由前端侧自查确认（见下文 mmg 的实证）。⚠️ 存量收敛已于 2026-09-21 执行完毕（AC-5）：经应用路径点名收敛，摘除成员行 10 条、整体释放关系 4 条；另有 2 条关系在摘除成员后仍保持 ACTIVE——那是正确终态，收缩规则是「剩余成员 < 2 时才整体释放」，这 2 条原各 3 名成员、摘 1 名后仍剩 2 名。本轮为点名执行而非全库扫，名单外可能仍存在同类历史数据，前端展示逻辑该兜的仍要兜。前端实证 not_required(mmg 2026-09-21):按「四、前端要做什么」逐项自查——activeShareGroupId/shareGroup/share-groups/shareEligible 前端 src 全仓零命中(共用关系属 #7444 未接入挂起域,同 #8051/#8061 实证口径),前端无任何共用关系状态缓存、无「关系只能人工解除」的假设;未来接入时均为操作后实时拉取,自动收缩不产生前端脏读。"
|
||
updated_at: "2026-09-22"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# fleet: 共用关系成员失去占用后，关系现在会自动收缩（行为变更，无接口契约变化）
|
||
|
||
> **存放目录**: 二期（fleet 车务）→ `changelogs-v2/2026-09/`
|
||
|
||
## ⚠️ 关键变化
|
||
|
||
**接口契约零变化**——没有新增/修改/删除任何端点，没有新增/修改任何请求或响应字段，没有新增任何错误码。
|
||
|
||
**变的是同一个请求的副作用。** 从本次修复上线起：
|
||
|
||
1. 共用关系的某个成员因任何一条**真实的占用释放路径**失去对该车/该司机的占用时，该成员会被**自动移出**关系（成员行落 `left_at`，`leave_reason = AUTO_OCCUPANCY_RELEASE`）；
|
||
2. 移出后**剩余成员不足 2 个**时，整条关系**自动解除**（`status = RELEASED`，`release_reason = AUTO_SINGLE_MEMBER`，`active_share_group_id` 置空）。
|
||
|
||
🔴 **这两件事在本次修复之前，在当前部署形态下一次都没有发生过**（不是"偶尔没触发"，是整条代码路径执行不到，见"一、背景"）。所以对前端而言，这是一个**从未出现过的新现象**，不是一个已有现象的修正。
|
||
|
||
## 一、背景
|
||
|
||
### 缺陷形态
|
||
|
||
自动收缩的唯一入口是 `GroupDispatchShareOccupancyRefService.onClaimReleased(...)`，全仓唯一调用点在 `OccupancyDualWriteCoordinator.notifyShareGroupOfRelease(...)`；后者只在 `releaseCurrent(...)` 内被调，`releaseCurrent` 只在 `synchronizeOne(...)` 内被调，而 `synchronize()` 的**第一条语句**是：
|
||
|
||
```java
|
||
if (!context.dualWrite()) {
|
||
return;
|
||
}
|
||
```
|
||
|
||
而占用账本的灰度形态（`fleet_occupancy_rollout_fence`，64 条分片）在测试环境与生产环境**全部为 `LEGACY`**，并已于工单 #7972 定案**维持不切**（理由：回填完成前切换会让新账本少记占用，属于"用一个偏松的判据替掉现状"）。
|
||
|
||
⇒ **在 `LEGACY` 形态下，`synchronizeOne` / `releaseCurrent` / `notifyShareGroupOfRelease` / `onClaimReleased` 整条链路一行都执行不到。**
|
||
|
||
### 这个判断是怎么坐实的
|
||
|
||
不是靠读代码推断，是靠一个**在"修好了"和"没修"两个世界里取值不同**的读数：
|
||
|
||
| 读数 | 修复前 | 修复后 |
|
||
|---|---|---|
|
||
| 全库 `fleet_group_dispatch_share_group.release_reason = 'AUTO_SINGLE_MEMBER'` 计数 | **0** | **1** |
|
||
| 全库 `fleet_group_dispatch_share_log` 中 `reason = 'AUTO_SINGLE_MEMBER'` | **无** | 有 |
|
||
|
||
⚠️ **一个容易读错的邻近读数**（写在这里免得下一个人重复踩）：成员行的 `leave_reason = 'AUTO_OCCUPANCY_RELEASE'` 修复前**并不是 0，而是 28**——但那 28 条**全部来自手工解除路径**（24 条属 `MANUAL`、4 条属 `CLEAR_ALL`），因为手工解除与自动收缩**复用了同一个成员级原因值**。⇒ **按成员行的 `leave_reason` 计数衡量自动收缩活跃度会错 86%**，必须 join 到所属关系的 `release_reason` 才能分辨。
|
||
|
||
### 修复
|
||
|
||
- PR **#8073**（`c07942035`）：把 LEGACY 形态下的收缩动作挂到 `dualWrite` 闸门**之前**，使其在不切换账本形态的前提下真正执行。
|
||
- PR **#8077**（`3a92cafbf`）：整团解除时，审计用的关系解除原因**不被自动收缩夺走**（走豁免，而不是调整执行顺序）——即"整团解除"仍记为整团解除，不会被改写成 `AUTO_SINGLE_MEMBER`。
|
||
|
||
## 二、变更接口清单（无）
|
||
|
||
本条**不新增、不修改、不删除**任何 HTTP 接口，也不改动任何请求/响应字段与错误码。
|
||
|
||
下列既有端点的**行为副作用**受影响（契约不变）：
|
||
|
||
| METHOD | Path | 变化 |
|
||
|---|---|---|
|
||
| POST | `/admin/fleet/assignments/{assignmentId}/soft-clear-assignment` | 若该派单是某 active 共用关系的成员，调用后该成员被自动移出；剩余 < 2 人时关系自动解除 |
|
||
| POST | `/admin/fleet/assignments/{assignmentId}/driver-reject` | 同上 |
|
||
| POST | `/admin/fleet/assignments/{assignmentId}/change`（改派替换） | 同上 |
|
||
| POST | `/admin/fleet/assignments/{assignmentId}/complete`（完结） | 同上 |
|
||
| DELETE | `/admin/fleet/assignments/{assignmentId}`（取消） | **仅**当被取消的行在取消前处于 `unassigned` 时才进入释放集，见下方"三、边界行为" |
|
||
|
||
## 三、边界行为（这一节比上面的清单更重要）
|
||
|
||
### ⛔ 取消派单**通常不会**触发收缩
|
||
|
||
`DELETE /admin/fleet/assignments/{assignmentId}` 对**在途**的派车行落的是 `exception` 而**不是** `canceled`，而按工单 **#6152** 的定案，`exception` **保留占用**。只有"取消前已是 `unassigned`"的那部分行会落 `canceled` 并进入释放集。
|
||
|
||
⇒ **前端不要把"取消派单"当成"会解除共用关系"的动作。** 车务若想解除关系，正确动作是显式调解除接口，或使用软清。
|
||
|
||
### 会触发收缩的五条路径
|
||
|
||
软清 / 司机拒接 / 改派替换 / 完结 / 取消中落 `canceled` 的那一子集。它们在后端收敛到同一个写口，因此行为一致。
|
||
|
||
### 软清清的是整行，不是单一维度
|
||
|
||
软清会把该派车行的**车与司机一起清空**（车辆 id / 车牌 / 车型 / 司机 id / 姓名 / 电话全部置空，并把当日车辆用量归零）。⇒ 若该派单同时参与了 VEHICLE 维度与 DRIVER 维度的两条共用关系，**两条都会受影响**，不是只动一条。
|
||
|
||
**2026-09-22 双维度活体实测坐实**（此前这一段是源码推演，现补实测）：自建班期下造 2 条派单共用**同一辆车 + 同一个司机**，于是 VEHICLE 与 DRIVER 各成一条 2 人共用关系；软清其中一条派单后，两条关系**各自独立**收缩，**同时**转 `RELEASED`：
|
||
|
||
| 维度 | 关系状态 | `release_reason` | `released_at` |
|
||
|---|---|---|---|
|
||
| VEHICLE | `RELEASED` | `AUTO_SINGLE_MEMBER` | `2026-09-21 16:32:26` |
|
||
| DRIVER | `RELEASED` | `AUTO_SINGLE_MEMBER` | `2026-09-21 16:32:26` |
|
||
|
||
两条关系下的**全部 4 条成员行**（含**未被软清**的那一户在两条关系里的成员行）都落 `left_at = 2026-09-21 16:32:26`、`leave_reason = AUTO_OCCUPANCY_RELEASE`；未被软清那条派单的派车行本身**完全未动**（车、司机、状态原样）。
|
||
|
||
⇒ **前端含义**：一次软清会让该派单参与的**每一个**维度的关系消失。若界面按维度分别渲染共用关系，操作后**两块都要重新拉取**，不能只刷新其中一块。
|
||
|
||
### 机制是「每个维度各自收缩」，不是「一个维度带动另一个」
|
||
|
||
自动收缩的触发口是**占用被释放**：`GroupDispatchShareOccupancyRefService#onClaimReleased` 按 `(服务日, 资源维度, 资源 ID, 来源)` 判定，只接**单个**资源维度，方法体内没有任何跨维度查询；上游 `OccupancyDualWriteCoordinator#notifyShareGroupOfRelease` 按**单条**占用行取它自己的维度调一次。⇒ 上一节看到的「两条同时 RELEASED」，成因是**同一个动作释放了两个维度的占用**（软清清整行），钩子因此被各调了一次，**不是**维度之间有传导。
|
||
|
||
这个区别对前端有实际后果，体现在**手工解除关系**上：
|
||
|
||
- 调解除接口解除 VEHICLE 维度的关系时，后端按释放集算法决定哪些成员的占用真被释放（被释放的那些会走软清 ⇒ 它们在 DRIVER 维度的关系也随之收缩），**留任的成员占用不变**⇒ 它们在 DRIVER 维度的关系**原样保留**。
|
||
- ⇒ **别预测**「解除一个维度会不会连带另一个」——它取决于这次解除把谁判进了释放集。**操作后两个维度都重新拉取**是唯一可靠的做法。
|
||
|
||
### 整团解除不会被改写成自动收缩
|
||
|
||
整团解除时，关系的 `release_reason` 仍记录整团解除的原因，不会被自动收缩改写成 `AUTO_SINGLE_MEMBER`（PR #8077）。审计与对账按 `release_reason` 区分来源时，这一点是可靠的。
|
||
|
||
## 四、前端要做什么
|
||
|
||
**需要确认的一件事**：贵侧是否在任何地方**缓存**了共用关系状态（`activeShareGroupId`、关系成员列表、"该派单属于某共用关系"这一标志），或是否在代码/交互里假设了「**共用关系只能由人工显式解除**」。
|
||
|
||
- 若有 ⇒ 该假设**已不再成立**，关系会在上述释放类操作之后"自己消失"，需要改为操作后重新拉取。
|
||
- 若无（每次都实时拉取）⇒ 前端零改动，请把 `frontend_status` 改为 `not_required` 并说明依据。
|
||
|
||
⚠️ 我**没有**替贵侧填 `not_required`：那是一个关于前端代码的事实，后端查证不了。**这个位由看得见前端代码的人来定。**
|
||
|
||
## 五、测试环境已验证
|
||
|
||
**部署**：fleet 测试服部署点 `51571c58a`；`git merge-base --is-ancestor c07942035 51571c58a` 与 `3a92cafbf` **均为真**；Nacos 两实例 `healthy = true`。
|
||
**形态**：`fleet_occupancy_rollout_fence` 维持 `LEGACY`（**未改任何配置、未翻闸门**——在 DUAL_WRITE 下绿不能证明本缺陷修好了，那正是它的藏身处）。
|
||
**网关**：全部调用经 `https://api.test.1814.love:9443`，调用流水逐条留档。
|
||
|
||
**夹具**：服务日 **2026-12-20**（全新，不复用存量），团车 + 司机 + 甲乙两户，VEHICLE 维度共用关系，3 个 alive 成员。
|
||
|
||
**三次查询逐条对**：
|
||
|
||
1. **软清前**：3 个成员全部 alive，关系 `status = ACTIVE`，关系日志仅一条 `CREATE`；
|
||
2. **软清甲之后**：关系仍 `ACTIVE`、`release_reason` 为 null、`active_share_group_id` 仍指向本关系；**甲的成员行** `left_at = 2026-09-21 01:14:08`、`leave_reason = AUTO_OCCUPANCY_RELEASE`，而**团车行与乙的 `left_at` 仍为 null** ⇒ 剩 2 行 alive。（团车行与乙没动，是排除"整条关系被一把清掉"的阳性对照。）
|
||
3. **软清乙（最后一人）之后**：`status = RELEASED`、`release_reason = AUTO_SINGLE_MEMBER`、`active_share_group_id = NULL`、`released_at = 2026-09-21 01:14:08`；关系日志出现 `{action: RELEASED, reason: AUTO_SINGLE_MEMBER}`。
|
||
|
||
## 六、不影响范围
|
||
|
||
- 任何接口的**请求参数、响应字段、错误码**——一个都没动。
|
||
- **取消派单**对在途行的行为（仍落 `exception`、仍保留占用，#6152 定案不变）。
|
||
- **整团解除**的审计原因（PR #8077 专门保证它不被夺走）。
|
||
- 占用账本（`fleet_resource_occupancy_*`）的灰度形态——**仍维持 `LEGACY`，本次修复没有切换它**，这正是本次修复的设计目标：不靠切形态也能让收缩跑起来。
|
||
- **存量数据**：已通过 internal 端点执行收敛（2026-09-21 22:27:47 UTC，不是 SQL 直改）。结果：
|
||
- 摘除成员 **10 行**：`left_at = 2026-09-21 22:27:47`、`leave_reason = AUTO_OCCUPANCY_RELEASE`
|
||
- 整体释放关系 **4 条**：`status = RELEASED`、`release_reason = AUTO_SINGLE_MEMBER`、`released_at = 2026-09-21 22:27:47`
|
||
- 摘除成员后仍保持 ACTIVE 的关系 **2 条**（**非残留**：它们各有 3 个成员，摘掉 1 个后剩 2 个，按收缩规则"剩余 < 2 时解除"不触发）
|
||
|
||
⚠️ 本轮收敛是**点名执行**（传入显式 ID 名单），不是全库扫。若名单外仍有同类历史数据，前端在界面上仍可能遇到"有成员、但该成员已不占用该资源"的关系——**展示逻辑该兜的还得兜**，别假设这类数据在库里已绝迹。
|
||
|
||
## 七、相关历史 PR
|
||
|
||
- PR #8073（`c07942035`）—— 让自动收缩在 LEGACY 下真正执行。
|
||
- PR #8077（`3a92cafbf`）—— 整团解除的审计原因不被自动收缩夺走。
|
||
- 工单 #7972 —— 定案占用账本形态维持 `LEGACY` 不切（本缺陷得以长期存在的环境前提）。
|
||
- 工单 #6152 —— 取消派单对在途行落 `exception` 且保留占用。
|
||
- 工单 #8061 —— 解除共用关系只清成员占用、同槽非成员不动。
|
||
|
||
## 关联 / 联系人
|
||
|
||
### 链接
|
||
|
||
- 后端工单：https://git.1814.love:8443/wx/HL/issues/8064
|
||
- PR：https://git.1814.love:8443/wx/HL/pulls/8073 、 https://git.1814.love:8443/wx/HL/pulls/8077
|
||
|
||
### 联系人
|
||
|
||
- 后端：wx
|
||
- 前端：mmg（本条需前端确认是否缓存了共用关系状态，见"四、前端要做什么"）
|