From fc36125695fee06cc39b9cf173460f8063aafda5 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Sat, 19 Sep 2026 14:35:25 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#7442=20=E9=80=90=E5=AD=97?= =?UTF-8?q?=E6=AE=B5=E5=AE=A1=E8=AE=A1=E6=9F=A5=E5=87=BA=E4=B8=A4=E5=A4=84?= =?UTF-8?q?=E5=A5=91=E7=BA=A6=E9=94=99=E8=AF=AF=EF=BC=8C=E4=BF=AE=E6=AD=A3?= =?UTF-8?q?=20coverage=20=E9=94=99=E8=AF=AF=E5=93=8D=E5=BA=94=E4=B8=8E=20r?= =?UTF-8?q?econfigure=20=E6=BC=8F=E5=88=97=E7=9A=84=205=20=E4=B8=AA?= =?UTF-8?q?=E5=AD=97=E6=AE=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 对 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) --- ...分组写口reconfigure补登-新增接口-管理后台.md | 17 ++++++++++++++ ...控重开窗口计划刷新状态收口-新增接口-管理后台.md | 23 +++++++++++++++++-- 2 files changed, 38 insertions(+), 2 deletions(-) diff --git a/changelogs-v2/2026-09/19_7442_团期配车分组写口reconfigure补登-新增接口-管理后台.md b/changelogs-v2/2026-09/19_7442_团期配车分组写口reconfigure补登-新增接口-管理后台.md index 85b1d4f0..77f8cd44 100644 --- a/changelogs-v2/2026-09/19_7442_团期配车分组写口reconfigure补登-新增接口-管理后台.md +++ b/changelogs-v2/2026-09/19_7442_团期配车分组写口reconfigure补登-新增接口-管理后台.md @@ -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\ | **恒为空列表**（见「⚠️ 关键变化」第 4 条），不要依赖它判断缺组 | | coverage.wholeBatchSatisfied | Boolean | 全团行程日整体覆盖是否成立 | | legacyGroupRowCount | Integer | 本团存活派车行里无分组键的历史行数（非错误，仅留痕，见 #7442 AC-32） | +| releasedShareGroupIds | Array\ | 🔴 **【#7444 追加，2026-09-19 补列】** 本次被解除的车辆共用关系 ID | +| keptSourceIds | Array\ | 🔴 **【#7444 追加】** 按 `survivorPolicy` 判定为保留的幸存派单 `sourceId` | +| releasedSourceIds | Array\ | 🔴 **【#7444 追加】** 按 `survivorPolicy` 判定为释放的派单 `sourceId` | +| pendingReassignSourceIds | Array\ | 🔴 **【#7444 追加】** 待重新改派的派单 `sourceId` | + +> ⚠️ 上面 4 个出参字段同 `survivorPolicy`，由 #7444 追加，**完整语义见 +> `19_7444_团期配车就绪门禁与车辆共用关系-修改接口-管理后台.md`**，本文档只补列字段名与出处。 #### 请求示例 diff --git a/changelogs-v2/2026-09/19_7442_团期配车受控重开窗口计划刷新状态收口-新增接口-管理后台.md b/changelogs-v2/2026-09/19_7442_团期配车受控重开窗口计划刷新状态收口-新增接口-管理后台.md index d561fc66..5553a7ad 100644 --- a/changelogs-v2/2026-09/19_7442_团期配车受控重开窗口计划刷新状态收口-新增接口-管理后台.md +++ b/changelogs-v2/2026-09/19_7442_团期配车受控重开窗口计划刷新状态收口-新增接口-管理后台.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` 在本端点才有非空的可能，其余端点（重配写口）的同名字段在任何路径上都只能是空列表——两处含义不同，前端渲染缺口清单只能信本端点