66 行
4.3 KiB
Markdown
66 行
4.3 KiB
Markdown
# 【修改接口·小程序端】客户出行人补全：订单确认后禁止 mp 端编辑（新增门禁 + 错误码 581145）(CR)
|
||
|
||
> **PR**: #4154 | **服务**: hl-order-service-v3 | **更新时间**: 2026-06-21
|
||
|
||
## 1. 接口背景
|
||
|
||
小程序客户出行人补全接口（batch-edit）此前**未在后端强制限制可编辑的订单阶段**：客户端只要订单属于本人，任意阶段都能提交编辑。本次安全/一致性收紧：**仅订单确认前（待支付 / 定制中）允许经小程序编辑出行人；订单确认后（待出行起）及已完成 / 已取消一律拒绝**，返回新错误码 `581145`。
|
||
|
||
收紧原因：订单确认后修改出行人 PII（姓名 / 手机 / 生日等）会误触发后端「合同作废重签 + 退保重投保」链路，造成非预期的合同与保单churn。证件号此前已在签约后冻结，本次把整个编辑动作按订单阶段收口。
|
||
|
||
> 本次为行为收紧（破坏性变更面向「确认后仍调用」的旧逻辑）。按产品生命周期，出行人补全本就发生在「待补全信息」窗口（定制中阶段），正常流程不受影响。
|
||
|
||
## 2. 变更清单
|
||
|
||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||
|---|------|------|------|----------|------|
|
||
| 1 | 客户出行人补全 | POST | /v3/internal/mp/order/{id}/traveler/batch-edit | 行为收紧 | 订单非「待支付/定制中」阶段调用直接拒绝（581145）；入参 / 出参结构不变 |
|
||
|
||
## 3. 关键说明
|
||
|
||
- **放行阶段（白名单）**：`order_status ∈ {PENDING_PAY 待支付, CUSTOMIZING 定制中}`。
|
||
- **拒绝阶段**：`PENDING_DEPARTURE 待出行（确认后）/ TRAVELLING 出行中 / COMPLETED 已完成 / CANCELLED 已取消`，以及任何其他状态（白名单 fail-closed）。
|
||
- 拒绝时**整单不写入**（事务回滚），返回 `code=581145`。
|
||
- 入参字段、出参 VO 结构**完全不变**，仅新增前置阶段校验。
|
||
- 本门禁**只约束小程序（mp）路径**；定制师 / admin 后台路径不受限（如需确认后变更出行人，请走定制师后台）。
|
||
|
||
## 4. 入参 / 出参
|
||
|
||
入参（请求体 travelers[] + 路径 id）与响应 VO **均不变**，详见既有文档（如 #3976 出行人补全契约）。本次仅在订单阶段不满足时提前抛 581145。
|
||
|
||
## 5. 错误码
|
||
|
||
| code | 含义 | 触发场景 | 本次 |
|
||
|------|------|----------|------|
|
||
| **581145** | 订单已确认，出行人信息不可再经小程序修改，如需变更请联系定制师 | 订单 status 不在 {待支付, 定制中} 白名单（即确认后 / 已完成 / 已取消）时调用 batch-edit | **新增** |
|
||
| 581102 | 订单不存在，无法编辑出行人 | orderId 无效 | 不变 |
|
||
| 581122 | 订单不属于当前用户 | 当前登录 userId 与订单归属不一致（横向越权拦截） | 不变 |
|
||
|
||
## 6. 前端处理建议
|
||
|
||
- 出行人编辑入口建议按订单状态控制：仅在「待支付 / 定制中（待补全信息）」展示可编辑表单；订单确认后置为只读。
|
||
- 若仍调用 batch-edit 命中 581145，按 message 文案提示用户「订单已确认，如需修改出行人请联系定制师」，不要静默失败。
|
||
- 正常按生命周期编辑（确认前补全）的前端流程**无需改动**。
|
||
|
||
## 7. 业务边界
|
||
|
||
- 适用：订单 `order_status = PENDING_PAY` 或 `CUSTOMIZING`，且出行人属本人订单（581122 越权拦截照旧）。
|
||
- 不适用：订单确认后（PENDING_DEPARTURE 起）/ 已完成 / 已取消 —— 一律 581145 拒绝。
|
||
- 证件号（idNo）在合同已签（contract_status=SIGNED）时本就冻结（581111），本次门禁覆盖范围更靠前（按订单阶段整体拦截）。
|
||
|
||
## 8. 影响评估 / 回滚
|
||
|
||
- **向后兼容**：对「确认前编辑」的正常流程兼容；对「确认后仍调用 batch-edit」的旧行为为破坏性收紧（此前会误触发重签，属应修缺陷）。
|
||
- **小程序是否必须同步上线**：建议同步——确认后隐藏 / 禁用编辑入口 + 处理 581145 文案；不同步也不会造成数据错误（后端已兜底拒绝）。
|
||
- **回滚**：revert PR #4154 重新部署 hl-order-service-v3，恢复不限阶段编辑的旧行为。
|
||
|
||
## 9. 关联 / 联系人
|
||
|
||
### 9.1 链接
|
||
|
||
- **PR**: [#4154](https://git.1814.love:8443/wx/HL/pulls/4154)（CR 发现，无关联 Issue）
|
||
|
||
### 9.2 联系人
|
||
|
||
- **后端负责人**: @wx
|