444 行
30 KiB
Markdown
444 行
30 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "8013"
|
||
title: "共用关系确认历史补记成本承担方变更（COST_BEARER_CHANGED 此前是死枚举）"
|
||
consumer: "admin"
|
||
author: "wx(GIT)"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "not_required"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: ""
|
||
target_release: ""
|
||
verified_at: ""
|
||
status_note: "gateway_status=verified 的依据：2026-09-20 18:22-18:46 经网关实测（账号 cw_test_7444，用的是本方自建的批次 2101246738038652930 上的共用关系 359639602970112，非他人夹具）：保持成员全集不变、仅将 costBearer 由 GROUP 改为 ORDER，POST .../share-groups 返 code=200、version 5→6、history=null（符合本端点 history 恒空的契约）；随即 GET .../share-groups?includeReleased=true 复核，新增历史行 action=COST_BEARER_CHANGED、costBearerSnapshot=ORDER，**未**误写 MEMBER_ADDED。🔴 这正是本篇正文写明的取证口径：判「这次确认写了几条历史」只能靠事后查询，不能靠 POST 响应体推断——本次按此执行。 【上一轮原注】backend_status=deployed 的判据（2026-09-20 18:35 复核）：hl-fleet-service 测试服部署点 311dc92ee（2026-09-20 17:46:56 发布，jar 字节当时经错误码出现次数核对过，非仅凭登记文件），`git merge-base --is-ancestor adfc5b53b 311dc92ee` = true，故本篇端点的代码确已在测试服运行的字节里。⚠️ 这是一次**时点读数**：测试服由多会话共用，随时可能被滚到别的提交；origin/dev-v3 在本次复核时已前进到 f56692a51，落后的是部署点不是本篇。 gateway_status 保持 pending——本会话未对本篇端点做任何真实网关调用，正文示例值的来源已在各小节逐处标注（单元测试字面量 / @ApiModelProperty example 声明），不是抓包。待网关复验后再置 verified，**不得为了让门禁变绿改这个位**。 【本轮之前的原注，保留供追溯口径变化】已合入 dev-v3（PR #8020，squash 提交 adfc5b53b，经 git log origin/dev-v3 --oneline | grep 8013 核实存在于 origin/dev-v3）。backend_status=deployed 的依据是「已在主线」，不代表已部署测试服并做过网关联调。gateway_status 刻意保持 pending——本次未做任何真实网关调用，唯一证据是随 PR 一起合入的两条单元测试（GroupDispatchShareAdmissionServiceTest：confirm_costBearerChangedWithoutMemberChange_writesCostBearerChangedNotMemberAdded / confirm_membersAddedAndCostBearerChangedTogether_writesBothRows），交接时未重新执行这两条测试（本机当时另有全量测试占用窗口，见 MACHINE-LOCK.md）。正文的请求/响应示例数值沿用 #7444 changelog（19_7444_团期配车就绪门禁与车辆共用关系-修改接口-管理后台.md，尚未推送的草稿）里已经登记的同一套 swagger 声明示例值（shareGroupId=77001 等），不是本次新造的编号，也不是真实网关抓包。待管理者安排测试服部署 + 网关复验后，再把 gateway_status 置 verified 并推送本文件；发布前不许为了过校验改这个状态位。 前端实证翻 not_required(mmg 2026-09-20):share-groups/costBearer/COST_BEARER/MEMBER_ADDED 全仓零命中,共用关系确认历史 UI 未建(#7444 挂起域),前端无 action 映射表可补;配车接入时映射必须含 COST_BEARER_CHANGED、同 operateTime 两条历史不去重、不假设每次确认历史 +1 条,已记入前端待办口径。"
|
||
updated_at: "2026-09-20"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# fleet: 共用关系确认历史补记成本承担方变更（工单 #8013）
|
||
|
||
> **存放目录**: 二期（order-v3 标签工单）→ `changelogs-v2/2026-09/`
|
||
>
|
||
> **服务**: hl-fleet-service（8087）
|
||
> **PR**: #8020 ｜ **Issue**: #8013 ｜ **合并提交**: `adfc5b53b`
|
||
> **日期**: 2026-09-20
|
||
> **影响范围**: 管理后台「团期配车页」共用关系确认历史（`GET .../share-groups?includeReleased=true` 的 `history[]`），以及写口 `POST .../share-groups` 内部的历史写入分流逻辑
|
||
|
||
---
|
||
|
||
## ⚠️ 关键变化
|
||
|
||
`ShareLogAction.COST_BEARER_CHANGED` 这个动作常量自 #7444 落地起就**从未被真正写出过**——车务在团期配车页把某天某辆车的共用关系成本承担方从 `GROUP` 改成 `ORDER`（或反过来），确认历史里记下来的是 `MEMBER_ADDED`，即便成员一个都没变。前端如果按 `action` 做过枚举映射/文案表，**没见过** `COST_BEARER_CHANGED` 这个值——它不是"没出现过"的边界情况，是编译器允许、运行时永远走不到的死分支。本次修复后它会真实出现，前端**必须**补上这一项，否则会显示成空白或 fallback 文案。
|
||
|
||
同一次修复顺带纠正了一个同构错误：车务对着同一份成员全集、同一个成本承担方原样重新点一次"确认"（例如错过 `@Idempotent(timeout=10)` 的 10 秒防重窗口后手动再点），改前会**误写一条** `MEMBER_ADDED`——车务并没有加任何成员，历史里却凭空多出一条"加了成员"的记录。改后这种真正的空提交**不产生任何新历史行**。
|
||
|
||
两处都不改变 `POST`/`GET` 两个端点自身的请求/响应字段名、类型或结构；变化只发生在"这次确认写了哪几条历史行、写的是哪个 `action`"这件事上。
|
||
|
||
---
|
||
|
||
## 一、背景
|
||
|
||
`fleet_group_dispatch_share_log.action` 这一列在 `V20260918_003` 建表时就用 CHECK 约束声明了五个合法字面量：`CREATE`/`MEMBER_ADDED`/`MEMBER_REMOVED`/`COST_BEARER_CHANGED`/`RELEASED`。DB 侧一直都能接受 `COST_BEARER_CHANGED`。
|
||
|
||
问题出在 Java 侧：`GroupDispatchShareAdmissionService#confirmInTransaction` 复用既有关系（幂等覆盖）时，末尾恒定写死一条历史——`created ? CREATE : MEMBER_ADDED`。这个三元表达式里**根本没有 `COST_BEARER_CHANGED` 这个分支**，无论车务这次改的是成员、是成本承担方、还是什么都没改，只要不是新建，写出去的永远是 `MEMBER_ADDED`（或者什么都没变时，同样误写 `MEMBER_ADDED`）。
|
||
|
||
`upsertGroup` 内部其实早就在做 `costBearer` 的 CAS 更新（`casUpdateCostBearer`），只是这次落库前后的差异从未被读出来、也从未参与历史写入的判定。
|
||
|
||
| 维度 | 改前 | 改后 |
|
||
|------|------|------|
|
||
| 复用关系时的历史写入判据 | 一个布尔 `created` 决定 `CREATE`/`MEMBER_ADDED` 二选一 | `created`（是否新建）+ 成员是否真的新增 + 成本承担方是否真的变化，三个独立判据，各写各的 0~2 条 |
|
||
| `COST_BEARER_CHANGED` 是否可达 | 否（死代码） | 是（复用关系且成本承担方变化时必写） |
|
||
| 成员全集与成本承担方均未变的重复确认 | 误写 1 条 `MEMBER_ADDED` | 写 0 条 |
|
||
|
||
---
|
||
|
||
## 二、变更接口清单
|
||
|
||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||
|---|------|------|------|----------|------|
|
||
| 1 | 确认团期车辆共用关系 | POST | `/admin/fleet/group-dispatch/batches/{groupBatchId}/share-groups` | 修改接口 | 请求/响应字段零变化；仅内部历史写入判据修正（本节所述） |
|
||
| 2 | 查询团期车辆共用关系 | GET | `/admin/fleet/group-dispatch/batches/{groupBatchId}/share-groups` | 修改接口 | `history[].action` 新增可观测取值 `COST_BEARER_CHANGED`（此前是死枚举） |
|
||
|
||
---
|
||
|
||
## 三、接口详情
|
||
|
||
### 1. 确认团期车辆共用关系 `POST /admin/fleet/group-dispatch/batches/{groupBatchId}/share-groups`
|
||
|
||
**VO**: `ShareGroupConfirmReqVO → ShareGroupRespVO`
|
||
|
||
（本接口的请求/响应字段与 #7444 落地时逐字节一致，未新增/删除/改名任何字段；源码核对：`GroupDispatchShareController.java:53-93`、`ShareGroupConfirmReqVO.java`、`ShareGroupRespVO.java`、`GroupDispatchShareAdmissionService.java:158-241`）
|
||
|
||
#### 使用场景
|
||
|
||
车务在团期配车页确认共用关系时调用，行为与 #7444 changelog 描述完全一致。本次改动**不影响本端点自身的响应内容**（`ShareGroupRespVO.history` 在这个端点上恒为空，历史只能通过接口 2 的 `includeReleased=true` 查询回来）——本节存在的意义是让前端理解"点一次确认，后台这次到底往历史表里写了几条、写的是什么"，这决定了随后调用接口 2 时能看到什么。
|
||
|
||
#### 入参字段表
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| groupBatchId | Path | Long | ✅ | - | 团期主订单 ID（雪花） |
|
||
| serviceDate | Body | LocalDate | ✅ | 必须落在该团基线 `serviceDates[]` 内 | 共用发生的服务日 |
|
||
| resourceType | Body | String | ✅ | `VEHICLE`/`DRIVER` | 资源维度 |
|
||
| resourceId | Body | Long | ✅ | - | 车辆 ID 或司机 ID |
|
||
| members | Body | Array | ✅ | 2～20 个 | 成员**全集**（不是增量） |
|
||
| members[].sourceType | Body | String | ✅ | `ASSIGNMENT`/`GROUP_DISPATCH` | - |
|
||
| members[].sourceId | Body | Long | ✅ | - | 派单 ID 或团级配车行 ID |
|
||
| costBearer | Body | String | ✅ | `GROUP`/`ORDER` | **本次改动的判据来源**：与落库前的旧值比对，不同则本次会多写一条 `COST_BEARER_CHANGED` |
|
||
| costBearerOrderId | Body | Long | 条件必填 | `costBearer=ORDER` 时必填 | - |
|
||
| remark | Body | String | ❌ | ≤200 | 确认备注（也会写进新增的历史行） |
|
||
|
||
（完整入参约束、错误码见 #7444 changelog 对应小节，本次未改动任何一条校验规则）
|
||
|
||
#### 出参字段表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| shareGroupId / groupBatchId / serviceDate / resourceType / resourceId / status / costBearer / costBearerOrderId / costSourceRefNo / members[] / confirmedBy / confirmedAt / version | - | 字段名/类型/取值规则均**未变动**，与 #7444 落地时逐字节一致 |
|
||
| history | Array | 本端点恒为 `null`/空数组；**本次改动写了几条历史、写的是什么，在这个响应体里看不到**，必须另调接口 2 |
|
||
|
||
#### 请求示例
|
||
|
||
沿用 #7444 changelog 登记的示例数据集（`shareGroupId=77001` 等），仅把 `costBearer` 改成触发 `COST_BEARER_CHANGED` 的取值：该关系此前以 `costBearer=GROUP` 建立，本次原样重新提交同一份成员全集、只把 `costBearer` 改成 `ORDER`：
|
||
|
||
```json
|
||
{
|
||
"serviceDate": "2026-09-12",
|
||
"resourceType": "VEHICLE",
|
||
"resourceId": 1,
|
||
"members": [
|
||
{ "sourceType": "GROUP_DISPATCH", "sourceId": 99001 },
|
||
{ "sourceType": "ASSIGNMENT", "sourceId": 88001, "admissionIntent": "OCCUPYING" }
|
||
],
|
||
"costBearer": "ORDER",
|
||
"costBearerOrderId": 70123,
|
||
"remark": "车费改由甲户订单承担"
|
||
}
|
||
```
|
||
|
||
（路径参数 `groupBatchId=8801`）
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"shareGroupId": "77001",
|
||
"groupBatchId": "8801",
|
||
"serviceDate": "2026-09-12",
|
||
"resourceType": "VEHICLE",
|
||
"resourceId": "1",
|
||
"status": "ACTIVE",
|
||
"costBearer": "ORDER",
|
||
"costBearerOrderId": "70123",
|
||
"costSourceRefNo": "SHARE-77001",
|
||
"members": [
|
||
{ "sourceType": "GROUP_DISPATCH", "sourceId": "99001", "requirementId": null, "orderId": null },
|
||
{ "sourceType": "ASSIGNMENT", "sourceId": "88001", "requirementId": "5501", "orderId": "70123" }
|
||
],
|
||
"confirmedBy": "1001",
|
||
"confirmedAt": "2026-09-12 18:25:10",
|
||
"version": 2
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
⚠️ 这个响应体本身**看不出**后台这次到底记了几条历史——`history` 字段在这个端点上恒为空。要确认这次调用是否真的多写了一条 `COST_BEARER_CHANGED`，必须紧接着调接口 2（`includeReleased=true`）。
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
本接口是同步写操作，不存在响应体意义上的"空数据"。**但本次改动引入了一种新的"写 0 条历史"的合法情形**：若车务原样重新提交同一份成员全集、且 `costBearer` 也未变（`membersAdded=false && costBearerChanged=false`），本次确认**不产生任何新历史行**——这不是接口故障，是 #8013 修复后的预期行为；改动前这种情况会误写一条 `MEMBER_ADDED`。前端不应假设"每次点确认，历史列表长度必然 +1"。
|
||
|
||
#### 错误响应
|
||
|
||
本次改动不引入任何新错误码，错误响应与 #7444 落地时完全一致，例如：
|
||
|
||
```json
|
||
{
|
||
"code": 602103,
|
||
"message": "成员派单不属于本团或团期身份未知: 88099",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- **本次改动不改变鉴权、幂等、校验、事务边界**，与 #7444 changelog 描述的规则完全一致。
|
||
- **判据在落库前取样**：`costBearer` 是否变化，取的是 `casUpdateCostBearer` 执行前读到的旧值与本次入参的比对结果，不是事后反查历史表推断出来的——落库那一瞬间旧快照就没有意义了，判据必须在那之前定下来。
|
||
- **新建关系（`created=true`）分支完全不受影响**：仍然只写 1 条 `CREATE`，不会额外叠加 `COST_BEARER_CHANGED`（新建时这条 `CREATE` 历史本身就带着当次的 `costBearerSnapshot`，没有必要再补一条）。
|
||
- **同一次确认最多产生 2 条新历史**（成员新增 1 条 `MEMBER_ADDED` + 成本承担方变化 1 条 `COST_BEARER_CHANGED`），顺序恒为先 `MEMBER_ADDED` 后 `COST_BEARER_CHANGED`（`operateTime` 相同，前端排序如依赖 `operateTime` 需要一个稳定的次级排序键，比如 `logId` 自增）；**成员被移出**（`MEMBER_REMOVED`）走的是 `syncMembers` 内联的另一条写入路径，与本次改动的判据完全独立，不受影响。
|
||
|
||
---
|
||
|
||
### 2. 查询团期车辆共用关系 `GET /admin/fleet/group-dispatch/batches/{groupBatchId}/share-groups`
|
||
|
||
**VO**: `ShareGroupQueryReqVO → List<ShareGroupRespVO>`
|
||
|
||
（源码核对：`GroupDispatchShareController.java:100-111`、`GroupDispatchShareService.java:125-144`、`ShareGroupHistoryRespVO.java`）
|
||
|
||
#### 使用场景
|
||
|
||
团期配车页 / 核团排障时查看共用关系变更历史，`includeReleased=true` 时返回 `history[]`。本次改动后，这里**首次**可能出现 `action="COST_BEARER_CHANGED"` 的历史行——此前无论后台实际发生了什么，这里永远只会看到 `CREATE`/`MEMBER_ADDED`/`MEMBER_REMOVED`/`RELEASED` 四种。
|
||
|
||
#### 入参字段表
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| groupBatchId | Path | Long | ✅ | - | 团期主订单 ID |
|
||
| serviceDate | Query | LocalDate | ❌ | 不传=全部服务日 | - |
|
||
| resourceType | Query | String | ❌ | `VEHICLE`/`DRIVER` | 不传=两者都查 |
|
||
| includeReleased | Query | Boolean | ❌ | 默认 false | **必须为 true 才会带 `history[]`**；本次改动只影响 `history[].action` 的取值分布，不影响本参数语义 |
|
||
|
||
#### 出参字段表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| （数组元素其余字段：shareGroupId / groupBatchId / serviceDate / resourceType / resourceId / status / costBearer / costBearerOrderId / costSourceRefNo / members[] / confirmedBy / confirmedAt / version） | - | **本次未改动** |
|
||
| history[] | Array | 仅 `includeReleased=true` 时非空；**本次改动只影响这个数组里各行 `action` 的取值分布，字段结构本身零变化** |
|
||
| history[].action | String | **本次改动点**：合法取值仍是 `CREATE`/`MEMBER_ADDED`/`MEMBER_REMOVED`/`COST_BEARER_CHANGED`/`RELEASED` 五个（DB CHECK 早已如此），但 `COST_BEARER_CHANGED` 此前从未被真实写出过，本次修复后会真实出现 |
|
||
| history[].memberSnapshot | String | 该次变更后的成员全集快照（JSON 文本）；`COST_BEARER_CHANGED` 这条历史的快照与紧邻的 `MEMBER_ADDED`（如果同次确认也写了的话）逻辑上相同，因为两条历史共用同一次 `selectActiveByGroupForUpdate` 锁定读结果 |
|
||
| history[].costBearerSnapshot | String | 该次变更后的成本承担方；`COST_BEARER_CHANGED` 这条历史上就是本次改到的新值 |
|
||
| history[].operator | String | 操作人 adminId |
|
||
| history[].operateTime | LocalDateTime | 操作时间；同一次确认产生的 `MEMBER_ADDED` 与 `COST_BEARER_CHANGED` 两条历史 `operateTime` 相同（同一个 `now` 变量） |
|
||
| history[].reason | String | 仅 `RELEASED` 动作有值，`COST_BEARER_CHANGED` 恒为 `null` |
|
||
| history[].remark | String | 备注；`COST_BEARER_CHANGED` 这条历史的 `remark` 与同次确认入参的 `remark` 相同（若同次也写了 `MEMBER_ADDED`，两条历史的 `remark` 是同一个值，不是分开填的两段话） |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /admin/fleet/group-dispatch/batches/8801/share-groups?includeReleased=true
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
沿用接口 1 示例的后续状态：该关系先以 `costBearer=GROUP` 建立（写 1 条 `CREATE`），随后车务把 `costBearer` 改成 `ORDER`（本次改动生效，写 1 条 `COST_BEARER_CHANGED`）：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": [
|
||
{
|
||
"shareGroupId": "77001",
|
||
"groupBatchId": "8801",
|
||
"serviceDate": "2026-09-12",
|
||
"resourceType": "VEHICLE",
|
||
"resourceId": "1",
|
||
"status": "ACTIVE",
|
||
"costBearer": "ORDER",
|
||
"costBearerOrderId": "70123",
|
||
"costSourceRefNo": "SHARE-77001",
|
||
"members": [
|
||
{ "sourceType": "GROUP_DISPATCH", "sourceId": "99001", "requirementId": null, "orderId": null },
|
||
{ "sourceType": "ASSIGNMENT", "sourceId": "88001", "requirementId": "5501", "orderId": "70123" }
|
||
],
|
||
"confirmedBy": "1001",
|
||
"confirmedAt": "2026-09-12 18:25:10",
|
||
"version": 2,
|
||
"history": [
|
||
{
|
||
"action": "CREATE",
|
||
"memberSnapshot": "[{\"sourceType\":\"GROUP_DISPATCH\",\"sourceId\":\"99001\",\"requirementId\":null,\"orderId\":null},{\"sourceType\":\"ASSIGNMENT\",\"sourceId\":\"88001\",\"requirementId\":\"5501\",\"orderId\":\"70123\"}]",
|
||
"costBearerSnapshot": "GROUP",
|
||
"operator": "1001",
|
||
"operateTime": "2026-09-12 18:20:33",
|
||
"reason": null,
|
||
"remark": "团车上午行程后接甲户"
|
||
},
|
||
{
|
||
"action": "COST_BEARER_CHANGED",
|
||
"memberSnapshot": "[{\"sourceType\":\"GROUP_DISPATCH\",\"sourceId\":\"99001\",\"requirementId\":null,\"orderId\":null},{\"sourceType\":\"ASSIGNMENT\",\"sourceId\":\"88001\",\"requirementId\":\"5501\",\"orderId\":\"70123\"}]",
|
||
"costBearerSnapshot": "ORDER",
|
||
"operator": "1001",
|
||
"operateTime": "2026-09-12 18:25:10",
|
||
"reason": null,
|
||
"remark": "车费改由甲户订单承担"
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
⚠️ **本响应体的数值构造来自 #7444 changelog 登记的同一套 swagger 声明示例 + 本次源码新增的判据逻辑推算，不是真实网关抓包**（`gateway_status=pending`，见 frontmatter `status_note`）。结构与字段名已逐一对源码核实（`ShareGroupHistoryRespVO.java`），但具体数值请在网关复验后以实测为准。
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
本团在筛选条件下没有任何共用关系时返回空数组 `[]`；`includeReleased=false`（默认）时 `history` 字段不返回。本次改动不影响这两种既有的空态。
|
||
|
||
#### 错误响应
|
||
|
||
```json
|
||
{
|
||
"code": 100001,
|
||
"message": "参数非法: 资源维度非法: TRAIN",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- **鉴权**：路径级角色门禁 `X-Admin-Role` 须为 `VEHICLE_MANAGER`/`SUPER_ADMIN`，本次未改动（详见 #7444 changelog）。
|
||
- **前端枚举映射表必须补 `COST_BEARER_CHANGED`**：此前的响应里从未出现过这个值，前端若对 `action` 做过 `switch`/映射表且没有兜底分支，会渲染成空白/`undefined`，而不是报错——这类问题不会在联调时报红，只会在页面上悄悄显示不对。
|
||
- **`memberSnapshot` 仍是全集不是增量**，本次改动不影响这条既有约定。
|
||
- **`COST_BEARER_CHANGED` 与紧邻的 `MEMBER_ADDED`（如果同次确认也命中的话）`operateTime` 相同**，前端如果用 `operateTime` 做排序/分组去重，需要注意这两条历史是同一次操作产生的两个独立事实，不能因为时间戳相同就当成重复记录去重掉。
|
||
- 查询接口本身不加锁、不开事务，读到的是调用时刻的库状态。
|
||
|
||
---
|
||
|
||
## 四、契约约束与正确调用方式
|
||
|
||
> 本节只写后端接受/拒绝 payload 的规则与历史写入判据，不写 UI 渲染建议。
|
||
|
||
### `COST_BEARER_CHANGED` 的触发条件是「落库前旧值 ≠ 本次入参新值」
|
||
|
||
这是纯粹的服务端判据，前端**不需要、也不应该**自己在客户端比对新旧 `costBearer` 来猜这次会不会有 `COST_BEARER_CHANGED` 历史——判据用的是数据库锁定读到的旧快照，前端本地缓存的旧值可能已经过期（比如同一团被另一个车务并发改过）。
|
||
|
||
### 判断"这次确认到底写了几条历史"，只能靠事后查询，不能靠 POST 响应体推断
|
||
|
||
`POST .../share-groups` 的响应体里没有任何字段能告诉调用方"这次写了 1 条还是 2 条历史、写的是什么 action"。前端如果需要在确认成功后立刻展示"本次变更记录"，必须紧接着调 `GET .../share-groups?includeReleased=true`，按 `operateTime`（+ 稳定次级排序键）取最新的 1~2 条。
|
||
|
||
### ✅ 正确 / ❌ 错误 理解对照
|
||
|
||
| 场景 | 后台实际写入 | 前端不应假设的事 |
|
||
|---|---|---|
|
||
| ✅ 新建关系 | 1 条 `CREATE` | 不会额外出现 `COST_BEARER_CHANGED` |
|
||
| ✅ 复用关系，只改 `costBearer`，成员全集不变 | 1 条 `COST_BEARER_CHANGED` | 不会出现 `MEMBER_ADDED` |
|
||
| ✅ 复用关系，成员与 `costBearer` 都变了 | 2 条：`MEMBER_ADDED` + `COST_BEARER_CHANGED` | 两条 `operateTime` 相同，不是两次独立操作 |
|
||
| ✅ 复用关系，成员与 `costBearer` 都没变（原样重提） | **0 条** | ❌ 不要假设"点一次确认历史必然 +1 条"——改前的旧行为才是这样，且是 #8013 要修的缺陷 |
|
||
| ❌ 前端自行比对 `costBearer` 新旧值来预测本次是否有 `COST_BEARER_CHANGED` | 无意义 | 判据在服务端落库前的锁定读上，前端本地状态可能已过期 |
|
||
|
||
---
|
||
|
||
## 五、数据库行为
|
||
|
||
写接口 `POST .../share-groups` 落库表 `fleet_group_dispatch_share_log`（`V20260918_003` 建表，INSERT-only 留痕表，一行 = 关系的一次变更）。
|
||
|
||
**本次改动不新增任何列、不新增任何表、不改 `chk_share_log_action` 约束**——约束自建表起就允许 `COST_BEARER_CHANGED` 这个字面量，缺陷完全在 Java 应用层（三元表达式漏了这个分支），DB 侧从一开始就是就绪的。
|
||
|
||
| 场景 | 改前写入行数 | 改后写入行数 |
|
||
|---|---|---|
|
||
| 新建关系 | 1（`CREATE`） | 1（`CREATE`，不变） |
|
||
| 复用关系，仅成员变化 | 1（`MEMBER_ADDED`） | 1（`MEMBER_ADDED`，不变） |
|
||
| 复用关系，仅 `costBearer` 变化 | 1（**误写** `MEMBER_ADDED`） | 1（`COST_BEARER_CHANGED`） |
|
||
| 复用关系，成员与 `costBearer` 都变化 | 1（`MEMBER_ADDED`，`costBearer` 变化未留痕） | 2（`MEMBER_ADDED` + `COST_BEARER_CHANGED`） |
|
||
| 复用关系，两者都未变化（原样重提） | 1（**误写** `MEMBER_ADDED`） | 0（不写） |
|
||
| 成员被移出 | 1（`MEMBER_REMOVED`，`syncMembers` 内联写，独立路径） | 1（不变，本次未触碰这条路径） |
|
||
|
||
---
|
||
|
||
## 六、边界行为
|
||
|
||
- 未登录/网关未透传角色 → 401（网关拦截），与既有行为一致
|
||
- `resourceType` 非法枚举值 → `100001`（沿用既有，见 #7444 changelog 更正记录）
|
||
- 成员数越界、服务日窗外、并发修改等既有错误码全部未变（602100~602112 段）
|
||
- 老数据兼容：本次改动前落库的历史行（`action` 只可能是 `CREATE`/`MEMBER_ADDED`/`MEMBER_REMOVED`/`RELEASED` 四种之一）原样保留，查询时按原值返回，不会被"回填"或"重新计算"成 `COST_BEARER_CHANGED`——本次修复只影响**新产生**的历史行，不改写存量数据
|
||
- `appendConfirmChangeLog` 全程在 `confirmInTransaction` 的同一个事务内执行，与关系落库、成员同步、派单关联、占用准入共享同一次提交/回滚，不会出现"关系已改但历史没写"或"历史写了但关系没改"的中间态
|
||
|
||
---
|
||
|
||
## 六.5、枚举 / 数据字典
|
||
|
||
### `action`（`ShareGroupHistoryRespVO.action`，源码 `ShareLogAction` 常量类 / DB `chk_share_log_action`）
|
||
|
||
**所属字段**: `history[].action` | **类型**: `String`
|
||
|
||
| 值 | 说明 | 本次改动前是否可能在响应中出现 |
|
||
|----|------|------|
|
||
| `CREATE` | 首次建立关系 | 是 |
|
||
| `MEMBER_ADDED` | 幂等覆盖时成员净增；改动前该分支同时错误吸收了"仅改成本承担方"与"什么都没改"两种场景 | 是（含误写） |
|
||
| `MEMBER_REMOVED` | 幂等覆盖或自动收缩时成员净减 | 是 |
|
||
| `COST_BEARER_CHANGED` | 成本承担方变更 | **否——本次改动前是死枚举，代码路径永远走不到** |
|
||
| `RELEASED` | 关系解除（四条解除路径共用） | 是 |
|
||
|
||
⚠️ 该枚举早在 `V20260918_003`（2026-09-18）建表时就在 DB CHECK 约束里声明了全部五个值，`COST_BEARER_CHANGED` 不是本次新加的枚举字面量，而是本次才让它第一次真正可达。
|
||
|
||
---
|
||
|
||
## 六.6、修改前后对比
|
||
|
||
### 字段级对比
|
||
|
||
| 字段 | 改前 | 改后 |
|
||
|------|------|------|
|
||
| `history[].action` 合法取值集合 | 声明上五个值都合法，但实际只会出现 `CREATE`/`MEMBER_ADDED`/`MEMBER_REMOVED`/`RELEASED` 四种 | 全部五个值均可能真实出现 |
|
||
| `POST`/`GET` 两端点的请求/响应字段名、类型、结构 | - | **零变化** |
|
||
|
||
### 行为级对比
|
||
|
||
| 行为 | 改前 | 改后 |
|
||
|------|------|------|
|
||
| 复用关系，仅改 `costBearer` | 误写 1 条 `MEMBER_ADDED`（无法从历史看出改的是成本承担方） | 正确写 1 条 `COST_BEARER_CHANGED` |
|
||
| 复用关系，成员与 `costBearer` 都改 | 只写 1 条 `MEMBER_ADDED`（`costBearer` 变化完全未留痕） | 写 2 条：`MEMBER_ADDED` + `COST_BEARER_CHANGED`，两件事都可追溯 |
|
||
| 复用关系，成员与 `costBearer` 都未改（原样重提） | 误写 1 条 `MEMBER_ADDED`（凭空多一条"加了成员"的假记录） | 写 0 条 |
|
||
| 新建关系 | 写 1 条 `CREATE` | 不变 |
|
||
|
||
## 六.7、影响评估
|
||
|
||
- **是否破坏向后兼容**: 否——两个端点的请求/响应字段名、类型、结构均未变动；变化只发生在 `history[].action` 的取值分布上（新增可观测取值，不是改变既有取值的含义）
|
||
- **前端是否必须同步上线**: 是——如果前端对 `action` 做了枚举映射/文案表且没有安全的 `default` 兜底，`COST_BEARER_CHANGED` 首次出现时会展示为空白或 `undefined`，需要补上这一项映射
|
||
- **前端 workaround 清理点**: 若前端此前发现"改成本承担方后历史列表多了一条奇怪的『新增成员』记录"并做过任何遮蔽/过滤逻辑（比如按 `remark` 内容猜测过滤掉这类"假 MEMBER_ADDED"），本次修复后这类 workaround 应当撤除——改后不会再产生这种假记录
|
||
|
||
---
|
||
|
||
## 七、不影响范围
|
||
|
||
- **仅影响**: 共用关系确认历史的写入判据（`POST .../share-groups` 内部）与查询回显（`GET .../share-groups?includeReleased=true` 的 `history[].action`）
|
||
- **零影响**:
|
||
- 两个端点的请求体、响应体字段名/类型/结构**零变更**
|
||
- 新建关系（`CREATE`）分支完全不受影响
|
||
- 解除关系（`RELEASED`，`DELETE .../share-groups/{shareGroupId}`）分支完全不受影响，本次未改动该端点任何代码
|
||
- 成员被移出（`MEMBER_REMOVED`）分支完全不受影响，走的是独立的内联写入路径
|
||
- 准入三步流程（授权 → 派单关联 → 占用准入）与占用账本行为**完全不受影响**，本次只动了流程末尾的历史写入分流
|
||
- 无新增 DB 表/列/索引/约束；`chk_share_log_action` 约束原样不变（自 `V20260918_003` 起就允许 `COST_BEARER_CHANGED`）
|
||
- 团期配车其余端点（就绪判定、派单预校验/候选、reconfigure 等）零影响
|
||
|
||
---
|
||
|
||
## 八、测试环境已验证
|
||
|
||
⚠️ **本篇尚无测试服/网关读数**（`gateway_status=pending`），以下只是**单元测试**层面的证据，不是测试环境实测——按管理者要求如实标注，不把单测读数伪装成测试环境验证：
|
||
|
||
随 PR #8020 一并合入的两条新增单测（`GroupDispatchShareAdmissionServiceTest`，Mockito，未重跑，仅列出用例名与断言意图供核实）：
|
||
|
||
```
|
||
confirm_costBearerChangedWithoutMemberChange_writesCostBearerChangedNotMemberAdded
|
||
→ 只改 costBearer、成员不变：断言 append(COST_BEARER_CHANGED) 被调用一次，
|
||
且 append(MEMBER_ADDED) 从未被调用（verify(..., never())）
|
||
|
||
confirm_membersAddedAndCostBearerChangedTogether_writesBothRows
|
||
→ 成员与 costBearer 同次都变：断言 append(MEMBER_ADDED) 与 append(COST_BEARER_CHANGED)
|
||
均被调用一次
|
||
```
|
||
|
||
**待办**：管理者安排 hl-fleet-service 部署测试服后，需补一次真实网关调用（POST 确认 + GET 查询 `includeReleased=true`），核实 `history[].action="COST_BEARER_CHANGED"` 真实落库并可读出，再把 `gateway_status` 置 `verified` 并推送本文件。
|
||
|
||
---
|
||
|
||
## 十、相关文档
|
||
|
||
- 关联 Issue: [wx/HL#8013](https://git.1814.love:8443/wx/HL/issues/8013)
|
||
- 关联 PR: [wx/HL#8020](https://git.1814.love:8443/wx/HL/pulls/8020)（squash 合并至 dev-v3 @`adfc5b53b`）
|
||
- 共用关系机制本身（confirm/query/release 三端点完整契约）见 #7444 changelog：`changelogs-v2/2026-09/19_7444_团期配车就绪门禁与车辆共用关系-修改接口-管理后台.md`（尚未推送的草稿，仅供内部核对参考，不作为已发布依据）
|
||
|
||
## 关联 / 联系人
|
||
|
||
### 链接
|
||
|
||
- **Issue**: [#8013](https://git.1814.love:8443/wx/HL/issues/8013)
|
||
- **PR**: [#8020](https://git.1814.love:8443/wx/HL/pulls/8020)
|
||
- **Merge commit**: [adfc5b53b](https://git.1814.love:8443/wx/HL/commit/adfc5b53b1aea08529eeb41459a692c7f8a9ed7a)
|
||
|
||
### 联系人
|
||
|
||
- **后端负责人**: wx(GIT)
|
||
- **前端负责人**: mmg
|