docs(changelog): 前台团期列表两条前端条目(列表漏展示 11 字段 + 子订单联系人绑错 customerName)
changelog-filename-gate / validate (push) Failing after 1s
changelog-filename-gate / validate (push) Failing after 1s
按团期原型逐块比对测试环境产出，后端零改动： - 前端优化：GET /v3/admin/order/group-batch、/summary、/products 已返回的 11 个字段前台未渲染 （productName/endDate/orderCount/enrolledPeople/maxParticipants/remainParticipants/maxRooms/ batchNo 展示形态/subOrderCount/total/coverImageUrl+regionText），逐条附现网实测值。 - 前端缺陷：SubOrderTable.vue:25 绑 o.contactName，该接口出参只有 customerName，联系人列恒显破折号； 同表 paidAmount/balanceAmount/orderStatusName/payStatusName 四个已返回字段也未使用。 后端确实缺的 5 项另开工单 #7769（出参 daysToDepart/minToForm）与 #7770（入参日期区间筛选与排序），不在本文范围。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
这个提交包含在：
Claude Opus 5
@@ -0,0 +1,102 @@
|
||||
---
|
||||
schema: "hl-changelog/v2"
|
||||
ticket: "frontend"
|
||||
title: "前台团期列表页漏展示 11 项接口已返回字段"
|
||||
consumer: "admin"
|
||||
author: "wx(GIT)"
|
||||
change_type: "前端优化"
|
||||
backend_status: "not_required"
|
||||
gateway_status: "not_required"
|
||||
frontend_status: "pending"
|
||||
frontend_owner: "mmg"
|
||||
frontend_ref: ""
|
||||
target_release: ""
|
||||
verified_at: ""
|
||||
status_note: "纯前端条目，后端零改动。GET /v3/admin/order/group-batch、/summary、/products 三个接口的出参未变，本文列出的字段现网均已返回，只是前台未渲染。按团期原型逐块比对后产出，原型出处见需求分析/2026-09-11-团期模块需求分析.md。后端确实缺的 5 项已另开工单 #7769（出参）与 #7770（入参），不在本文范围。"
|
||||
updated_at: "2026-09-15"
|
||||
base: "dev-v3"
|
||||
---
|
||||
|
||||
# 前台团期列表页漏展示 11 项接口已返回字段（前端优化）
|
||||
|
||||
> **服务**: hl-order-service-v3（后端零改动）
|
||||
> **页面**: 管理后台 `/order-v2/batch` 团期订单列表
|
||||
> **组件**: `src/views/order-v2/batch/index.vue`、`components/PeriodRow.vue`
|
||||
> **日期**: 2026-09-15
|
||||
> **影响范围**: 仅前台渲染；无端点、无出入参、无路由、无 DDL 变化
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 关键变化
|
||||
|
||||
🔵 **接口没变，是前台没接。** 下列 11 个字段现网三个接口都已返回，页面上一个都没渲染，导致团期列表与原型差距很大。
|
||||
|
||||
按原型比对，列表行现在只显示「第 N 期 + 班期名 + 编号 + 出团日 + 户进度 + 状态 + 六芯片 + 应收/已收」，原型要求的产品名、日期区间、子订单数、人维度进度、成团标准、统计条子订单总数等全部缺位。
|
||||
|
||||
---
|
||||
|
||||
## 一、漏展示字段清单
|
||||
|
||||
### 1.1 `GET /v3/admin/order/group-batch`（团期分页列表，逐行）
|
||||
|
||||
| # | 原型上的元素 | 接口字段 | 现网实测值 | 前台现状 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | 行内产品名称 | `productName` | `测试小蒙马-多档-固定金额` | 未渲染，产品名只在顶部页签 |
|
||||
| 2 | 日期区间 `6.25-6.30` | `endDate` | `2026-12-21` | `departDateText()` 只取 `departDate`，区间尾丢失 |
|
||||
| 3 | 子订单数 | `orderCount` | `2` | 未渲染 |
|
||||
| 4 | 人维度进度条「人 23/26」 | `enrolledPeople` / `maxParticipants` | `4` / `0` | 只有户（房）一条进度条 |
|
||||
| 5 | 「约 N 人满 / 剩 N 人」 | `remainParticipants` | `null` | 未渲染，依赖第 4 条 |
|
||||
| 6 | 满团标准「满 9 户满团」 | `maxRooms` | `9` | 未渲染 |
|
||||
| 7 | 短期号展示形态 | `batchNo` | `Q202612202096494989117677570` | 25 位原始编号整串铺出，原型是短编号 |
|
||||
|
||||
### 1.2 `GET /v3/admin/order/group-batch/summary`（看板统计条）
|
||||
|
||||
| # | 原型上的元素 | 接口字段 | 现网实测值 | 前台现状 |
|
||||
|---|---|---|---|---|
|
||||
| 8 | 统计条「子订单 15」 | `subOrderCount` | `3` | 未渲染，页签区只画了 8 桶 |
|
||||
| 9 | 「班期总览 · 全年 N 期」 | `total` | `11` | 无总览卡片 |
|
||||
|
||||
### 1.3 `GET /v3/admin/order/group-batch/products`（产品选择器）
|
||||
|
||||
| # | 原型上的元素 | 接口字段 | 现网实测值 | 前台现状 |
|
||||
|---|---|---|---|---|
|
||||
| 10 | 产品卡封面 | `coverImageUrl` | 有值（OSS 链接） | 用产品名首字色块代替 |
|
||||
| 11 | 产品卡副标题地区 | `regionText` | `null`（该产品未回填） | 未渲染；见下方「四」 |
|
||||
|
||||
---
|
||||
|
||||
## 二、字段口径提醒
|
||||
|
||||
- `endDate` 是**返团日**，与 `departDate` 组成原型的日期区间；两者都可能为空，为空时不要拼出半截区间。
|
||||
- `remainRooms` / `remainParticipants` 在容量为空时后端直接返 `null`，**前台不要用 0 兜底**，`null` 表示「不限」而不是「已满」。
|
||||
- `maxParticipants = 0` 按契约表示**人数维度不限容量**，此时人进度条与「约 N 人满」都不应渲染（当前测试数据正是这种情况）。
|
||||
- `batchNo` 是产品域生成的长编号，**前台自行截断或改展示规则即可**，后端不会再给一个短码。
|
||||
- `subOrderCount` 只在 summary 返回，逐行的 `orderCount` 是该团期自己的子订单数，两者不是一回事，别互相替代。
|
||||
|
||||
---
|
||||
|
||||
## 三、不影响范围
|
||||
|
||||
- 三个接口的路径、入参、出参结构**均未变动**，无需后端配合发版。
|
||||
- 不涉及网关路由、权限码、错误码、数据库。
|
||||
- 团期详情页与子订单展开区不在本文范围（展开区见同日另一条 `前端缺陷` 条目）。
|
||||
|
||||
---
|
||||
|
||||
## 四、需要另行确认的两项
|
||||
|
||||
- `regionText` 现网为 `null`，是**产品域没有回填地区文案**，不是接口缺字段。前台先按「有值才渲染」处理，数据侧另行推动。
|
||||
- `minGroupPeople` 现网为 `0`，它是**人数**成团门槛（0 表示不限）；原型「满 6 户成团」用的是**户数**门槛 `minToForm`，该字段目前只在团期详情 `GET /v3/admin/order/group-batch/{groupBatchId}` 返回，列表接口没有，已开工单 #7769 补。**在 #7769 交付前，统计条副标题的成团标准做不出来。**
|
||||
|
||||
---
|
||||
|
||||
## 五、相关文档
|
||||
|
||||
- 差异清单：`需求分析/测试发现问题.md` 模块 1
|
||||
- 原型出处：`需求分析/2026-09-11-团期模块需求分析.md` §1.2、§2.2.4
|
||||
- 后端缺口工单：#7769（出参补 `daysToDepart` / `minToForm`）、#7770（入参补日期区间筛选与排序）
|
||||
|
||||
## 关联 / 联系人
|
||||
|
||||
- 后端：wx
|
||||
- 前端：mmg
|
||||
@@ -0,0 +1,111 @@
|
||||
---
|
||||
schema: "hl-changelog/v2"
|
||||
ticket: "frontend"
|
||||
title: "前台团期列表子订单展开区联系人绑错字段恒显破折号"
|
||||
consumer: "admin"
|
||||
author: "wx(GIT)"
|
||||
change_type: "前端缺陷"
|
||||
backend_status: "not_required"
|
||||
gateway_status: "not_required"
|
||||
frontend_status: "pending"
|
||||
frontend_owner: "mmg"
|
||||
frontend_ref: ""
|
||||
target_release: ""
|
||||
verified_at: ""
|
||||
status_note: "纯前端条目，后端零改动。GET /v3/admin/order/group-batch/{groupBatchId}/orders 出参未变，联系人字段一直叫 customerName，前台绑成了不存在的 contactName，导致该列恒显破折号。同时该接口已返回的已付/待付/订单状态/支付状态四个字段前台也未使用。后端经核对零缺口。"
|
||||
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
|
||||
在新工单中引用
屏蔽一个用户