hl-api-changelog/changelogs-v2/2026-07/09_4867_确认行程专用接口-新增接口-管理后台.md

【新增接口·管理后台】确认行程专用接口 (#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	确认成功后触发的异步事项标识。当前可能包含 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

值	中文	说明
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 典型成功：不调整主报账人

请求：

POST /v3/admin/order/2072930557464899585/confirm-itinerary
Authorization: Bearer <token>
Content-Type: application/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 边界成功：确认时指定新的主报账人

请求：

POST /v3/admin/order/2072930323661811714/confirm-itinerary
Authorization: Bearer <token>
Content-Type: application/json

{
  "reporterAssignmentId": "2072930358709415938"
}

响应：

{
  "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 异常：重复确认

请求：

POST /v3/admin/order/2072930557464899585/confirm-itinerary
Authorization: Bearer <token>
Content-Type: application/json

{}

响应：

{
  "code": 581016,
  "message": "当前订单状态不允许该操作",
  "data": null
}

8.4 异常：前置 checklist 未通过

请求：

POST /v3/admin/order/2072930000000000000/confirm-itinerary
Authorization: Bearer <token>
Content-Type: application/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
• PR: #4868
• Merge commit: c772d83e7

13.2 联系人

• 后端负责人: @yst
• 前端对接: 管理后台前端