305 行
9.7 KiB
Markdown
305 行
9.7 KiB
Markdown
# 【新增接口·管理后台】确认行程专用接口 (#4867)
|
||
|
||
> **PR**: #4868 | **服务**: hl-order-service-v3 | **更新时间**: 2026-07-09
|
||
|
||
## 1. 接口背景
|
||
|
||
管理后台确认行程不再对接通用状态机接口。前端现在使用确认行程专用接口，只表达“确认行程”以及可选的主报账人调整。
|
||
|
||
## 2. 变更清单
|
||
|
||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||
|---|------|------|------|----------|------|
|
||
| 1 | 确认行程 | POST | `/v3/admin/order/{orderId}/confirm-itinerary` | 新增接口 | 前端只传可选 `reporterAssignmentId`；不再传 `eventCode`、`reason` |
|
||
|
||
## 3. 接口详情
|
||
|
||
### 3.1 确认行程
|
||
|
||
- **使用场景**：订单已进入待确认阶段，管理后台点击“确认行程”时调用。
|
||
- **认证**：需要管理后台登录态，Header 携带 `Authorization: Bearer <token>`。
|
||
- **幂等性**：不是幂等接口。订单确认成功后重复调用会返回状态不允许操作。
|
||
- **请求格式**：建议前端发送 `Content-Type: application/json`，body 传 `{}` 或包含 `reporterAssignmentId`。
|
||
|
||
## 4. 接口入参
|
||
|
||
### 4.1 路径参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `orderId` | String | 是 | 订单 ID。雪花 ID 建议按字符串传，避免 JS 精度丢失。 |
|
||
|
||
### 4.2 请求体字段
|
||
|
||
| 字段 | 类型 | 必填 | 说明 | 校验规则 |
|
||
|------|------|------|------|----------|
|
||
| `reporterAssignmentId` | String | 否 | 新的主报账人员 assignmentId。不传则沿用当前主报账人。 | 传入时必须是当前订单下的有效 staff assignment；不能是团期共享 staff。 |
|
||
|
||
前端不需要传以下字段：
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `eventCode` | 专用接口已固定为确认行程语义，不再由前端传。 |
|
||
| `reason` | 专用接口已固定确认行程原因，不再由前端传。 |
|
||
|
||
## 5. 出参（响应）
|
||
|
||
响应包装：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `code` | Number | 业务状态码，`200` 表示成功。 |
|
||
| `message` | String | 业务提示。成功时可能为空或为通用成功文案。 |
|
||
| `data` | Object | 确认行程结果；失败时通常为 `null`。 |
|
||
|
||
`data` 字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `success` | Boolean | 是否确认成功。 |
|
||
| `oldStatus` | String | 变更前粗状态，确认行程成功时通常为 `CUSTOMIZING`。 |
|
||
| `newStatus` | String | 变更后粗状态，确认行程成功时为 `PENDING_DEPARTURE`。 |
|
||
| `oldFlowStatus` | String | 变更前细状态，确认行程成功时通常为 `PENDING_CONFIRM`。 |
|
||
| `newFlowStatus` | String | 变更后细状态，确认行程成功时为 `PENDING_DEPARTURE`。 |
|
||
| `triggeredEvents` | Array<String> | 确认成功后触发的异步事项标识。当前可能包含 `ASYNC_CONTRACT_GENERATE`、`ASYNC_INSURANCE_ISSUE`。 |
|
||
|
||
## 6. 枚举 / 数据字典
|
||
|
||
### 6.1 `oldStatus` / `newStatus`
|
||
|
||
**所属字段**：`data.oldStatus`、`data.newStatus` | **类型**：String
|
||
|
||
| 值 | 中文 | 说明 |
|
||
|----|------|------|
|
||
| `PENDING_PAY` | 待支付 | 订单待支付。 |
|
||
| `CUSTOMIZING` | 定制中 | 订单处于资源配置/待确认前阶段。 |
|
||
| `PENDING_DEPARTURE` | 待出行 | 行程已确认，等待出行。 |
|
||
| `TRAVELLING` | 出行中 | 行程正在进行。 |
|
||
| `COMPLETED` | 已完成 | 订单已完成。 |
|
||
| `CANCELLED` | 已取消 | 订单已取消。 |
|
||
|
||
确认行程成功时，前端重点关注：
|
||
|
||
| 字段 | 成功前 | 成功后 |
|
||
|------|--------|--------|
|
||
| `oldStatus` / `newStatus` | `CUSTOMIZING` | `PENDING_DEPARTURE` |
|
||
|
||
### 6.2 `oldFlowStatus` / `newFlowStatus`
|
||
|
||
**所属字段**：`data.oldFlowStatus`、`data.newFlowStatus` | **类型**：String
|
||
|
||
| 值 | 中文 | 说明 |
|
||
|----|------|------|
|
||
| `PENDING_CONFIRM` | 待确认 | 资源与前置信息已满足，等待确认行程。 |
|
||
| `PENDING_DEPARTURE` | 待出行 | 行程已确认，等待出行。 |
|
||
|
||
确认行程成功时，前端重点关注：
|
||
|
||
| 字段 | 成功前 | 成功后 |
|
||
|------|--------|--------|
|
||
| `oldFlowStatus` / `newFlowStatus` | `PENDING_CONFIRM` | `PENDING_DEPARTURE` |
|
||
|
||
### 6.3 `triggeredEvents`
|
||
|
||
**所属字段**：`data.triggeredEvents` | **类型**：Array<String>
|
||
|
||
| 值 | 中文 | 说明 |
|
||
|----|------|------|
|
||
| `ASYNC_CONTRACT_GENERATE` | 异步生成合同 | 确认行程后可能触发合同相关事项。 |
|
||
| `ASYNC_INSURANCE_ISSUE` | 异步投保 | 确认行程后可能触发保险相关事项。 |
|
||
|
||
## 7. 错误码
|
||
|
||
| code | 含义 | 触发场景 |
|
||
|------|------|----------|
|
||
| `401` | 未登录或登录态无效 | 未携带有效 `Authorization`。 |
|
||
| `581007` | 订单不存在 | `orderId` 不存在或已删除。 |
|
||
| `581016` | 当前订单状态不允许该操作 | 订单不处于可确认状态，例如已确认后重复调用。 |
|
||
| `581036` | 确认订单前置校验未通过 | checklist 未全部通过。 |
|
||
| `581046` | `reporterAssignmentId` 格式非法 | `reporterAssignmentId` 无法识别为有效数字 ID。 |
|
||
| `582102` | 员工分配记录不存在 | `reporterAssignmentId` 不存在，或不属于当前订单。 |
|
||
| `582109` | 团期共享 staff 不可在订单侧增删改 | `reporterAssignmentId` 指向团期共享 staff。 |
|
||
|
||
## 8. 示例（典型 / 边界 / 异常）
|
||
|
||
### 8.1 典型成功：不调整主报账人
|
||
|
||
**请求**：
|
||
|
||
```http
|
||
POST /v3/admin/order/2072930557464899585/confirm-itinerary
|
||
Authorization: Bearer <token>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
```json
|
||
{}
|
||
```
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"success": true,
|
||
"oldStatus": "CUSTOMIZING",
|
||
"newStatus": "PENDING_DEPARTURE",
|
||
"oldFlowStatus": "PENDING_CONFIRM",
|
||
"newFlowStatus": "PENDING_DEPARTURE",
|
||
"triggeredEvents": [
|
||
"ASYNC_CONTRACT_GENERATE",
|
||
"ASYNC_INSURANCE_ISSUE"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.2 边界成功：确认时指定新的主报账人
|
||
|
||
**请求**：
|
||
|
||
```http
|
||
POST /v3/admin/order/2072930323661811714/confirm-itinerary
|
||
Authorization: Bearer <token>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
```json
|
||
{
|
||
"reporterAssignmentId": "2072930358709415938"
|
||
}
|
||
```
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"success": true,
|
||
"oldStatus": "CUSTOMIZING",
|
||
"newStatus": "PENDING_DEPARTURE",
|
||
"oldFlowStatus": "PENDING_CONFIRM",
|
||
"newFlowStatus": "PENDING_DEPARTURE",
|
||
"triggeredEvents": [
|
||
"ASYNC_CONTRACT_GENERATE",
|
||
"ASYNC_INSURANCE_ISSUE"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.3 异常：重复确认
|
||
|
||
**请求**：
|
||
|
||
```http
|
||
POST /v3/admin/order/2072930557464899585/confirm-itinerary
|
||
Authorization: Bearer <token>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
```json
|
||
{}
|
||
```
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"code": 581016,
|
||
"message": "当前订单状态不允许该操作",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 8.4 异常：前置 checklist 未通过
|
||
|
||
**请求**：
|
||
|
||
```http
|
||
POST /v3/admin/order/2072930000000000000/confirm-itinerary
|
||
Authorization: Bearer <token>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
```json
|
||
{}
|
||
```
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"code": 581036,
|
||
"message": "确认订单前置校验未通过，请先补全所有必填项",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## 9. 业务边界
|
||
|
||
- 仅用于“确认行程”动作，不用于取消、支付、出发、完成、终止等其他状态变更。
|
||
- 订单需要处于可确认阶段；确认成功后会进入待出行阶段。
|
||
- 确认前置 checklist 需要全部通过，包括付款、出行人信息、配房、配车、合同方案等必要项。
|
||
- `reporterAssignmentId` 不传时，当前主报账人保持不变。
|
||
- `reporterAssignmentId` 传入时，会把该 staff assignment 设为主报账人；原主报账人会被降为非主报账人。
|
||
- 已确认订单重复调用会返回 `581016`，前端不要把它当作成功。
|
||
|
||
## 10. 修改前后对比
|
||
|
||
本次是新增专用接口，同时替代前端确认行程时使用通用状态机接口的对接方式。
|
||
|
||
### 10.1 调用方式对比
|
||
|
||
| 项 | 修改前 | 修改后 |
|
||
|----|--------|--------|
|
||
| 前端确认行程接口 | `POST /v3/admin/order/{orderId}/transition` | `POST /v3/admin/order/{orderId}/confirm-itinerary` |
|
||
| 前端是否传 `eventCode` | 需要传 `CONFIRM` | 不传 |
|
||
| 前端是否传 `reason` | 可传或由调用方组织 | 不传 |
|
||
| 前端是否可调整主报账人 | 通过通用 payload 表达 | 只传可选 `reporterAssignmentId` |
|
||
|
||
### 10.2 请求体对比
|
||
|
||
| 场景 | 修改前 | 修改后 |
|
||
|------|--------|--------|
|
||
| 不调整报账人 | `{"eventCode":"CONFIRM"}` | `{}` |
|
||
| 调整报账人 | `{"eventCode":"CONFIRM","payload":{"reporterAssignmentId":"2072930358709415938"}}` | `{"reporterAssignmentId":"2072930358709415938"}` |
|
||
|
||
## 11. 影响评估 / 回滚
|
||
|
||
### 11.1 影响评估
|
||
|
||
- **是否破坏向后兼容**：否。新增接口不删除既有响应字段。
|
||
- **前端是否必须同步上线**：建议管理后台确认行程入口切到新接口，避免继续依赖通用状态机接口。
|
||
- **影响已有数据**：不需要数据迁移。
|
||
|
||
### 11.2 回滚方案
|
||
|
||
- 若新接口不可用，前端可临时回退到原通用状态机接口调用方式。
|
||
- 回滚后请继续确保确认行程前置 checklist 已通过。
|
||
|
||
## 12. 注意事项
|
||
|
||
- 前端发送空请求体时，建议发送 `{}` 并设置 `Content-Type: application/json`。
|
||
- 不要再在确认行程页面拼 `eventCode=CONFIRM` 或 `reason`。
|
||
- `reporterAssignmentId` 是订单 staff assignment 的 ID，不是员工 ID。
|
||
- 雪花 ID 建议按字符串处理，避免 JS Number 精度丢失。
|
||
- 通用 `/transition` 不再作为管理后台确认行程的对接入口。
|
||
|
||
## 13. 关联 / 联系人
|
||
|
||
### 13.1 链接
|
||
|
||
- **Issue**: [#4867](https://git.1814.love:8443/wx/HL/issues/4867)
|
||
- **PR**: [#4868](https://git.1814.love:8443/wx/HL/pulls/4868)
|
||
- **Merge commit**: [c772d83e7](https://git.1814.love:8443/wx/HL/commit/c772d83e7)
|
||
|
||
### 13.2 联系人
|
||
|
||
- **后端负责人**: @yst
|
||
- **前端对接**: 管理后台前端
|