diff --git a/changelogs-v2/2026-09/15_frontend_前台团期列表页漏展示已返回字段-前端优化-管理后台.md b/changelogs-v2/2026-09/15_frontend_前台团期列表页漏展示已返回字段-前端优化-管理后台.md new file mode 100644 index 00000000..64a8d765 --- /dev/null +++ b/changelogs-v2/2026-09/15_frontend_前台团期列表页漏展示已返回字段-前端优化-管理后台.md @@ -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 diff --git a/changelogs-v2/2026-09/15_frontend_前台子订单展开区联系人绑错字段-前端缺陷-管理后台.md b/changelogs-v2/2026-09/15_frontend_前台子订单展开区联系人绑错字段-前端缺陷-管理后台.md new file mode 100644 index 00000000..aea9b5c5 --- /dev/null +++ b/changelogs-v2/2026-09/15_frontend_前台子订单展开区联系人绑错字段-前端缺陷-管理后台.md @@ -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 +{{ o.contactName || '—' }} +``` + +而该接口的出参里**没有 `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