From 4c7d3f2773c8576c9a605e712b0db36ef25fbdc8 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Sat, 19 Sep 2026 03:34:37 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#7443=20=E8=AE=A2=E6=AD=A3?= =?UTF-8?q?=20PR-1=20=E6=96=87=E6=A1=A3=E7=9A=84=E9=94=99=E8=AF=AF?= =?UTF-8?q?=E7=A0=81=E5=88=A4=E5=AE=9A=EF=BC=8C=E5=B9=B6=E4=BF=AE=E6=8E=89?= =?UTF-8?q?=E4=B8=A4=E5=A4=84=E5=8F=91=E5=B8=83=E9=97=A8=E7=A6=81=E9=97=AE?= =?UTF-8?q?=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 一、内容订正（本次的主体） 原文「三个端点对 kind=TRANSFER 必现 605041」只对其中两个成立。 POST /requirements/{id}/confirm 实际返 605905（REQUIREMENT_VERSION_EXPIRED）—— 该端点有一道更早触发的版本预检 assertRequirementPreflightVersion （AssignmentService.java:3567-3583），请求根本走不到会抛 605041 的那一层。 另两个端点（POST /{assignmentId}/confirm、POST /{assignmentId}/change）描述准确。 订正以追加形式写在三处（关键变化 / 边界行为 / 影响面），原字面全部保留接 grep。 订正自身也标了边界：基于源码、未经网关复测。 二、frontend_status=not_required 的字段清理（门禁 E_FRONTEND_STATE） frontend_owner 与 verified_at 清空。not_required 条目不得保留前端负责人与验证时间， mmg 的判定与实测时间本来就已写在 status_note 里。 正文里原有一句引用了 frontmatter 的 verified_at，一并改写成不依赖该字段的表述， 避免留下指向空字段的悬挂引用。 三、五处悬挂文件名引用 订正文字里五处指向「18_7443_TRANSFER派车行确认改派基线复核修复-…」， 而那份 changelog 实际以 19_ 前缀成稿，且日前缀还会随实际推送日再变 （validate-changelog-filenames.mjs 用的是 new Date()，比的是校验运行当天、不是提交当天）。 统一改成「同目录《标题》（日前缀以实际推送日为准）」这种抗改名的写法。 门禁：validate-changelog-filenames.mjs 对本次变更 PASS（修改路径不进文件名门禁视野， 只校验新增路径）；validate-changelog-frontmatter.mjs 本文件零 error。 Refs #7443 --- ...叉PR1派车入参新增需求类别kind-修改接口-管理后台.md | 45 ++++++++++++++++++- 1 file changed, 43 insertions(+), 2 deletions(-) diff --git a/changelogs-v2/2026-09/18_7443_接送机用车需求分叉PR1派车入参新增需求类别kind-修改接口-管理后台.md b/changelogs-v2/2026-09/18_7443_接送机用车需求分叉PR1派车入参新增需求类别kind-修改接口-管理后台.md index 4678d095..3619fbc9 100644 --- a/changelogs-v2/2026-09/18_7443_接送机用车需求分叉PR1派车入参新增需求类别kind-修改接口-管理后台.md +++ b/changelogs-v2/2026-09/18_7443_接送机用车需求分叉PR1派车入参新增需求类别kind-修改接口-管理后台.md @@ -8,10 +8,10 @@ change_type: "修改接口" backend_status: "deployed" gateway_status: "verified" frontend_status: "not_required" -frontend_owner: "mmg" +frontend_owner: "" frontend_ref: "" target_release: "" -verified_at: "2026-09-18" +verified_at: "" status_note: "后端交付。派车批量与接送机配置入参新增可选 kind 字段；新增 4 个错误码（602200/602201/602202/602205）。[mmg 2026-09-18 判 not_required] kind 可选不传=TRAVEL，契约保证存量请求行为逐字一致。grep 实证：前端两处调用（src/api/fleet/board.js 的 POST /fleet/assignments/batch 与 PUT /fleet/assignments/pickup-dropoff-config）均不传 kind，全仓无 TRANSFER 派车入口；上游写口 809009 开关关闭，产品上产不出 TRANSFER 需求，4 个新错误码仅 kind=TRANSFER 触发、前端不可达；响应信封订正（code 即业务码、无 errorCode）与前端 request.js 拦截器透 message 惯例一致，无需改动。TRANSFER 开放后回头补：batch/pickup-dropoff-config 显式传 kind=TRANSFER、602205 给「先补大交通再重试」引导、TRANSFER 派车行确认/改派待 #7443 AC-24 修复后接入，已记入项目 memory。" updated_at: "2026-09-18" base: "dev-v3" @@ -55,6 +55,15 @@ base: "dev-v3" > （`POST /{assignmentId}/change`）三个端点内部的基线复核仍未做 kind 感知，必现 605041。 > 根因、影响面与跟踪单号见「六、边界行为」。**前端本版请只接「建接送机派车行」这一步， > 确认/改派暂缓接入，接了必然拿到 605041。** +> +> 🔧 **2026-09-18 订正（原文「三个端点……必现 605041」不准确，仅对其中两个成立）**：经源码 +> 复核，`POST /requirements/{id}/confirm` 端点对 `kind=TRANSFER` 需求实际抛出的是 +> **605905**（`REQUIREMENT_VERSION_EXPIRED`，"需求版本过期"）而不是 605041——该端点有一道 +> 更早触发的版本预检门禁 `assertRequirementPreflightVersion`（`AssignmentService.java:3567-3583`）， +> 请求根本走不到会抛 605041 的那一层。`POST /{assignmentId}/confirm` 与 +> `POST /{assignmentId}/change` 抛 605041 的描述准确。三个端点均已于当日随 AC-24 一并修复， +> 详见 同目录《#7443 TRANSFER 派车行确认改派基线复核修复-修改接口-管理后台》（**日前缀以实际推送日为准**，成稿时为 `19_`）。原字面保留在 +> 上方两行接 grep，不删除。 1. `BatchCreateAssignmentReqVO` 新增可选入参 `kind`（`TRAVEL`|`TRANSFER`，不传=`TRAVEL`） 2. `PickupDropoffConfigReqVO` 新增可选入参 `kind`（`TRAVEL`|`TRANSFER`，不传=`TRAVEL`） @@ -362,6 +371,7 @@ N/A（整批幂等覆盖，`items` 可传空数组表示"本次不新增任何 | `kind` 不传或传空字符串 | 按 `TRAVEL` 处理，行为与本次改动前逐字一致 | | `kind` 传非 `TRAVEL`/`TRANSFER` 值 | 400 参数校验失败（`@Pattern` 拦在入参层，不到业务码） | | `kind=TRANSFER` 派车行走「确认」`POST /requirements/{id}/confirm`、`POST /{assignmentId}/confirm`、「改派」`POST /{assignmentId}/change` | 返 605041（已知限制，三处内部基线复核未做 kind 感知，见「六、边界行为」），前端本版**暂不要接入**，只接「建接送机派车行」这一步 | +| 🔧 2026-09-18 订正 | 上一行「三处……返 605041」不准确：`POST /requirements/{id}/confirm` 实际返 **605905**，另两个端点返 605041 属实；三者均已随 AC-24 修复，详见「六、边界行为」订正与 同目录《#7443 TRANSFER 派车行确认改派基线复核修复-修改接口-管理后台》（**日前缀以实际推送日为准**，成稿时为 `19_`） | --- @@ -403,6 +413,29 @@ N/A（整批幂等覆盖，`items` 可传空数组表示"本次不新增任何 同步 Feign 的红线。已在 Gitea #7443 的 AC-24 登记，需单独设计（补齐三个命令对象的 kind 字段，或由 order-v3 在 `OrderFleetDetailContextDTO` 里一并带回 TRANSFER 那条需求）后再修， 属跨服务契约变更，本单不实现。**前端本版暂不要对接 TRANSFER 派车行的确认/改派操作。** +- 🔧 **2026-09-18 订正（原文首句「三个端点……必现 605041」不准确，仅对其中两个成立）**： + 经源码复核，上面这三个端点里，`POST /requirements/{id}/confirm`（`confirmRequirement`） + 对 `kind=TRANSFER` **实际可观测的报错是 605905**（`REQUIREMENT_VERSION_EXPIRED`，"需求版本 + 过期"），不是 605041——该端点在到达上文所述的 `assertFinalConfirmationBaseline` 之前，先有 + 一道版本预检门禁 `assertRequirementPreflightVersion`（`AssignmentService.java:3567-3583`）： + 该方法直接读 `preflightContext.getVehicleRequirement()`（恒 TRAVEL）与请求体里的 + `requirementId`（TRANSFER）比对，必不等，**请求根本走不到本条描述的那一层** + （`confirmRequirement` 自己内部对 `assertFinalConfirmationBaseline` 的调用点在 + `AssignmentService.java:3969`，理论上也会抛 605041，但 TRANSFER 请求永远到不了那一行）。 + `POST /{assignmentId}/confirm`（HOLDING 分支两处调用 `:4237-4238`/`:4270-4271`， + ASSIGNED 复核分支经 `revalidateAssignedAfterBaselineChange` 于 `:4452`）与 + `POST /{assignmentId}/change`（`doChangeInLock` 于 `:5794-5795`）抛 605041 的描述准确、 + 行号与上述一致（均取自 `origin/dev-v3` 当前源码，与本文档描述的状态一致）。三个端点已于 + 2026-09-18 随 AC-24 一并修复（fleet 侧新增 `baselineRequirementFor`、order-v3 侧 + `OrderFleetDetailContextDTO` 新增可空字段 `transferVehicleRequirement`），详见 + 同目录《#7443 TRANSFER 派车行确认改派基线复核修复-修改接口-管理后台》（**日前缀以实际推送日为准**，成稿时为 `19_`）。上方原字面保留接 grep， + 不删除。⚠️ **本条订正基于源码，未经网关复测**——2026-09-18 那轮网关实测覆盖的是原文描述的 + 主链路（`kind` 入参、四步前置、602200-602205 四个新错误码），**不含本条错误码判定**：当时 + 要么没覆盖 `confirmRequirement` 对 TRANSFER 需求的确认路径，要么覆盖了但记录时把码记错， + 两者哪个成立本条未查证。 + （原文此处引用过 frontmatter 的 `verified_at`，该字段已于 2026-09-19 按门禁要求清空—— + `frontend_status: not_required` 的条目不得保留验证时间，实测时间改由本段与 `status_note` + 承载。） - 与之相对：`POST /admin/fleet/assignments/batch`（本文档接口 1）的同一基线复核缺口已于 2026-09-18 修复（PR #7913，commit `5a6bd95f8`）——批量创建改传锁内按 kind 复核过的 `lockedRequirement` 做基线，`kind=TRANSFER` 批量创建不再必现 605041 @@ -457,6 +490,9 @@ N/A（整批幂等覆盖，`items` 可传空数组表示"本次不新增任何 - 车务确认执行 `POST /{assignmentId}/confirm`、按需求原子确认 `POST /requirements/{id}/confirm`、 改派 `POST /{assignmentId}/change`（三者 VO/入参本次均未改动；但 `kind=TRANSFER` 派车行走到 这三个端点目前必现 605041，是已知限制而非本次刻意变更，见「⚠️ 关键变化」与「六、边界行为」） + 🔧 **2026-09-18 订正**：确切地说，`POST /requirements/{id}/confirm` 必现的是 **605905** + 不是 605041（另两个端点 605041 属实），已随 AC-24 修复，见「六、边界行为」的订正段与 + 同目录《#7443 TRANSFER 派车行确认改派基线复核修复-修改接口-管理后台》（**日前缀以实际推送日为准**，成稿时为 `19_`） - 声明/撤销整段不用车 `POST|DELETE /requirements/{id}/no-vehicle` - 看板列表、矩阵日订单等查询接口 - `kind` 不传或=`TRAVEL` 时两端点的既有校验与落库路径 @@ -497,6 +533,11 @@ POST /requirements/{id}/confirm、POST /{assignmentId}/confirm、POST /{assignme 对 kind=TRANSFER 派车行的确认/改派 — 已知必现 605041，非本单验收范围 ``` +🔧 **2026-09-18 订正**：上面代码块第一行三个端点中，`POST /requirements/{id}/confirm` 已知必现 +的准确错误码是 **605905**，不是 605041（另两个端点 605041 属实）。三者均已随 AC-24 修复，详见 +同目录《#7443 TRANSFER 派车行确认改派基线复核修复-修改接口-管理后台》（**日前缀以实际推送日为准**，成稿时为 `19_`）。上方代码块原字面保留接 +grep，不删除。 + --- ## 十、相关文档