feat(contract): 拆分 12301 合同方案 changelog 为 3 份独立文档(附件 Tab/导游 Tab/出行人字段) - 前端 mmg 重新阅读

2026-05-01 15:51:00 +08:00
@@ -0,0 +1,129 @@
+# 出行人录入 — 新增 民族 / 国籍 / 同住分组号 三个字段
+
+**类型**: 后端字段扩展
+**前端处理者**: 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 之前已有）。