docs(mp): MP 订单详情 travelers[].travelerId 从 null 修复为真实值 (PR #1208)

changelogs/2026-04/2026-04-22_mp-order-detail-traveler-id-now-populated.md

@@ -0,0 +1,73 @@
+# MP 订单详情 travelers[] 字段 travelerId 从 null 变真实值
+
+**日期**: 2026-04-22
+**PR**: #1208
+**Issue**: #1207
+**服务**: hl-order-service-v2(已部署测试服 双实例 8094/8194)
+**影响端**: 小程序订单详情页、管理端可能调用的 MP 订单详情
+
+## 问题
+
+`GET /mp/order/{orderId}` 返回的 `data.travelers[]` 数组,每条出行人对象的:
+
+- `travelerId` —— **之前永远是 null**
+- `travelerTypeLabel` —— 之前永远是 null
+- `idCardTypeLabel` —— 之前永远是 null
+
+前端凡是依赖 `travelerId` 做**编辑 / 删除 / 关联**的操作都不可用;依赖 label 做展示的会显示空。
+
+## 根因(后端自修)
+
+后端 `MpOrderDetailAssembler` 用 Hutool `BeanUtil.toBean` 做 `OrderTraveler → TravelerVO` 映射,但 Entity 主键字段名 `orderTravelerId` ≠ VO 字段 `travelerId`,属性精确匹配不上导致 id 永久 null;enum 类型字段转 label 也被吞。修复后复用同 Service 已有的正确手动映射方法。
+
+## 字段契约(修复后)
+
+```
+GET /mp/order/{orderId}
+Response.data.travelers: Array<MpTravelerVO>
+```
+
+每条 MpTravelerVO 关键字段:
+
+| 字段 | 类型 | 修复前 | 修复后 |
+|------|------|--------|--------|
+| `travelerId` | Long | null | 真实雪花 ID |
+| `name` | String | 正常 | 正常 |
+| `travelerType` | String | 正常(ADULT/CHILD/YOUNG_CHILD/BABY) | 正常 |
+| `travelerTypeLabel` | String | null | "成人"/"儿童"/"幼儿"/"婴儿" |
+| `idCardType` | String | 正常(IDCARD/PASSPORT/...) | 正常 |
+| `idCardTypeLabel` | String | null | "身份证"/"护照"/... |
+| `idCardNo` | String | 正常 | 正常 |
+| `phone` / `gender` / `birthday` / ... | | 正常 | 正常 |
+
+## 前端 TODO(若此前有兜底)
+
+- 如果之前判空后显示"-"或不显示编辑/删除按钮,现在可以直接信任 `travelerId` 非 null
+- 如果之前手动拼 label,现在可以直接用 `travelerTypeLabel` / `idCardTypeLabel`
+- 无需改任何请求签名,无需发版,后端部署后次日生效(前端刷新页面即生效)
+
+## 验证
+
+```bash
+# 测试服内部 curl(需 gateway token)
+curl "https://api.test.1814.love:9443/mp/order/{orderId}" -H "Authorization: Bearer {TOKEN}"
+
+# 断言
+.data.travelers[].travelerId != null
+.data.travelers[].travelerTypeLabel in ["成人","儿童","幼儿","婴儿"]
+```
+
+实测订单 `2046842978273579010`:
+```json
+{
+  "travelers": [
+    { "travelerId": 2046911429360955393, "name": "米明光",  "travelerType": "ADULT", "travelerTypeLabel": "成人" },
+    { "travelerId": 2046911429365149698, "name": "王晓",    "travelerType": "YOUNG_CHILD", "travelerTypeLabel": "幼儿" }
+  ]
+}
+```
+
+## 无破坏性
+
+- 字段名/类型不变,仅值从 null 变真实值
+- 无前端代码必须改动