docs(changelog): #7442 逐字段审计查出两处契约错误，修正 coverage 错误响应与 reconfigure 漏列的 5 个字段
changelog-filename-gate / validate (push) Failing after 2s
changelog-filename-gate / validate (push) Failing after 2s
对 4 份 #7442 交接件做了逐字段契约审计（10 个端点、21 个错误码，分母从 工单正文与源码数、不从 changelog 数），端点数与错误码数均对上，查出两处： 1. coverage 端点「错误响应」节整段写错（严重）。原文写成「本团正式需求 零分组或无需求时统一失败关闭、返 602009」，并引了一句并不存在的 message。核 GroupDispatchService#queryCoverage 后实为三条不同路径： - 无活跃需求 → HTTP 200、success=true、satisfied=false，gaps 指出身份 已变，根本不是错误 - 有需求但零分组 → 602009，message 实为「正式用车需求未声明任何乘车 分组(整团免车的团期不应配车)」，抛出点在 GroupDispatchCoverageCalculator - 基线不可达 → 600009，不是 602009 把三条压成一条，会让调用方给一个返 200 的正常场景写错误处理分支—— 「拿不到覆盖结论」和「覆盖结论是不满足」在本端点不是同一件事。 2. reconfigure 补登漏列 5 个字段：入参 survivorPolicy（clearAll=true 且 存在 active 共用关系时必填，缺失抛 602110）与出参 releasedShareGroupIds / keptSourceIds / releasedSourceIds / pendingReassignSourceIds。它们由 #7444 追加到同一个端点，完整语义在 #7444 那份 changelog 里；本文档只补 列字段名与出处，不重复。 ⚠️ 这一处的机制值得记：本文档自称按端点「当前的完整契约」撰写，而 「完整契约」这种自述会在别的工单往同一个端点加字段时静默失效——加字段 的人写的是他自己那份 changelog，不会回头改这一份。 Refs #7442 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
这个提交包含在：
API Changelog Bot
@@ -84,6 +84,16 @@ base: "dev-v3"
|
||||
| demands[].assignments[].vehicleId | Body | Long | 是 | - | 派出车辆 ID；同日重复抛 600006（车辆被占） |
|
||||
| demands[].assignments[].driverId | Body | Long | 否 | - | 派出司机 ID；可空=仅排车未排司机；同日重复抛 600007（司机被占） |
|
||||
| demands[].assignments[].remark | Body | String | 否 | ≤200 字符 | 备注 |
|
||||
| survivorPolicy | Body | String | **条件必填** | - | 🔴 **【#7444 追加，2026-09-19 补列】** `clearAll=true` 且该团存在 active 车辆共用关系时**必填**，缺失抛 **602110**。完整取值与语义见 `19_7444_团期配车就绪门禁与车辆共用关系-修改接口-管理后台.md` |
|
||||
|
||||
> 🔴 **2026-09-19 订正：本文档此前漏列了 5 个字段（入参 1 + 出参 4）。**
|
||||
> 它们由 **#7444** 追加到**同一个端点**上，源码里也标注为 #7444
|
||||
> （`GroupDispatchReconfigureReqVO` / `GroupDispatchReconfigureRespVO`）。
|
||||
> ⚠️ **漏列的后果是具体的**：本文档开头自称按端点**「当前的完整契约」**撰写，
|
||||
> 只读这一份的人会以为契约就这些，而 `clearAll=true` 时不传 `survivorPolicy` 会**直接被 602110 拒**。
|
||||
> ⇒ 这 5 个字段的**完整语义在 #7444 那份文档里**，本文档只补列字段名与出处，不重复其内容。
|
||||
> **教训**：「本端点的完整契约」这种自述，会在**别的工单往同一个端点加字段**时静默失效——
|
||||
> 而加字段的人写的是他自己那份 changelog，不会回头改这一份。
|
||||
|
||||
#### 出参字段表
|
||||
|
||||
@@ -112,6 +122,13 @@ base: "dev-v3"
|
||||
| coverage.missingGroupCodes | Array\<String\> | **恒为空列表**（见「⚠️ 关键变化」第 4 条），不要依赖它判断缺组 |
|
||||
| coverage.wholeBatchSatisfied | Boolean | 全团行程日整体覆盖是否成立 |
|
||||
| legacyGroupRowCount | Integer | 本团存活派车行里无分组键的历史行数（非错误，仅留痕，见 #7442 AC-32） |
|
||||
| releasedShareGroupIds | Array\<String\> | 🔴 **【#7444 追加，2026-09-19 补列】** 本次被解除的车辆共用关系 ID |
|
||||
| keptSourceIds | Array\<String\> | 🔴 **【#7444 追加】** 按 `survivorPolicy` 判定为保留的幸存派单 `sourceId` |
|
||||
| releasedSourceIds | Array\<String\> | 🔴 **【#7444 追加】** 按 `survivorPolicy` 判定为释放的派单 `sourceId` |
|
||||
| pendingReassignSourceIds | Array\<String\> | 🔴 **【#7444 追加】** 待重新改派的派单 `sourceId` |
|
||||
|
||||
> ⚠️ 上面 4 个出参字段同 `survivorPolicy`，由 #7444 追加，**完整语义见
|
||||
> `19_7444_团期配车就绪门禁与车辆共用关系-修改接口-管理后台.md`**，本文档只补列字段名与出处。
|
||||
|
||||
#### 请求示例
|
||||
|
||||
|
||||
@@ -459,17 +459,36 @@ GET /internal/fleet/dispatch/group-batch/1934567890123456800/coverage?requiremen
|
||||
|
||||
#### 错误响应
|
||||
|
||||
本团正式需求零分组（整团免车）或无需求时失败关闭：
|
||||
> 🔴 **2026-09-19 订正：本节此前整段写错了。**原文写成「本团正式需求零分组（整团免车）**或无需求**时统一失败关闭、返 602009」，并引了一句并不存在的 message。逐行核 `GroupDispatchService.java:1182-1201 queryCoverage` 后，**实际是三条互不相同的路径**——把它们压成一条，会让调用方给一个**根本返 200 的场景**写错误处理分支。
|
||||
|
||||
| 情形 | 实际响应 | 依据 |
|
||||
|---|---|---|
|
||||
| **无活跃需求**（`baseline.getRequirementId()` 为 null，与入参不等） | 🔴 **HTTP 200，不是错误**：`satisfied=false`，`gaps=["需求身份已变：请求 x/vy，当前 null/vnull"]` | `GroupDispatchService.java:1182-1201`，走 identity-mismatch 分支 |
|
||||
| **有匹配需求但零分组**（整团免车） | **602009**，message 实为 `"正式用车需求未声明任何乘车分组(整团免车的团期不应配车)"` | 抛出点在 `GroupDispatchCoverageCalculator.java:60` |
|
||||
| **基线拉取不可达** | **600009**（基线不可用），**不是 602009** | `fetchBaselineOrFail` |
|
||||
|
||||
```json
|
||||
// ① 无活跃需求 —— 注意这是 200，success=true
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"data": { "satisfied": false, "gaps": ["需求身份已变：请求 …/v3，当前 null/vnull"] },
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
// ② 有需求但零分组（整团免车）
|
||||
{
|
||||
"code": 602009,
|
||||
"message": "无法取得本团的权威乘车分组清单: 该团正式需求整团免车",
|
||||
"message": "正式用车需求未声明任何乘车分组(整团免车的团期不应配车)",
|
||||
"data": null,
|
||||
"success": false
|
||||
}
|
||||
```
|
||||
|
||||
⚠️ **调用方要点**：「拿不到覆盖结论」和「覆盖结论是不满足」在本端点**不是同一件事**——前者才是错误码，后者是 200 + `satisfied=false`。把 ① 当错误处理，会把一个正常的「需求身份已变、请重新确认」渲染成系统故障。
|
||||
|
||||
#### 业务边界
|
||||
|
||||
- `missingGroupCodes` 在本端点才有非空的可能，其余端点（重配写口）的同名字段在任何路径上都只能是空列表——两处含义不同，前端渲染缺口清单只能信本端点
|
||||
|
||||
在新工单中引用
屏蔽一个用户