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

类型: 后端字段扩展 前端处理者: mmg 日期: 2026-05-01 关联: 工单 #1590 / PR #1592 影响页面:

管理后台「订单详情 → 出行人 → 新增/编辑出行人」
小程序「订单 → 出行人」录入页

这是什么

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

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

UI 需求

出行人录入弹窗 / 表单

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

民族（选填）
- 推荐用 下拉框，但项目暂没"民族"字典
- 简化方案：用文本输入框 + placeholder "默认汉族, 港澳台/护照证件请填实际民族"
- 后端会用 EncryptTypeHandler 加密存储不？不加密(当前 entity 直接 String race)
- 长度限制 20 字符
国籍（选填）
- 文本输入 + placeholder "默认中国, 港澳台/护照证件必填"
- 长度限制 50 字符（实际更短）
同住分组号（选填）
- 数字输入 + 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 之前已有）。

3.4 KiB 原始文件 Blame 文件历史 Unescape Escape

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