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

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	8064	fleet: 共用关系成员失去占用后，关系现在会自动收缩（行为变更，无接口契约变化）	admin	wx(GIT)	修复	deployed	verified	not_required					本条无任何接口出入参或错误码变化，变的是同一请求的副作用：共用关系现在会在成员失去占用时自动收缩、剩余不足 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 实证口径),前端无任何共用关系状态缓存、无「关系只能人工解除」的假设;未来接入时均为操作后实时拉取,自动收缩不产生前端脏读。	2026-09-22	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() 的第一条语句是：

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