133 行
4.3 KiB
Markdown
133 行
4.3 KiB
Markdown
# 订单出行人 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）
|