wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

新增确认订单checklist删除actionPath变更说明

浏览代码
这个提交包含在：
yaosutu 2026-07-13 11:00:04 +08:00
父节点 20d782c02b
当前提交 61f23b9190
共有 1 个文件被更改，包括 290 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

290
changelogs-v2/2026-07/13_4941_确认订单checklist删除actionPath-修改接口-管理后台.md 普通文件
查看文件

@ -0,0 +1,290 @@
# 【修改接口 · 管理后台】确认订单 checklist 删除 actionPath 出参（#4941）
> **PR**: #4942
> **服务**: hl-order-service-v3
> **更新时间**: 2026-07-13
> **适用端**: 管理后台订单详情页
## 1. 接口背景
管理后台订单详情页点击“确认订单”时，会先调用确认订单前置 checklist 接口判断是否允许展示确认弹窗。
此前失败项 `items[]` 中返回 `actionPath`，但该字段只是后端拼接的弱跳转提示，前端实际应按 `items[].code` 自行映射补全入口。为避免前端误依赖后端路由字符串，本次删除 `items[].actionPath` 出参字段。
## 2. 变更清单
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 确认订单前置 checklist | GET | `/v3/admin/order/{orderId}/confirm-checklist` | 修改接口 | 出参删除 `items[].actionPath`；失败项继续返回 `code/checkName/passed/failReason` |
## 3. 接口详情
### 3.1 确认订单前置 checklist
- **路径**: `GET /v3/admin/order/{orderId}/confirm-checklist`
- **认证**: 管理后台登录态，Header 携带 `Authorization: Bearer <token>`
- **使用场景**: 订单详情页点击确认订单按钮后先调用。
- **核心语义**:
- `allPassed=true`: `items=null`，`preview` 有值，前端可展示确认弹窗。
- `allPassed=false`: `items` 有值，`preview=null`，前端展示失败项并按 `items[].code` 映射引导。
## 4. 入参
### 4.1 路径参数
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `orderId` | String | 是 | 订单 ID。雪花 ID 建议按字符串处理，避免前端数字精度丢失。 |
### 4.2 Query 参数
无。
### 4.3 请求体
无请求体。
## 5. 出参
### 5.1 通用响应包
| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | Number | 业务状态码，`200` 表示成功。 |
| `message` | String | 业务提示，成功时通常为 `成功`。 |
| `data` | Object | checklist 结果。 |
### 5.2 `data` 字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `allPassed` | Boolean | 是否全部通过。 |
| `items` | Array<Object> / null | 失败项明细；仅 `allPassed=false` 时返回数组，全部通过时为 `null`。 |
| `preview` | Object / null | 确认弹窗预览数据；仅 `allPassed=true` 时返回对象，未通过时为 `null`。 |
### 5.3 `items[]` 字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | String | 检查项代码。前端应按该字段映射补全入口。 |
| `checkName` | String | 检查项中文名称。 |
| `passed` | Boolean | 当前检查项是否通过。 |
| `failReason` | String / null | 未通过原因；通过时为 `null`。 |
> 本次删除字段：`items[].actionPath`。响应中不再出现该字段。
### 5.4 `preview` 字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `departureDate` | String | 出发日期，格式 `yyyy-MM-dd`。 |
| `totalPeopleCount` | Number | 总出行人数。 |
| `driverName` | String / null | 司机姓名。 |
| `driverPhoneMasked` | String / null | 司机手机号脱敏值。 |
| `hotels` | Array<Object> | 酒店摘要列表。 |
| `staffs` | Array<Object> | 本单配置人员列表。 |
| `contractAutoAction` | Object / null | 确认后合同自动处理预告。 |
| `insuranceAutoAction` | Object / null | 确认后保险自动处理预告。 |
## 6. 枚举 / 数据字典
### 6.1 `items[].code`
| 值 | 中文 | 说明 |
|----|------|------|
| `PAYMENT_OK` | 款项校验 | 订单需满足确认前支付要求。 |
| `TRAVELER_COMPLETE` | 出行人信息 | 出行人信息需完整。 |
| `HOTEL_DONE` | 房型安排 | 需要配房的订单必须已完成配房。 |
| `VEHICLE_DONE` | 用车安排 | 需要配车的订单必须已完成配车。 |
| `CONTRACT_TEMPLATE_OK` | 合同方案配置 | 产品需存在可用合同方案。 |
## 7. 错误码
| code | 含义 | 触发场景 |
|------|------|----------|
| `401` | 未登录或登录态无效 | 未携带有效 `Authorization`。 |
| `581007` | 订单不存在 | `orderId` 不存在或已删除。 |
| `581016` | 当前订单状态不允许该操作 | 订单不处于可确认状态。 |
| `581036` | 确认订单前置校验未通过 | 直接提交确认，但 checklist 未全部通过。 |
## 8. 示例
### 8.1 全部通过
**请求**
```http
GET /v3/admin/order/2076236236812345346/confirm-checklist
Authorization: Bearer <token>
```
**响应**
```json
{
"code": 200,
"message": "成功",
"data": {
"allPassed": true,
"items": null,
"preview": {
"departureDate": "2026-07-19",
"totalPeopleCount": 3,
"driverName": "测试司机",
"driverPhoneMasked": "1390000****",
"hotels": [
{
"cityName": "拉萨",
"hotelName": "测试酒店"
}
],
"staffs": [
{
"assignmentId": "2076236240000000001",
"staffId": "2076236240000000002",
"staffName": "张三",
"staffPhone": "1380000****",
"staffRole": "DRIVER",
"staffRoleName": "司机",
"isPrimaryReporter": true
}
],
"contractAutoAction": {
"planName": "标准国内电子签约方案",
"autoSign": true
},
"insuranceAutoAction": {
"planName": "测试境内意外险方案",
"peopleCount": 3,
"effectiveDescription": "出发前 24h 内生效"
}
}
}
}
```
### 8.2 未通过
**请求**
```http
GET /v3/admin/order/2072930000000000000/confirm-checklist
Authorization: Bearer <token>
```
**响应**
```json
{
"code": 200,
"message": "成功",
"data": {
"allPassed": false,
"items": [
{
"code": "TRAVELER_COMPLETE",
"checkName": "出行人信息",
"passed": false,
"failReason": "未添加出行人"
},
{
"code": "HOTEL_DONE",
"checkName": "房型安排",
"passed": false,
"failReason": "未提交用房需求"
}
],
"preview": null
}
}
```
### 8.3 直接提交确认但前置校验未通过
**请求**
```http
POST /v3/admin/order/2072930000000000000/confirm-itinerary
Authorization: Bearer <token>
Content-Type: application/json
```
```json
{}
```
**响应**
```json
{
"code": 581036,
"message": "确认订单前置校验未通过，请先补全所有必填项",
"data": null
}
```
## 9. 业务边界
1. 前端确认按钮流程仍是先调 `GET /confirm-checklist`，`allPassed=true` 后再调 `POST /confirm-itinerary`。
2. `allPassed=false` 时前端不要读 `preview`，只处理 `items[]`。
3. `items[].actionPath` 已删除，前端不要再读取该字段。
4. 失败项跳转或高亮入口由前端按 `items[].code` 自行映射。
## 10. 修改前后对比
### 10.1 字段级对比
| 字段 | 修改前 | 修改后 |
|------|--------|--------|
| `items[].actionPath` | String / null，失败时可能返回后端拼接的跳转路径 | 删除，不再返回 |
| `items[].code` | String，检查项代码 | 保持不变，作为前端映射依据 |
| `items[].checkName` | String，检查项中文名称 | 保持不变 |
| `items[].passed` | Boolean，是否通过 | 保持不变 |
| `items[].failReason` | String / null，失败原因 | 保持不变 |
### 10.2 示例对比
修改前：
```json
{
"code": "TRAVELER_COMPLETE",
"checkName": "出行人信息",
"passed": false,
"failReason": "未添加出行人",
"actionPath": "/admin/order/orders/2072930000000000000?tab=traveler"
}
```
修改后：
```json
{
"code": "TRAVELER_COMPLETE",
"checkName": "出行人信息",
"passed": false,
"failReason": "未添加出行人"
}
```
## 11. 影响评估 / 回滚
| 维度 | 影响 |
|------|------|
| 是否破坏向后兼容 | 是。依赖 `items[].actionPath` 的前端代码需要调整。 |
| 前端是否必须同步上线 | 如果当前前端读取 `items[].actionPath` 做跳转，则必须改为按 `items[].code` 映射。仅展示 `checkName/failReason` 的页面不受影响。 |
| 影响接口范围 | 仅 `GET /v3/admin/order/{orderId}/confirm-checklist`。 |
| 回滚方式 | 回滚 PR #4942 可恢复字段。 |
## 12. 注意事项
1. `items[].code` 是稳定映射字段，前端可按 `PAYMENT_OK / TRAVELER_COMPLETE / HOTEL_DONE / VEHICLE_DONE / CONTRACT_TEMPLATE_OK` 分别定位到对应补全区域。
2. 不要用 `checkName` 做逻辑判断；`checkName` 是展示文案。
3. `orderId` 建议继续按字符串处理。
## 13. 关联 / 联系人
- Issue #4941: https://git.1814.love:8443/wx/HL/issues/4941
- PR #4942: https://git.1814.love:8443/wx/HL/pulls/4942
- Merge commit: https://git.1814.love:8443/wx/HL/commit/10c120109d04bd21ab53a3af5baf03caa1116f42
- 负责人: 腰苏图