# 订单出行人 MP 端 CRUD 接口新增 — 2026-04-20

> **服务** hl-order-service-v2（端口 8094）· **类型** feat · **关联** Issue #1020 / PR #1022
> **前端调用路径**: 网关(8080) → hl-mp-service(8085) → hl-order-service-v2(8094)
> **前端实际请求前缀**: `/mp/order/{orderId}/traveler`（4 个接口）

---

## 一、能力概述

给小程序端补齐**订单出行人** CRUD 能力，对应原型 **L4xYN 乘坐人员勾选列表**、**Bf9jC 添加人员弹窗**。

| 原型节点 | 功能 | 主要接口 |
| --- | --- | --- |
| L4xYN pplList | 乘坐人员勾选列表 | `GET /mp/order/{orderId}/traveler` |
| Bf9jC | 添加人员弹窗 | `POST /mp/order/{orderId}/traveler` |
| Bf9jC（编辑） | 修改出行人 | `PUT /mp/order/{orderId}/traveler/{travelerId}` |
| Bf9jC（删除） | 删除出行人 | `DELETE /mp/order/{orderId}/traveler/{travelerId}` |

**注意区分两套"出行人"模型**：

| 维度 | 路径 | 说明 |
| --- | --- | --- |
| 用户常用出行人 | `/mp/user/traveler/*` | user-service 管，已有 |
| **订单出行人**（本次新增） | `/mp/order/{orderId}/traveler/*` | order-v2 的 `order_traveler` 表 |

---

## 二、接口清单

鉴权：user token（登录态）

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | `/mp/order/{orderId}/traveler` | 查某订单的出行人列表 |
| POST | `/mp/order/{orderId}/traveler` | 新增出行人到某订单 |
| PUT | `/mp/order/{orderId}/traveler/{travelerId}` | 修改出行人（字段为 null 保持原值不变） |
| DELETE | `/mp/order/{orderId}/traveler/{travelerId}` | 删除出行人 |

---

## 三、请求体（`MpOrderTravelerSaveReqVO`）

```jsonc
{
  "name":             "张三",               // 必填，≤50 字
  "idCardType":       "ID_CARD",            // 字典 id_card_type
  "idCardNo":         "110101199001011234", // 必填
  "phone":            "13800000000",
  "gender":           "1",                  // 1=男 2=女
  "birthday":         "1990-01-01",
  "travelerType":     "ADULT",              // 默认 ADULT，字典 traveler_type
  "nationality":      "中国",
  "emergencyContact": "李四",
  "emergencyPhone":   "13900000000",
  "email":            "zhangsan@example.com"
}
```

**字典取值**：
- `idCardType`: `ID_CARD` 身份证 / `PASSPORT` 护照 / `HK_MACAO_PASS` 港澳通行证 / `TAIWAN_PASS` 台湾通行证 / `OTHER` 其他
- `travelerType`: `ADULT` 成人 / `CHILD` 儿童 / `YOUNG_CHILD` 幼儿 / `BABY` 婴儿

**后端自动处理**：
- 身份证（18 位）自动解析 `birthday` + `gender`（前端可不传）
- 同订单证件号重复检查（重复抛业务错误）

---

## 四、响应体

### 列表 `GET` 响应

```jsonc
{
  "code": 200,
  "data": [
    {
      "travelerId":       10001,             // Long，注：未强制 String（现有约定）
      "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"
    }
  ]
}
```

### 新增/修改返回

返回单个对象（同列表元素结构）。

### 删除返回

```jsonc
{ "code": 200, "data": null }
```

### 约定

- 所有枚举字段都配 `xxxLabel` 中文标签
- 空数据返回 `[]`，不是 `null`
- 时间格式统一 `yyyy-MM-dd`（出生日期）/ `yyyy-MM-dd HH:mm:ss`（含时间字段）

---

## 五、前端接入建议

**L4xYN 乘坐人员勾选列表**：
1. 打开页面 → `GET /mp/order/{orderId}/traveler` 拉取订单已有出行人
2. 用户勾选 → 把 travelerId 传给**到达信息**接口的 `travelerIds` 字段

**Bf9jC 添加人员弹窗**：
1. 可选：先调 `GET /mp/user/traveler`（已有）让用户从常用库选一个 → 填到表单里
2. 用户补全/修改字段（含 OCR 扫描身份证填入，OCR 用小程序原生插件前端做）
3. 提交 `POST /mp/order/{orderId}/traveler`

---

## 六、关联

- Issue: [wx/HL#1020](https://git.1814.love:8443/wx/HL/issues/1020)
- PR: [wx/HL#1022](https://git.1814.love:8443/wx/HL/pulls/1022)（已合并到 dev）