diff --git a/changelogs-v2-mp/2026-06/21_4154_出行人补全订单确认后禁止mp编辑-修改接口-小程序端.md b/changelogs-v2-mp/2026-06/21_4154_出行人补全订单确认后禁止mp编辑-修改接口-小程序端.md new file mode 100644 index 0000000..0f83ee3 --- /dev/null +++ b/changelogs-v2-mp/2026-06/21_4154_出行人补全订单确认后禁止mp编辑-修改接口-小程序端.md @@ -0,0 +1,65 @@ +# 【修改接口·小程序端】客户出行人补全:订单确认后禁止 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