changelog(frontend): 团期看板对齐后端契约待办汇总——第N期标题 / scope 班期范围 / 出行完毕页签 / 未建团行交互 / 芯片计数（依赖后端 #7246）
changelog-filename-gate / validate (push) Successful in 2s
changelog-filename-gate / validate (push) Successful in 2s
这个提交包含在：
API Changelog Bot
@@ -0,0 +1,193 @@
|
|||||||
|
---
|
||||||
|
schema: "hl-changelog/v2"
|
||||||
|
ticket: "frontend"
|
||||||
|
title: "团期看板对齐后端契约待办汇总（第N期 / 班期范围 scope / 出行完毕页签 / 未建团行交互 / 芯片计数）"
|
||||||
|
consumer: "admin"
|
||||||
|
author: "wx(GIT)"
|
||||||
|
change_type: "前端优化"
|
||||||
|
backend_status: "deployed"
|
||||||
|
gateway_status: "verified"
|
||||||
|
frontend_status: "pending"
|
||||||
|
frontend_owner: "mmg"
|
||||||
|
frontend_ref: ""
|
||||||
|
target_release: ""
|
||||||
|
verified_at: "2026-09-07"
|
||||||
|
status_note: "后端 #7188 / #7189 / #7190 三单已全部合并并部署测试服 dev-v3、网关实测通过（合并提交 a5eacefd / ac0ffb02 / ccb4d8fd），三份 changelog 分别在 06_7188 / 07_7189 / 06_7190。hl-ui gitea/v2.1（20eb2a19，2026-09-07）尚未消费这些字段，导致 wx 在测试服看到：行标题没有「第7期」、产品页签写「8 期」而看板只显 2 行、状态页签缺「出行完毕」。本篇是这三份 changelog 的前端待办汇总，不重复接口契约，只给现状 file:line 与期望效果。第 5 项芯片计数依赖后端 #7246，其 changelog 发布后再做。"
|
||||||
|
updated_at: "2026-09-07"
|
||||||
|
base: "dev-v3"
|
||||||
|
---
|
||||||
|
|
||||||
|
# 团期看板：对齐后端契约的前端待办汇总（前端优化）
|
||||||
|
|
||||||
|
## ⚠️ 关键变化
|
||||||
|
|
||||||
|
后端 #7188 / #7189 / #7190 已上线且实测通过，但 hl-ui 尚未消费新字段与新参数，现场表现为三个「看起来像 bug」的现象。本篇把待办逐条列清，**后端零改动**（第 5 项例外，依赖后端 #7246）。
|
||||||
|
|
||||||
|
| # | 现象 | 根因 | 后端已给什么 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| 1 | 行标题只有「没，那你」，没有「第7期」 | 前端没读 `batchLabel` | 分页 / 看板 / 详情三处都返 `batchLabel`（实测 10-01 期 `"7"`、12-01 期 `"8"`） |
|
||||||
|
| 2 | 产品页签写「8 期」，看板「全部期」只有 2 行 | 前端不传 `scope`，后端在传 productId 时缺省按「未结束」过滤 | `scope=ONGOING / FINISHED / ALL` 四端点同名同义 |
|
||||||
|
| 3 | 状态页签缺「出行完毕」 | 前端页签表硬编码 7 个 | 统计条固定返 8 键，含 `TRIP_FINISHED` |
|
||||||
|
| 4 | 未建团行点进去会报错 | 前端未按 `groupBatchId=null` 分支渲染 | 分页项 `groupBatchId` 可为 null，另有 `productBatchRemoved` 标孤儿行 |
|
||||||
|
| 5 | 芯片整格红，看不出哪户出了问题 | 现契约只给一个状态字符串 | 待后端 #7246 透出 `chipStats` 计数 |
|
||||||
|
|
||||||
|
**已修无需再动**：「展开行子订单列表恒空」（changelog `06_frontend_团期看板展开行子订单列表恒空-前端缺陷-管理后台.md`）在 `gitea/v2.1` 20eb2a19 已修复——`src/stores/orderV2Batch.js:44` 的 `ordersByBatch` 按 groupBatchId 键缓存已落地（`:166-173` 写入），`PeriodRow.vue:248-249` 注释也已说明不再依赖 `currentGroupBatchId`。
|
||||||
|
|
||||||
|
**桶中文文案不改**：沿用前端现有「待审核 / 已审核 / 流团」，与 #7190 changelog 写明的「前端页签文案沿用现有」一致；新增的第八个页签用「出行完毕」。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 一、背景
|
||||||
|
|
||||||
|
wx 2026-09-06 至 09-07 在测试服（管理后台「团期订单」看板，产品「冻干粉发短信给」productId=2044306857534636034）逐项核对，四个现象经 BUG 分析员对 origin/dev-v3 源码与网关实测取证，结论是三条前端未跟进、一条是测试数据（详见第六节）。
|
||||||
|
|
||||||
|
后端三单的接口契约分别在：
|
||||||
|
|
||||||
|
- `changelogs-v2/2026-09/06_7188_团期看板列表详情透出第N期batchLabel-修改接口-管理后台.md`
|
||||||
|
- `changelogs-v2/2026-09/07_7189_团期看板产品全班期基底与scope范围筛选-修改接口-管理后台.md`
|
||||||
|
- `changelogs-v2/2026-09/06_7190_团期状态新增出行完毕TRIP_FINISHED看板八桶-修改接口-管理后台.md`
|
||||||
|
|
||||||
|
本篇只写「前端该改哪里、改成什么样」，字段语义与请求参数以上述三份为准。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 二、逐条待办
|
||||||
|
|
||||||
|
### 1. 行标题与详情头显示「第N期」
|
||||||
|
|
||||||
|
**现状**（ref `gitea/v2.1` 20eb2a19）
|
||||||
|
|
||||||
|
- `src/views/order-v2/batch/components/PeriodRow.vue:179-184`：`title` computed 依次取 `batchName / groupBatchName / name / periodName`，不含 `batchLabel`。
|
||||||
|
- `src/views/order-v2/batch/detail/components/BatchHero.vue:74-75`：同样只取 `batchName` 系列。
|
||||||
|
- 全仓 `batchLabel` 只在 `views/order-v2/new/components/Step3Confirm.vue`、`views/product/edit/components/steps/BatchPricingStep.vue`、`views/product/line/components/BatchPanel.vue` 命中，看板与团期详情零命中。
|
||||||
|
|
||||||
|
**期望**
|
||||||
|
|
||||||
|
```js
|
||||||
|
const title = computed(() => {
|
||||||
|
const name = props.row.batchName || props.row.groupBatchName || props.row.name || props.row.periodName || '团期'
|
||||||
|
return props.row.batchLabel ? `第${props.row.batchLabel}期 ${name}` : name
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
`batchLabel` 是数字字符串（`"7"`），**不要**当数字做算术或当排序键；存量团期在下一次该班期下单刷新快照前可能为 null，必须兜底成只显名称。详情头同规则。
|
||||||
|
|
||||||
|
### 2. 新增「班期范围」筛选，三处请求同传 scope
|
||||||
|
|
||||||
|
**现状**
|
||||||
|
|
||||||
|
- `src/stores/orderV2Batch.js:76` `fetchSummary` 与 `:93` `fetchBatchPage` 都不传 `scope`；看板相关文件全仓 `scope` 零命中（其它命中在房务日历、待办、订单调整快照，与本处无关）。
|
||||||
|
- 结果：传 productId 时后端按缺省 `ONGOING` 只回未结束班期，产品 2044306857534636034 的 8 期里只剩 10-01 与 12-01，而左侧产品页签的 `batchCount` 是 product 侧全部班期数（8），同屏两个口径。
|
||||||
|
|
||||||
|
**期望**
|
||||||
|
|
||||||
|
- 筛选区加「班期范围」下拉：未结束 / 已结束 / 全部，对应 `scope=ONGOING / FINISHED / ALL`，**默认「未结束」**。
|
||||||
|
- 列表、统计条、导出**同一组参数同传** `productId / scope / month / keyword`（列表另加 `opsStage / pageNo / pageSize`）。统计条不传 scope 会与列表对不上账。
|
||||||
|
- 用户点后段桶页签（`TRIP_FINISHED` / `AUDITING` / `CHECKED`）时，若当前 scope 不是 ALL，**自动切成 ALL** 再请求（可给一句提示）。后端严格取 scope 与 opsStage 的交集，这三个桶的返团日必然已过，默认「未结束」下交集恒空。
|
||||||
|
|
||||||
|
实测对照（2026-09-07，产品 2044306857534636034）：
|
||||||
|
|
||||||
|
| 请求 | total |
|
||||||
|
|---|---|
|
||||||
|
| 不传 scope（等于 ONGOING） | 2 |
|
||||||
|
| `scope=FINISHED` | 6 |
|
||||||
|
| `scope=ALL` | 8 |
|
||||||
|
|
||||||
|
### 3. 状态页签补「出行完毕」
|
||||||
|
|
||||||
|
**现状**
|
||||||
|
|
||||||
|
- `src/views/order-v2/batch/_shared/batchLifecycle.js:13` `OPS_STAGES` 只有 7 键；`:24-31` `OPS_STAT_TABS` 逐项硬写；`BATCH_STATUS_TO_OPS` 缺 `TRIP_FINISHED`。
|
||||||
|
- 全仓 `TRIP_FINISHED` 与「出行完毕」零命中。
|
||||||
|
|
||||||
|
**期望**
|
||||||
|
|
||||||
|
- 三张表都补 `TRIP_FINISHED`，位置在 `TRAVELLING` 与 `AUDITING` 之间（与后端 `GroupBatchStageBuckets.Bucket` 声明顺序一致），标签「出行完毕」。
|
||||||
|
- 统计条按**键名**读 `buckets.TRIP_FINISHED`，不要按数组索引取值。
|
||||||
|
- 其余七个桶的中文**不改**，沿用现有文案。
|
||||||
|
|
||||||
|
后端统计条实测返回（`GET /v3/admin/order/group-batch/summary?productId=2044306857534636034`）：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"message": "成功",
|
||||||
|
"data": {
|
||||||
|
"total": 2,
|
||||||
|
"buckets": { "RECRUIT": 1, "FORMED": 1, "PENDING_TRIP": 0, "TRAVELLING": 0, "TRIP_FINISHED": 0, "AUDITING": 0, "CHECKED": 0, "DISBANDED": 0 },
|
||||||
|
"subOrderCount": 55
|
||||||
|
},
|
||||||
|
"success": true
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. 未建团行与孤儿行的交互
|
||||||
|
|
||||||
|
**现状**：#7189 起分页在传 productId 时返回三类行，前端尚未区分。
|
||||||
|
|
||||||
|
**期望**
|
||||||
|
|
||||||
|
- `groupBatchId === null`（未建团行，产品建了班期但还没人下单）：不渲染展开箭头、不请求子订单、不显示任何团期操作，只放「新增子订单」，跳 `/order-v2/new?productId={productId}&productBatchId={productBatchId}`。对这类行调团期详情、子订单或团期操作，后端会返 589500「团期不存在」。
|
||||||
|
- `productBatchRemoved === true`（孤儿行，产品侧班期已删但团期仍有活跃子订单）：行尾标「班期已删」灰标签，仍可展开看子订单。
|
||||||
|
- 未建团行的 `chips` 六项固定为 `TODO`，不要当成「有待办」去提醒；它只是零户占位。
|
||||||
|
|
||||||
|
### 5. 芯片红色可解释（依赖后端 #7246）
|
||||||
|
|
||||||
|
**现状**：芯片只返回一个状态字符串，规则是「只要有一户被打回就整格 ERROR（红）」，优先于「进行中」。现场产品 2044306857534636034 的 10-01 期 55 户活跃单里有 1 户处于「驳回给定制师」，房芯片就整格红，运营看不出是 1 户还是 55 户出问题。
|
||||||
|
|
||||||
|
**期望**：wx 2026-09-07 拍板「口径不改，透出计数」。后端 #7246 将在看板列表额外返回 `chipStats.{hotel|vehicle|guide|photo|contract|insurance} = {done, total, error}`（附加对象，`chips` 字符串不变，老前端不受影响）。前端在芯片上加悬停提示：「{done}/{total} 待配」，`error` 大于 0 时追加「、{error} 户已打回」。**后端 #7246 的 changelog 发布后再做**，字段名以那份为准。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 三、契约约束与正确调用方式
|
||||||
|
|
||||||
|
> 本篇不新增接口。以下是消费规则速查，字段详情见三份后端 changelog。
|
||||||
|
|
||||||
|
| 场景 | 正确做法 |
|
||||||
|
|---|---|
|
||||||
|
| 看板默认加载 | 列表与统计条都带 `productId`，都不传 scope（等于 ONGOING），或都显式传 `scope=ONGOING` |
|
||||||
|
| 用户切范围 | 列表、统计条、导出三处**同时**带新的 `scope` |
|
||||||
|
| 点后段桶页签 | 先把 scope 切成 ALL 再请求，否则必然空列表 |
|
||||||
|
| 未建团行 | 只放「新增子订单」，深链带 `productId` 与 `productBatchId` |
|
||||||
|
| 页签「N 期」徽标 | 直接用 `products` 接口的 `batchCount`，不要用列表 total 反推（默认范围不含已结束期） |
|
||||||
|
| 行标题 | `batchLabel ? 第{batchLabel}期 {batchName} : batchName`，null 必须兜底 |
|
||||||
|
| 剩余房 / 剩余名额 | `null` 表示**不限**，不要按 0 判满员 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 四、验证方式
|
||||||
|
|
||||||
|
改完后在测试服（产品「冻干粉发短信给」）逐条核对：
|
||||||
|
|
||||||
|
1. 范围切「全部」，10-01 行标题为「第7期 没，那你」，12-01 行为「第8期 QA-7189-1201」；进详情页头部同样带期号。
|
||||||
|
2. 默认进入时范围显示「未结束」，Network 里列表与统计条都带 `scope=ONGOING`，两边 total 都是 2；切「全部」后都变 8，与页签「8 期」一致；导出请求带同一个 scope。
|
||||||
|
3. 在「未结束」下点「出行完毕」，请求变成 `opsStage=TRIP_FINISHED&scope=ALL`，范围下拉自动跳到「全部」。
|
||||||
|
4. 状态页签共 8 个，顺序为 招募中 / 已成团 / 待出行 / 出行中 / 出行完毕 / 待审核 / 已审核 / 流团；`scope=ALL` 时招募中 7、已成团 1、其余 0。
|
||||||
|
5. 12-01 期那行没有展开箭头、没有团期操作，只有「新增子订单」，点击跳 `/order-v2/new?productId=2044306857534636034&productBatchId=2096631555760807938`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 五、不影响范围
|
||||||
|
|
||||||
|
- 后端接口零改动（第 5 项待 #7246）。
|
||||||
|
- 小程序、H5 不涉及。
|
||||||
|
- 团期详情页除头部标题外的其它区域不涉及。
|
||||||
|
- 已修好的「展开行子订单恒空」不要重复改。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 六、附：现场四问题的排查结论
|
||||||
|
|
||||||
|
| 现象 | 结论 |
|
||||||
|
|---|---|
|
||||||
|
| 行标题没有「第7期」 | 前端未跟进（后端三接口都已返 `batchLabel="7"`） |
|
||||||
|
| 「全部期」只剩 2 期 | 前端未跟进（后端默认 `scope=ONGOING` 是 2026-09-06 拍板口径，`scope=ALL` 实测回 8 期） |
|
||||||
|
| 缺「出行完毕」页签 | 前端未跟进（后端固定返 8 桶） |
|
||||||
|
| 房芯片红但「没配房」 | **不是 bug**：红色代表「有户需人工介入」，该团期 55 户里 1 户处于「驳回给定制师」（#7210 验收 AC-22 并发打回的造数单 HL20260907014318542），规则是任一户被打回即整格红，优先于「进行中」。另核对「已订房 54/80 剩 26」三个数字自洽（54+26=80），没有人数与户数混用 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 联系人
|
||||||
|
|
||||||
|
- **后端负责人**: @wx
|
||||||
|
- **前端负责人**: @mmg
|
||||||
在新工单中引用
屏蔽一个用户