changelog(mp): 微信小程序 · 订单出行人 CRUD 接口(4 个)
- 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) <noreply@anthropic.com>
这个提交包含在：
yaosutu
父节点
34621d845b
当前提交
7e12f0e9ce
@ -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<List<MpOrderTravelerVO>>`
|
||||
|
||||
**`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<MpOrderTravelerVO>` — 新创建的出行人,结构同第 1 节。`birthday` 和 `gender` 已由后端回填。
|
||||
|
||||
---
|
||||
|
||||
## 3. 修改出行人
|
||||
|
||||
```
|
||||
PUT /mp/order/{orderId}/traveler/{travelerId}
|
||||
```
|
||||
|
||||
**鉴权**:Bearer token。
|
||||
**字段语义**:**null 保持原值**,只传需要修改的字段即可(部分更新)。
|
||||
|
||||
### 入参
|
||||
|
||||
| 参数 | 位置 | 类型 | 必填 |
|
||||
|---|---|---|---|
|
||||
| orderId | Path | Long | ✅ |
|
||||
| travelerId | Path | Long | ✅ |
|
||||
|
||||
Body:`MpOrderTravelerSaveReqVO`(同第 2 节,但各字段均可为 null 表示不改)。
|
||||
|
||||
### 出参
|
||||
|
||||
`Result<MpOrderTravelerVO>` — 修改后的完整信息。
|
||||
|
||||
---
|
||||
|
||||
## 4. 删除出行人
|
||||
|
||||
```
|
||||
DELETE /mp/order/{orderId}/traveler/{travelerId}
|
||||
```
|
||||
|
||||
**鉴权**:Bearer token。
|
||||
|
||||
### 入参
|
||||
|
||||
| 参数 | 位置 | 类型 | 必填 |
|
||||
|---|---|---|---|
|
||||
| orderId | Path | Long | ✅ |
|
||||
| travelerId | Path | Long | ✅ |
|
||||
|
||||
### 出参
|
||||
|
||||
`Result<Void>`:
|
||||
|
||||
```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,已经是中文展示值。
|
||||
正在加载...
x
在新工单中引用
屏蔽一个用户