docs: 订单出行人编辑调错接口导致参数类型错误+主表误改(前端需修)

changelogs/2026-04/2026-04-22_mp-order-traveler-edit-wrong-endpoint-frontend-fix.md

@@ -0,0 +1,97 @@
+# [前端 BUG · 需前端修] 订单里编辑出行人调错接口导致"参数类型错误: id"+主表被误改
+
+> **归属**: 前端
+> **日期**: 2026-04-22
+> **报告人**: wx (后端)
+> **优先级**: P1
+
+## 现象
+
+小程序 **订单详情 → 出行人列表 → 点编辑 → 保存** 时:
+1. 红字 toast: **"参数类型错误: id"**
+2. 部分场景下用户反馈"订单的出行人"和"实际出行人(常用出行人地址簿)"都被修改
+
+## 根因 (后端三尺实证已确认)
+
+### 根因 1: 调错接口
+
+本项目有两个完全独立的"出行人"接口,语义不同:
+
+| 接口 | 改的表 | 语义 | 适用场景 |
+|------|--------|------|---------|
+| `PUT /mp/user/traveler/{id}` | `traveler` (用户地址簿主表) | 长期维护的常用出行人 | **个人中心 → 常用出行人** 页面 |
+| `PUT /mp/order/{orderId}/traveler/{travelerId}` | `order_traveler` (订单快照表) | 下单快照,不影响主表 | **订单详情 → 出行人** 页面 |
+
+目前"订单里编辑出行人"页面调的是 `/mp/user/traveler/{id}`(主表接口),**调用目标错了**。
+
+### 根因 2: `id` 为 undefined/null/对象
+
+`/mp/user/traveler/{id}` 的路径参数 `id` 是 `Long` 类型,Spring 解析失败即报 "参数类型错误: id"。
+说明前端在构造 URL 时 `id` 传入了 `undefined` / `null` / 非数字字符串,URL 变成 `/mp/user/traveler/undefined` 被后端 `MethodArgumentTypeMismatchException` 拦截。
+
+### 为什么会"双改"
+
+- 调了主表接口 → 地址簿被改
+- 订单详情里的出行人如果从主表 join 展示姓名/证件,看起来"订单出行人也变了"
+
+(后端代码已核查: `OrderTravelerService.updateTraveler` 只动 `order_traveler`,`MpTravelerController.updateTraveler` 只动 `traveler`。双方都是快照/主表独立维护,没有任何一个后端方法"双改"两张表。)
+
+## 前端修复要求
+
+### 1. 订单出行人编辑页统一走订单快照接口
+
+**旧 (错)**:
+```js
+PUT /mp/user/traveler/{id}           // id = orderTravelerId (不对口)
+                                     // 或 id = undefined (参数类型错误)
+```
+
+**新 (对)**:
+```js
+PUT /mp/order/{orderId}/traveler/{travelerId}
+  body: MpOrderTravelerSaveReqVO {
+    name, idCardType, idCardNo, phone, gender, birthday,
+    travelerType, nationality, emergencyContact, emergencyPhone, email
+  }
+```
+
+- `orderId`: 当前订单 ID
+- `travelerId`: 从 `GET /mp/order/{orderId}/traveler` 返回的 `TravelerVO.travelerId`(就是 `order_traveler.order_traveler_id`)
+- 不要 fallback 到"常用出行人 id"
+
+### 2. 保存按钮点击前校验 `travelerId` 存在
+
+构造 URL 前 `if (!travelerId) { return uni.showToast('出行人 ID 缺失') }`,禁止 `undefined` 进 URL。
+
+### 3. 区分两个"编辑出行人"入口
+
+| 入口页面 | 调用接口 |
+|---------|---------|
+| 个人中心 → 我的出行人 → 编辑 | `PUT /mp/user/traveler/{id}` |
+| 订单详情 → 出行人 → 编辑 | `PUT /mp/order/{orderId}/traveler/{travelerId}` |
+
+两个入口**必须**用对应的接口,不可共用同一个 API 调用。
+
+## 相关接口
+
+### 订单出行人 (本次要改的目标接口)
+
+- `GET /mp/order/{orderId}/traveler` — 查询订单出行人列表
+  返回 `List<TravelerVO>`,其中 `travelerId` 就是 `order_traveler.order_traveler_id`
+- `POST /mp/order/{orderId}/traveler` — 新增订单出行人
+- **`PUT /mp/order/{orderId}/traveler/{travelerId}`** — **修改订单出行人 (null 字段保持原值)**
+- `DELETE /mp/order/{orderId}/traveler/{travelerId}` — 删除订单出行人
+
+所有字段语义见 `MpOrderTravelerSaveReqVO`,与 `MpTravelerRequest` 字段名对齐,Jackson 透传。
+
+### 用户常用出行人 (只用于"个人中心 → 我的出行人")
+
+- `GET /mp/user/traveler` — 列表
+- `POST /mp/user/traveler` — 新增
+- `PUT /mp/user/traveler/{id}` — 改主表
+- `DELETE /mp/user/traveler/{id}` — 删主表
+- `PUT /mp/user/traveler/{id}/default` — 设为默认
+
+## 后端无改动
+
+本次后端代码、DB、VO 均无变更。