docs(changelog): #7439 对外分册补齐 809001/809007 处置口径与「建议显式传 kind」
changelog-filename-gate / validate (push) Failing after 2s
changelog-filename-gate / validate (push) Failing after 2s
两处是交接件自身的缺口,不是实现问题: 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。
这个提交包含在:
@@ -78,7 +78,7 @@ base: "dev-v3"
|
|||||||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||||||
|------|------|------|------|------|------|
|
|------|------|------|------|------|------|
|
||||||
| id | Path | Long | ✅ | - | 订单 ID |
|
| 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<FleetItem> | ✅ | @NotEmpty | 车型配置,两类需求都必填 |
|
| fleet | Body | List<FleetItem> | ✅ | @NotEmpty | 车型配置,两类需求都必填 |
|
||||||
| pickupRequired | Body | Boolean | ❌ | - | 需接机 |
|
| pickupRequired | Body | Boolean | ❌ | - | 需接机 |
|
||||||
| dropoffRequired | Body | Boolean | ❌ | - | 需送机 |
|
| dropoffRequired | Body | Boolean | ❌ | - | 需送机 |
|
||||||
@@ -691,7 +691,9 @@ GET /v3/admin/order/60123456789013/settlement/step3/vehicles
|
|||||||
| 错误码 | 触发条件 | 🖐 前端该怎么处置 |
|
| 错误码 | 触发条件 | 🖐 前端该怎么处置 |
|
||||||
|--------|----------|------------------|
|
|--------|----------|------------------|
|
||||||
| **809000** | `kind` 传了 TRAVEL / TRANSFER 之外的值 | 参数错误,按常规表单校验处理;正常调用不该出现 |
|
| **809000** | `kind` 传了 TRAVEL / TRANSFER 之外的值 | 参数错误,按常规表单校验处理;正常调用不该出现 |
|
||||||
|
| **809001** | 同一订单**同一 kind** 已存在活跃需求时又提交了一条(重复提交 / 并发双击) | ⚠️ **不要自动重试**——只要那条活跃需求还在,重试永远是这个码。提示「该订单已有进行中的用车需求」并引导去看板刷新确认;需求被打回或完成后才能再提 |
|
||||||
| **809002** | 提交 `TRANSFER`,但该单**大交通信息为空**,服务日派生不出来 | ⚠️ **不要提示「参数错误」或「稍后重试」**——这是数据缺口,必须给「**先去补大交通**」的引导,最好直接给一个跳到大交通填写页的入口。重试不会变好,补完大交通再提交才会好 |
|
| **809002** | 提交 `TRANSFER`,但该单**大交通信息为空**,服务日派生不出来 | ⚠️ **不要提示「参数错误」或「稍后重试」**——这是数据缺口,必须给「**先去补大交通**」的引导,最好直接给一个跳到大交通填写页的入口。重试不会变好,补完大交通再提交才会好 |
|
||||||
|
| **809007** | 接送机需求的 `service_dates` 为空时被下游消费(存量迁移行未回填即被取用) | **前端拿不到这个码**——它在 `/v3/internal` 链路上由 fleet 侧触发,不经 `/v3/admin`。列在这里是为了错误码段位完整,以及说明它与 809002 的分工:**809002 = 提交时派生不出来**(前端可引导补大交通),**809007 = 提交时没派生、事后被消费**(属存量数据回填问题,需后端处理,前端无动作)。详见内部接口分册端点 3 |
|
||||||
| **809008** | 该单**两类活跃需求并存**时,手录车费行没指定 `requirementKind` | 表单必填校验漏了;把该字段做成必选(两类并存时)即可 |
|
| **809008** | 该单**两类活跃需求并存**时,手录车费行没指定 `requirementKind` | 表单必填校验漏了;把该字段做成必选(两类并存时)即可 |
|
||||||
| **809009** | 提交 `kind=TRANSFER`,而开关 `hl.order.requirement.transfer-kind-submit-enabled` **仍是默认的 false** | ⚠️ **按「功能未开放」提示**(例如「接送机需求提交尚未开放」),**不得**按参数错误处理、**也不得**提示「稍后重试」——开关不开,重试多少次都是这个码。本单交付时该开关就是关的,所以这是**当前的正常返回**,不是故障 |
|
| **809009** | 提交 `kind=TRANSFER`,而开关 `hl.order.requirement.transfer-kind-submit-enabled` **仍是默认的 false** | ⚠️ **按「功能未开放」提示**(例如「接送机需求提交尚未开放」),**不得**按参数错误处理、**也不得**提示「稍后重试」——开关不开,重试多少次都是这个码。本单交付时该开关就是关的,所以这是**当前的正常返回**,不是故障 |
|
||||||
|
|
||||||
@@ -726,7 +728,7 @@ GET /v3/admin/order/60123456789013/settlement/step3/vehicles
|
|||||||
|
|
||||||
## 六.7、影响评估
|
## 六.7、影响评估
|
||||||
|
|
||||||
- **向后兼容性**:部分。不传 kind 时按 TRAVEL 处理,但双需求时手录行必须指定
|
- **向后兼容性**:部分。不传 kind 时服务端按 `TRAVEL` 处理,**现网代码可以不改**;但**建议 hl-ui 一律显式传 kind**——一旦该订单出现两类活跃需求,「不传」的语义就从「就是行程用车」变成了「碰巧落到行程用车上」,而这两者在代码里长得一模一样。双需求时手录行的 `requirementKind` 则是**必须**指定(缺失返 809008)
|
||||||
- **前端同步上线**:是
|
- **前端同步上线**:是
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|||||||
在新工单中引用
屏蔽一个用户