hl-api-changelog/changelogs-v2/2026-09/21_8064_共用关系成员失去占用后关系会自动收缩-修复-管理后台.md

---
schema: "hl-changelog/v2"
ticket: "8064"
title: "fleet: 共用关系成员失去占用后，关系现在会自动收缩（行为变更，无接口契约变化）"
consumer: "admin"
author: "wx(GIT)"
change_type: "修复"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "pending"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: "2026-09-21"
status_note: "本条无任何接口出入参或错误码变化，变的是同一请求的副作用：共用关系现在会在成员失去占用时自动收缩、剩余不足 2 人时自动解除。gateway_status=verified 的依据是 2026-09-21 经网关 https://api.test.1814.love:9443 的真实调用（建关系 + 两次 soft-clear-assignment），调用流水与库内终态逐条对照一致，不是只看部署登记。frontend_status 取 pending 而非 not_required：本条会让共用关系『自己消失』，前端是否需要改代码取决于它有没有缓存 activeShareGroupId 或假设关系只能人工解除——那是我无法从后端查证的事实，所以不替前端下 not_required 的结论；mmg 评估后若确认零改动，再由前端侧改为 not_required。⚠️ 存量数据尚未收敛（工单 #8064 AC-5 未完成，成文时实测孤儿关系 7 条），本次修复只对修复上线后发生的释放动作生效。"
updated_at: "2026-09-21"
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 维度的两条共用关系，**两条都会受影响**，不是只动一条。

### 整团解除不会被改写成自动收缩

整团解除时，关系的 `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`，本次修复没有切换它**，这正是本次修复的设计目标：不靠切形态也能让收缩跑起来。
- **存量数据**：⚠️ **未收敛**。工单 #8064 AC-5 的存量收敛尚未执行（成文时实测孤儿关系 **7** 条，判据为"有 alive 成员但该成员已不占用本资源的 ACTIVE 关系"）。本次修复**只对修复上线之后发生的释放动作生效**，历史遗留的不一致关系仍需单独收敛，完成后本文件会追加说明。

## 七、相关历史 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（本条需前端确认是否缓存了共用关系状态，见"四、前端要做什么"）