jw和Claude Opus 5
165cbcb69a
changelog-filename-gate / validate (push) Failing after 1s
整团名单速览、子订单、查看需求三张表吃同一个接口 GB-ADM-003
GET /v3/admin/order/group-batch/{groupBatchId}/orders，同源所以同病：
- 22_frontend_整团名单速览与子订单表…：联系人列显示占位符「—」应取 customerName；
房型列显示英文枚举码（KING）应取 roomTypeName（豪华大床）。
- 22_frontend_查看需求Tab子订单表…：同样两处取值问题，外加只有 5 列、
要补齐到子订单表的列集（团号/房型·间数/状态/需求审核/联系电话/应收/游客/资料）。
后端零改动，两份均已回填测试服活体实测读数：团期 2101506167098511362 全量 12 户，
customerName 12/12 有值、roomType→roomTypeName 12/12 翻译正常（KING→豪华大床）；
图示那一行的 12 列逐列与实测值逐字吻合。附排查提示：travelers 12/12 为空数组且
travelerInfoComplete 恒 false，联系人若从出行人明细推导即会恒显「—」。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
150 行
7.8 KiB
Markdown
150 行
7.8 KiB
Markdown
---
|
||
schema: hl-changelog/v2
|
||
ticket: "frontend"
|
||
title: "整团名单速览与子订单两张表：联系人列取 customerName、房型列取 roomTypeName"
|
||
consumer: admin
|
||
author: "jw(GIT)"
|
||
change_type: "前端缺陷"
|
||
backend_status: "not_required"
|
||
gateway_status: "not_required"
|
||
frontend_status: "pending"
|
||
frontend_owner: ""
|
||
frontend_ref: ""
|
||
target_release: ""
|
||
verified_at: ""
|
||
status_note: "2026-09-22 页面核对：团期详情的「整团名单速览」与「子订单」两张表存在同样两处显示问题——①「子订单 / 联系人」列的联系人行显示占位符「—」；②「房型 / 间数」列的房型显示英文枚举码（如 KING）。两张表吃的是同一个后端接口 GB-ADM-003 GET /v3/admin/order/group-batch/{groupBatchId}/orders，同源所以同病。后端零改动：同日 TEST 实测团期 2101506167098511362 全量 12 户，customerName 12/12 有值（张三/王五/李玉/张德发/王芳/阿宾等），roomType 与 roomTypeName 12/12 均有值且翻译正常（KING → 豪华大床）。前端把联系人列对齐到 customerName、房型列对齐到 roomTypeName 即可。排查提示：同一响应里 travelers 12/12 为空数组、travelerInfoComplete 12/12 为 false，若联系人是从出行人明细推导的，出行人未填时就会恒显「—」，而 customerName 与出行人资料无关、一直有值。"
|
||
updated_at: "2026-09-22"
|
||
base: dev-v3
|
||
---
|
||
|
||
# 整团名单速览 / 子订单: 联系人列与房型列取值订正
|
||
|
||
> **服务**: hl-order-service-v3（**后端零改动**）
|
||
> **页面**: 管理后台 → 团期订单 → 团期详情 → 「整团总览」Tab 的整团名单速览 与 「子订单」Tab 的子订单表
|
||
> **接口**: `GET /v3/admin/order/group-batch/{groupBatchId}/orders`（GB-ADM-003 / A3）
|
||
> **日期**: 2026-09-22
|
||
> **影响范围**: 仅前台渲染取值；无端点、无出入参、无路由、无 DDL 变化
|
||
|
||
---
|
||
|
||
## ⚠️ 关键变化
|
||
|
||
- **两张表是同一个接口**，所以同一个毛病出现两次：整团名单速览与子订单表都消费 GB-ADM-003，改的时候两处一起改，别只改一处。
|
||
- **后端不需要任何改动**。这两个字段一直都在返回，且 2026-09-22 TEST 实测**全量有值**——问题在前端取了别的字段。
|
||
|
||
---
|
||
|
||
## 一、两处问题
|
||
|
||
| # | 列 | 页面现在显示 | 应该显示 | 接口字段 |
|
||
|---|---|---|---|---|
|
||
| 1 | 子订单 / 联系人（第二行的联系人） | `—`（占位符） | 客户姓名，如 `张三` | `customerName` |
|
||
| 2 | 房型 / 间数 里的「房型」 | 英文枚举码，如 `KING` | 中文房型名，如 `豪华大床` | `roomTypeName`（当前多半取了 `roomType`） |
|
||
|
||
---
|
||
|
||
## 二、实测证据
|
||
|
||
TEST 环境 `api.test.1814.love:9443`，2026-09-22，团期 `2101506167098511362`（jw测试产品 · 第1期 jw测试1期），`GET /v3/admin/order/group-batch/2101506167098511362/orders?pageSize=200`，`total=12`：
|
||
|
||
```
|
||
customerName 为空的户数: 0 / 12
|
||
roomTypeName 为空的户数: 0 / 12
|
||
roomType 为空的户数: 0 / 12
|
||
|
||
roomType -> roomTypeName 取值分布:
|
||
'KING' -> '豪华大床' x12 （翻译正常，没有回落英文的情况）
|
||
```
|
||
|
||
单户原始响应片段：
|
||
|
||
```json
|
||
{
|
||
"orderId": "2101506167043985410",
|
||
"orderNo": "HL20260920105808925",
|
||
"teamNo": "26-3627",
|
||
"customerName": "张三",
|
||
"participantCount": 6,
|
||
"tierCode": "2A2C2Y",
|
||
"tierName": "2成人2儿童2幼童",
|
||
"roomCount": 2,
|
||
"roomType": "KING",
|
||
"roomTypeName": "豪华大床",
|
||
"contactPhone": "133****2212",
|
||
"travelerInfoComplete": false,
|
||
"travelers": []
|
||
}
|
||
```
|
||
|
||
前 6 户逐户对照（联系人全部有值，与页面上的 `—` 直接矛盾）：
|
||
|
||
```
|
||
HL20260920105808925 联系人='张三' roomCount=2 roomType='KING' roomTypeName='豪华大床'
|
||
HL20260920110233355 联系人='王五' roomCount=2 roomType='KING' roomTypeName='豪华大床'
|
||
HL20260920110625528 联系人='李玉' roomCount=2 roomType='KING' roomTypeName='豪华大床'
|
||
HL20260921160904989 联系人='张德发' roomCount=2 roomType='KING' roomTypeName='豪华大床'
|
||
HL20260921161004158 联系人='王芳' roomCount=2 roomType='KING' roomTypeName='豪华大床'
|
||
HL20260921161039050 联系人='阿宾' roomCount=2 roomType='KING' roomTypeName='豪华大床'
|
||
```
|
||
|
||
---
|
||
|
||
## 三、排查提示: 联系人为什么会恒显「—」
|
||
|
||
同一次响应里还有两个数：**`travelers` 12/12 都是空数组**，**`travelerInfoComplete` 12/12 都是 `false`**（这个团的出行人资料还没填）。
|
||
|
||
如果联系人这一行是从出行人明细里推导的（例如取 `travelers[0]` 的姓名），那么只要该户出行人没录，页面就会恒显 `—`，与客户姓名有没有值无关。而 `customerName` 取的是订单主表的客户姓名，**与出行人资料完全无关**，本团 12/12 都有值。
|
||
|
||
接口里没有名为 `contact` / `linkman` 之类的字段，**联系人就是 `customerName`**。同一行若要显示联系方式，用 `contactPhone`（已脱敏，前3后4，本团 12/12 有值）。
|
||
|
||
---
|
||
|
||
## 四、房型列的两个限定
|
||
|
||
1. **要用 `roomTypeName`，不要自建映射。** `roomTypeName` 是后端把 `roomType` 按「、」逐段走 `room_category` 字典翻译后拼回的结果（多段房型会返回成 `标间、大床房` 这样）。字典不可达时它会**回落成原始英文码**——此时前端直显即可，不要另建一套前端映射表兜底（沿用 `16_frontend_前台整团名单速览补状态与需求审核列` 定下的口径：中文名一律由后端给，前端不自建映射）。
|
||
|
||
2. **房型三字段受 `includeNeeds` 开关控制。** `includeNeeds` **缺省为 `true`**，此时才返回 `roomCount` / `roomType` / `roomTypeName` / `specialNeeds`。同日实测显式传 `includeNeeds=false` 时，这四个字段全部为 `null`，而 `customerName` 仍有值：
|
||
|
||
```
|
||
includeNeeds=false 时：
|
||
roomCount = None roomType = None roomTypeName = None specialNeeds = None
|
||
customerName = '张三'
|
||
```
|
||
|
||
所以「房型列整列为空」与「房型列显示英文码」是两回事：前者去看请求有没有显式传 `includeNeeds=false`，后者才是本条说的取值取错。间数列用 `roomCount`（来源需求里的逐段房数，缺需求行时回落 `ceil(人数/2)`）。
|
||
|
||
---
|
||
|
||
## 五、改完后这两张表的完整字段对照
|
||
|
||
| 列 | 字段 | 备注 |
|
||
|---|---|---|
|
||
| 子订单编号 | `orderNo` | 另有团号 `teamNo`（订金支付成功后才生成，未付订金为 `null`） |
|
||
| 联系人 | `customerName` | 本条订正项 |
|
||
| 联系方式 | `contactPhone` | 脱敏，前3后4 |
|
||
| 套餐 / 档位 | `tierName` | 码为 `tierCode` |
|
||
| 人数 | `participantCount` | 成人+儿童+幼童+婴儿 |
|
||
| 房型 | `roomTypeName` | 本条订正项，需 `includeNeeds=true`（缺省即是） |
|
||
| 间数 | `roomCount` | 需 `includeNeeds=true` |
|
||
| 特殊需求 | `specialNeeds` | 需 `includeNeeds=true` |
|
||
| 状态 | `orderStatusName` | 枚举外回落 `orderStatus` |
|
||
| 需求审核（房 / 车） | `hotelRequirementStatusName` / `vehicleRequirementStatusName` | 取值：待房务配 / 配房中 / 配房完成 / 待审核 / 驳回 |
|
||
| 定制师 | `consultantName` | — |
|
||
| 金额 | `totalPrice` / `paidAmount` / `balanceAmount` | 字符串两位小数 |
|
||
|
||
---
|
||
|
||
## 六、不影响范围
|
||
|
||
- 后端无需发版：GB-ADM-003 的路径、入参、出参、返回值一个都没变，其它调用方不受影响。
|
||
- 不涉及权限码、错误码、字典、DDL。
|
||
- 团期详情其它 Tab、子订单详情页、定制师待办、抢单池均不受影响。
|
||
|
||
---
|
||
|
||
## 关联 / 联系人
|
||
|
||
- 后端: jw
|
||
- 前端: 待认领（`frontend_status: pending`）
|
||
- 同接口的前序交接件: `changelogs-v2/2026-09/16_frontend_前台整团名单速览补状态与需求审核列-前端优化-管理后台.md`（该条已确认「联系人 `customerName`」「房型 `roomTypeName` / `roomCount`」是原型要求的列与字段）
|