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