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>
这个提交包含在:
@@ -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` 在本端点才有非空的可能,其余端点(重配写口)的同名字段在任何路径上都只能是空列表——两处含义不同,前端渲染缺口清单只能信本端点
|
||||
|
||||
在新工单中引用
屏蔽一个用户