---
schema: "hl-changelog/v2"
ticket: "frontend"
title: "前台团期列表子订单展开区联系人绑错字段恒显破折号"
consumer: "admin"
author: "wx(GIT)"
change_type: "前端缺陷"
backend_status: "not_required"
gateway_status: "not_required"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "89dadf1e69fb3953389e3a34a1c402279f5a9eb8"
target_release: ""
verified_at: "2026-09-15"
status_note: "纯前端条目，后端零改动。GET /v3/admin/order/group-batch/{groupBatchId}/orders 出参未变，联系人字段一直叫 customerName，前台绑成了不存在的 contactName，导致该列恒显破折号。同时该接口已返回的已付/待付/订单状态/支付状态四个字段前台也未使用。后端经核对零缺口。 前端已交付(89dadf1e):SubOrderTable 联系人改绑 customerName;金额格改「已付 paidAmount / 应收 totalPrice」复合+确有尾款时次行「待付 balanceAmount」(归一化字符串比 0.00 判零不 Number());新增状态列直显 orderStatusName/payStatusName(枚举外兜底 code,不建映射);资料标签保留。SubOrderTable.spec 夹具同步+3 新例,7/7。"
updated_at: "2026-09-15"
base: "dev-v3"
---

# 前台团期列表子订单展开区联系人绑错字段恒显破折号（前端缺陷）

> **服务**: hl-order-service-v3（后端零改动）
> **页面**: 管理后台 `/order-v2/batch` 团期订单列表 → 展开某一期的子订单
> **组件**: `src/views/order-v2/batch/components/SubOrderTable.vue`
> **接口**: `GET /v3/admin/order/group-batch/{groupBatchId}/orders`
> **日期**: 2026-09-15
> **影响范围**: 仅前台渲染；无端点、无出入参、无路由、无 DDL 变化

---

## ⚠️ 关键变化

🔴 **联系人列绑错了字段名，现网恒显破折号。**

`SubOrderTable.vue:25` 写的是：

```vue
<b>{{ o.contactName || '—' }}</b>
```

而该接口的出参里**没有 `contactName` 这个字段**，联系人字段叫 **`customerName`**。所以无论数据是否齐全，这一列永远走 `|| '—'` 兜底。

现网实测（团期 `2096495107078328322` 的首条子订单）：

```json
{
  "orderId": "2096495107032190978",
  "orderNo": "HL20260906150559114",
  "customerName": "#7158验收",
  "participantCount": 2,
  "orderStatus": "PENDING_PAY",
  "orderStatusName": "待支付",
  "payStatus": "UNPAID",
  "payStatusName": "未支付",
  "paidAmount": "0.00",
  "balanceAmount": "4000.00",
  "totalPrice": "4000.00",
  "tierName": "2成人",
  "contactPhone": "138****2046"
}
```

`customerName` 有值，页面却显示破折号。

---

## 一、修复方式

把 `o.contactName` 改绑 `o.customerName` 即可，后端不需要任何改动。

> 说明：`contactName` 这个名字在团期行程接口（GB-ADM-018）里确实存在，但已标注废弃、与 `customerName` 同值同源；**子订单列表接口从来只有 `customerName`**，不要按行程接口的字段名去猜。

---

## 二、同一张表上另外 4 个已返回但未使用的字段

| # | 原型上的元素 | 接口字段 | 现网实测值 | 前台现状 |
|---|---|---|---|---|
| 1 | 已付金额（原型「¥5,000 / ¥12,300」左值） | `paidAmount` | `0.00` | 只显应收 `totalPrice`，看不出欠款 |
| 2 | 待付尾款 | `balanceAmount` | `4000.00` | 未使用 |
| 3 | 子订单状态（原型「待出行 / 待补全信息」） | `orderStatus` / `orderStatusName` | `PENDING_PAY` / `待支付` | 该位置现在放的是「资料 待补」标签（对应 `travelerInfoComplete`），不是订单状态 |
| 4 | 支付状态标签 | `payStatus` / `payStatusName` | `UNPAID` / `未支付` | 未使用 |

---

## 三、字段口径提醒

- **中文名一律直显后端给的 `*Name` 字段**，不要在前台自建枚举到中文的映射表；后端加状态时前台不需要跟着改。
- `totalPrice` 是本户应收（`orderAmount + 增项 − 优惠`，下限 0，取消单返 `0.00`）；`balanceAmount` 是待付尾款（应收 − 已退 − 已付，恒非负）。**两者都由后端算好，前台不要自行相减。**
- `contactPhone` 已在后端脱敏（前 3 后 4），前台直显即可。
- 展开区默认不含已取消子订单（`includeCancelled` 缺省 `false`），所以行上的子订单数与展开条数在有取消单时会不一致；需要一致时显式传 `includeCancelled=true`。

---

## 四、不影响范围

- 接口路径、入参、出参结构**均未变动**，无需后端配合发版。
- 不涉及网关路由、权限码、错误码、数据库。
- 团期列表行本身的漏展示字段见同日另一条 `前端优化` 条目。

---

## 五、相关文档

- 差异清单：`需求分析/测试发现问题.md` 模块 2
- 原型出处：`需求分析/2026-09-11-团期模块需求分析.md` §3.2「子订单页」

## 关联 / 联系人

- 后端：wx
- 前端：mmg