7e12f0e9ce
- 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>
207 行
5.3 KiB
Markdown
207 行
5.3 KiB
Markdown
# 微信小程序 · 订单出行人 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,已经是中文展示值。
|