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>
这个提交包含在:
@@ -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`**,本文档只补列字段名与出处。
|
||||
|
||||
#### 请求示例
|
||||
|
||||
|
||||
在新工单中引用
屏蔽一个用户