# 出行人录入 — 新增 民族 / 国籍 / 同住分组号 三个字段

**类型**: 后端字段扩展
**前端处理者**: mmg
**日期**: 2026-05-01
**关联**: 工单 #1590 / PR #1592
**影响页面**:
- 管理后台「订单详情 → 出行人 → 新增/编辑出行人」
- 小程序「订单 → 出行人」录入页

---

## 这是什么

出行人 entity 加了 3 个字段，用于 12301 合同上报：

| 字段 | 类型 | 说明 | 默认值兜底 |
|------|------|------|----------|
| `race` | String | 民族（中文，如 "汉族" "蒙古族" "回族"） | 后端兜底 "汉族" |
| `nationality` | String | 国籍（中文，如 "中国"） | 后端兜底 "中国" |
| `roomGroupNo` | Integer | 同住分组号（同号=同房，例如夫妻填同一数字 1，独立间填 NULL 或唯一数字） | 系统自动两两配对 |

---

## UI 需求

### 出行人录入弹窗 / 表单

加三个字段（建议放在「证件号 / 手机号 / 紧急联系人」附近）：

1. **民族**（选填）
   - 推荐用 **下拉框**，但项目暂没"民族"字典
   - **简化方案**：用文本输入框 + placeholder "默认汉族, 港澳台/护照证件请填实际民族"
   - 后端会用 EncryptTypeHandler 加密存储不？**不加密**(当前 entity 直接 String race)
   - 长度限制 20 字符

2. **国籍**（选填）
   - 文本输入 + placeholder "默认中国, 港澳台/护照证件必填"
   - 长度限制 50 字符（实际更短）

3. **同住分组号**（选填）
   - 数字输入 + placeholder "同号=同房, 留空系统自动两两配对"
   - 提示文案：
     > 例如夫妻同房：两人都填 1
     > 朋友合住：两人都填 2
     > 单人房：填唯一数字（如 99）
     > 留空：系统按列表顺序自动两两配对（0+1, 2+3...）

---

## 接口（增量字段）

### 1. 管理端新增出行人

```
POST /admin/order/{orderId}/traveler
Content-Type: application/json

{
  "name": "张三",
  "idCardType": "ID_CARD",
  "idCardNo": "152104199802205216",
  "phone": "13800138000",
  ...

  // 🆕 新增 3 字段(全部选填):
  "race": "蒙古族",
  "nationality": "中国",
  "roomGroupNo": 1
}
```

### 2. 管理端修改出行人

```
PUT /admin/order/traveler/{travelerId}
Content-Type: application/json

{ ...含同样 3 字段 }
```

### 3. 小程序端

`POST /mp/order/traveler` body 里也加这 3 字段（逻辑一致）。

### 4. 查询出行人详情/列表

```
GET /admin/order/traveler/{travelerId}
GET /admin/order/{orderId}/travelers

→ 200
{
  "code": 200,
  "data": {
    ...原有字段...
    "race": "汉族",          // 🆕
    "nationality": "中国",   // 🆕
    "roomGroupNo": 1         // 🆕 (Integer 或 null)
  }
}
```

---

## 哪种证件类型必填？

业务规则：

| 证件类型 | race / nationality 重要性 |
|---------|-------------------------|
| 身份证（ID_CARD） | 系统可由身份证号反推民族/国籍，**前端可不填**，后端兜底 |
| 港澳通行证 | **建议填**，身份证算法不适用 |
| 护照（PASSPORT） | **建议填**，外籍/海外华人必填正确国籍 |
| 台湾通行证 | 同港澳通行证 |

可在表单上加提示文案引导。

---

## 测试服已就绪

后端字段已上线，前端调用接口加这 3 个字段即可。

---

## 服务重启

后端 hl-order-service-v2 已上线。`order_traveler` 表已 ALTER 加 race + room_group_no 列（nationality 之前已有）。