From 1c5279f32767460eeac07221729954db49da858d Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Sun, 13 Sep 2026 15:01:15 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#7439=20=E5=AF=B9=E5=A4=96?= =?UTF-8?q?=E5=88=86=E5=86=8C=E8=A1=A5=E9=BD=90=20809001/809007=20?= =?UTF-8?q?=E5=A4=84=E7=BD=AE=E5=8F=A3=E5=BE=84=E4=B8=8E=E3=80=8C=E5=BB=BA?= =?UTF-8?q?=E8=AE=AE=E6=98=BE=E5=BC=8F=E4=BC=A0=20kind=E3=80=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 两处是交接件自身的缺口，不是实现问题： 1. 809001（同单同 kind 重复/并发提交）此前只作为 JSON 示例出现，没有前端处置口径， 而本文件错误码表的前提就是「每个码配一条处置口径——码本身不够，处置动作错了 照样是线上问题」。补的处置口径关键是「不要自动重试」：只要那条活跃需求还在， 重试永远是这个码。 2. 809007 此前只在内部分册。它确实是 fleet 消费侧的码、前端拿不到，但错误码段位 在交接件里应当完整，且它与 809002 的分工需要说清（809002=提交时派生不出来， 前端可引导补大交通；809007=提交时没派生、事后被消费，属存量回填，前端无动作）。 补上之后，「交接件含 6 个错误码」在「两册之和」与「mmg 实际拿到的那一份」 两种读法下都成立，不必再去裁哪种读法对。 3. 「不传 kind 按 TRAVEL 处理，现网代码可不改但建议显式传」此前只写在内部分册， 而内部分册的收件人是后端与 fleet 侧、不是 mmg。已补进对外分册的影响评估与 端点1 入参表，并写明为什么值得显式传：一旦该订单出现两类活跃需求，「不传」 的语义就从「就是行程用车」变成「碰巧落到行程用车上」，两者在代码里长得一样。 校验：六个码（809000/809001/809002/809007/809008/809009）在对外册均为行首表格行 各 1 行；退役号 809003-809006 阴性对照各 0 命中；endpoint-count 仍为 7 / 4。 --- .../13_7439_团期车务地基-用车需求分家-修改接口-管理后台.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/changelogs-v2/2026-09/13_7439_团期车务地基-用车需求分家-修改接口-管理后台.md b/changelogs-v2/2026-09/13_7439_团期车务地基-用车需求分家-修改接口-管理后台.md index 4bad95c5..6b5b9478 100644 --- a/changelogs-v2/2026-09/13_7439_团期车务地基-用车需求分家-修改接口-管理后台.md +++ b/changelogs-v2/2026-09/13_7439_团期车务地基-用车需求分家-修改接口-管理后台.md @@ -78,7 +78,7 @@ base: "dev-v3" | 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | |------|------|------|------|------|------| | id | Path | Long | ✅ | - | 订单 ID | -| kind | Body | String | ❌ | TRAVEL/TRANSFER | 需求类型，默认 TRAVEL；非法值实际返 400（Bean Validation 拦截，不是 809000，见下方错误响应说明） | +| kind | Body | String | ❌ | TRAVEL/TRANSFER | 需求类型，不传按 TRAVEL 处理（**建议显式传**，理由见六.7 影响评估）；非法值实际返 400（Bean Validation 拦截，不是 809000，见下方错误响应说明） | | fleet | Body | List | ✅ | @NotEmpty | 车型配置，两类需求都必填 | | pickupRequired | Body | Boolean | ❌ | - | 需接机 | | dropoffRequired | Body | Boolean | ❌ | - | 需送机 | @@ -691,7 +691,9 @@ GET /v3/admin/order/60123456789013/settlement/step3/vehicles | 错误码 | 触发条件 | 🖐 前端该怎么处置 | |--------|----------|------------------| | **809000** | `kind` 传了 TRAVEL / TRANSFER 之外的值 | 参数错误，按常规表单校验处理；正常调用不该出现 | +| **809001** | 同一订单**同一 kind** 已存在活跃需求时又提交了一条（重复提交 / 并发双击） | ⚠️ **不要自动重试**——只要那条活跃需求还在，重试永远是这个码。提示「该订单已有进行中的用车需求」并引导去看板刷新确认；需求被打回或完成后才能再提 | | **809002** | 提交 `TRANSFER`，但该单**大交通信息为空**，服务日派生不出来 | ⚠️ **不要提示「参数错误」或「稍后重试」**——这是数据缺口，必须给「**先去补大交通**」的引导，最好直接给一个跳到大交通填写页的入口。重试不会变好，补完大交通再提交才会好 | +| **809007** | 接送机需求的 `service_dates` 为空时被下游消费（存量迁移行未回填即被取用） | **前端拿不到这个码**——它在 `/v3/internal` 链路上由 fleet 侧触发，不经 `/v3/admin`。列在这里是为了错误码段位完整，以及说明它与 809002 的分工：**809002 = 提交时派生不出来**（前端可引导补大交通），**809007 = 提交时没派生、事后被消费**（属存量数据回填问题，需后端处理，前端无动作）。详见内部接口分册端点 3 | | **809008** | 该单**两类活跃需求并存**时，手录车费行没指定 `requirementKind` | 表单必填校验漏了；把该字段做成必选（两类并存时）即可 | | **809009** | 提交 `kind=TRANSFER`，而开关 `hl.order.requirement.transfer-kind-submit-enabled` **仍是默认的 false** | ⚠️ **按「功能未开放」提示**（例如「接送机需求提交尚未开放」），**不得**按参数错误处理、**也不得**提示「稍后重试」——开关不开，重试多少次都是这个码。本单交付时该开关就是关的，所以这是**当前的正常返回**，不是故障 | @@ -726,7 +728,7 @@ GET /v3/admin/order/60123456789013/settlement/step3/vehicles ## 六.7、影响评估 -- **向后兼容性**：部分。不传 kind 时按 TRAVEL 处理，但双需求时手录行必须指定 +- **向后兼容性**：部分。不传 kind 时服务端按 `TRAVEL` 处理，**现网代码可以不改**；但**建议 hl-ui 一律显式传 kind**——一旦该订单出现两类活跃需求，「不传」的语义就从「就是行程用车」变成了「碰巧落到行程用车上」，而这两者在代码里长得一模一样。双需求时手录行的 `requirementKind` 则是**必须**指定（缺失返 809008） - **前端同步上线**：是 ---