From 7e12f0e9cedbca1ef427a7e131445e92e97112d8 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Tue, 21 Apr 2026 16:38:19 +0800 Subject: [PATCH] =?UTF-8?q?changelog(mp):=20=E5=BE=AE=E4=BF=A1=E5=B0=8F?= =?UTF-8?q?=E7=A8=8B=E5=BA=8F=20=C2=B7=20=E8=AE=A2=E5=8D=95=E5=87=BA?= =?UTF-8?q?=E8=A1=8C=E4=BA=BA=20CRUD=20=E6=8E=A5=E5=8F=A3(4=20=E4=B8=AA)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - GET /mp/order/{orderId}/traveler - POST /mp/order/{orderId}/traveler - PUT /mp/order/{orderId}/traveler/{travelerId} - DELETE /mp/order/{orderId}/traveler/{travelerId} 对应原型 L4xYN 乘坐人员勾选列表、Bf9jC 添加人员弹窗。 身份证 idCardNo 后端自动解析 birthday + gender。 PR #1022 (Closes #1020) Co-Authored-By: Claude Opus 4.7 (1M context) --- .../2026-04-21_mp-order-traveler-crud.md | 206 ++++++++++++++++++ 1 file changed, 206 insertions(+) create mode 100644 changelogs/2026-04/2026-04-21_mp-order-traveler-crud.md diff --git a/changelogs/2026-04/2026-04-21_mp-order-traveler-crud.md b/changelogs/2026-04/2026-04-21_mp-order-traveler-crud.md new file mode 100644 index 0000000..434030b --- /dev/null +++ b/changelogs/2026-04/2026-04-21_mp-order-traveler-crud.md @@ -0,0 +1,206 @@ +# 微信小程序 · 订单出行人 CRUD 接口(4 个) + +**日期**:2026-04-21 +**影响**:**微信小程序** 订单出行人管理(原型 `L4xYN` 乘坐人员勾选列表、`Bf9jC` 添加人员弹窗) +**PR**:#1022(Closes #1020) + +--- + +## 概述 + +订单维度的出行人管理接口,区别于用户维度的"我的常用出行人": + +| 接口前缀 | 数据范围 | 用途 | +|---|---|---| +| `/mp/order/{orderId}/traveler` | **本接口**,`order_traveler` 表 | 订单出行人(随订单绑定) | +| `/mp/user/traveler` | 用户维度`user-service` | 用户常用出行人(跨订单复用) | + +共 **4 个接口**:列表、新增、修改、删除。 + +--- + +## 1. 出行人列表 + +``` +GET /mp/order/{orderId}/traveler +``` + +**鉴权**:Bearer token。 + +### 入参 + +| 参数 | 位置 | 类型 | 必填 | +|---|---|---|---| +| orderId | Path | Long | ✅ | + +### 出参 `Result>` + +**`MpOrderTravelerVO`**: + +| 字段 | 类型 | 说明 | +|---|---|---| +| travelerId | Long | 出行人ID | +| name | String | 姓名 | +| travelerType | String | 出行人类型(字典 `traveler_type`):`ADULT` / `CHILD` / `YOUNG_CHILD` / `BABY` | +| travelerTypeLabel | String | 类型中文标签 | +| idCardType | String | 证件类型(字典 `id_card_type`):`ID_CARD` / `PASSPORT` / `HK_MACAO_PASS` / `TAIWAN_PASS` / `OTHER` | +| idCardTypeLabel | String | 证件类型中文标签 | +| idCardNo | String | 证件号码 | +| gender | String | `1`=男 / `2`=女 | +| birthday | LocalDate | 出生日期 | +| phone | String | 手机号 | +| nationality | String | 国籍 | +| emergencyContact | String | 紧急联系人姓名 | +| emergencyPhone | String | 紧急联系人电话 | +| email | String | 邮箱 | + +### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "data": [ + { + "travelerId": 10001, + "name": "张三", + "travelerType": "ADULT", + "travelerTypeLabel": "成人", + "idCardType": "ID_CARD", + "idCardTypeLabel": "身份证", + "idCardNo": "110101199001011234", + "gender": "1", + "birthday": "1990-01-01", + "phone": "13800000000", + "nationality": "中国", + "emergencyContact": "李四", + "emergencyPhone": "13900000000", + "email": "zhangsan@example.com" + } + ], + "success": true +} +``` + +--- + +## 2. 新增出行人 + +``` +POST /mp/order/{orderId}/traveler +``` + +**鉴权**:Bearer token。 +**自动解析**:`idCardType=ID_CARD` 时,后端根据 `idCardNo` 自动解析并回填 `birthday` + `gender`。 + +### 入参 + +| 参数 | 位置 | 类型 | 必填 | +|---|---|---|---| +| orderId | Path | Long | ✅ | + +Body `MpOrderTravelerSaveReqVO`: + +| 字段 | 类型 | 必填 | 约束 | 说明 | +|---|---|---|---|---| +| name | String | ✅ | ≤50 | 姓名 | +| idCardType | String | 否 | - | 证件类型,默认 `ID_CARD`;可选 `ID_CARD` / `PASSPORT` / `HK_MACAO_PASS` / `TAIWAN_PASS` / `OTHER` | +| idCardNo | String | ✅ | - | 证件号码 | +| phone | String | 否 | - | 手机号 | +| gender | String | 否 | - | `1`=男 / `2`=女(身份证时可省略,自动解析) | +| birthday | LocalDate | 否 | - | 出生日期(身份证时可省略,自动解析) | +| travelerType | String | 否 | - | 默认 `ADULT`;可选 `ADULT` / `CHILD` / `YOUNG_CHILD` / `BABY` | +| nationality | String | 否 | - | 国籍 | +| emergencyContact | String | 否 | - | 紧急联系人姓名 | +| emergencyPhone | String | 否 | - | 紧急联系人电话 | +| email | String | 否 | - | 邮箱 | + +### 请求示例 + +```json +{ + "name": "张三", + "idCardType": "ID_CARD", + "idCardNo": "110101199001011234", + "phone": "13800000000", + "travelerType": "ADULT", + "nationality": "中国", + "emergencyContact": "李四", + "emergencyPhone": "13900000000", + "email": "zhangsan@example.com" +} +``` + +### 出参 + +`Result` — 新创建的出行人,结构同第 1 节。`birthday` 和 `gender` 已由后端回填。 + +--- + +## 3. 修改出行人 + +``` +PUT /mp/order/{orderId}/traveler/{travelerId} +``` + +**鉴权**:Bearer token。 +**字段语义**:**null 保持原值**,只传需要修改的字段即可(部分更新)。 + +### 入参 + +| 参数 | 位置 | 类型 | 必填 | +|---|---|---|---| +| orderId | Path | Long | ✅ | +| travelerId | Path | Long | ✅ | + +Body:`MpOrderTravelerSaveReqVO`(同第 2 节,但各字段均可为 null 表示不改)。 + +### 出参 + +`Result` — 修改后的完整信息。 + +--- + +## 4. 删除出行人 + +``` +DELETE /mp/order/{orderId}/traveler/{travelerId} +``` + +**鉴权**:Bearer token。 + +### 入参 + +| 参数 | 位置 | 类型 | 必填 | +|---|---|---|---| +| orderId | Path | Long | ✅ | +| travelerId | Path | Long | ✅ | + +### 出参 + +`Result`: + +```json +{ "code": 200, "message": "成功", "data": null, "success": true } +``` + +--- + +## 边界行为 + +- 订单不存在 / 不属于当前用户:500,`message` 含 `orderId` +- 出行人不存在 / 不属于该订单:500,`message` 含 `travelerId` +- `idCardType=ID_CARD` 时 `idCardNo` 格式不合法:400,`message` 含错误原因 +- 删除出行人时,若该出行人已被某到达批次关联,批次绑定同步软删(不会阻断删除) +- 订单状态为 `CANCELLED` / `REFUNDED` 时禁止修改/新增/删除 + +--- + +## 字典依赖 + +| 字典类型 | 可选值 | +|---|---| +| `traveler_type` | `ADULT` / `CHILD` / `YOUNG_CHILD` / `BABY` | +| `id_card_type` | `ID_CARD` / `PASSPORT` / `HK_MACAO_PASS` / `TAIWAN_PASS` / `OTHER` | + +所有 `xxxLabel` 字段由 BFF 透传自 order-v2,已经是中文展示值。