hl-api-changelog/changelogs-v2/2026-09/07_frontend_团期看板对齐后端契约待办汇总-前端优化-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	frontend	团期看板对齐后端契约待办汇总（第N期 / 班期范围 scope / 出行完毕页签 / 未建团行交互 / 芯片计数）	admin	wx(GIT)	前端优化	deployed	verified	verified	mmg	2eb27845		2026-09-08	本篇是 #7188/#7189/#7190 三单的前端待办汇总(行标题第N期 batchLabel / 班期范围 scope 筛选三处同传 / 出行完毕 TRIP_FINISHED 页签 / 未建团行 groupBatchId=null 分支),含精确 file:line 与期望代码。第 5 项芯片计数 tooltip 依赖后端 #7250 chipStats,后端代码已合入 dev-v3(PR #7254),其 changelog 07_7250_* 已于 2026-09-07 通过测试服 AC-1~AC-9 实测后发布(commit 16e0133),依赖已解除,本条可派发;c39fb8a 已修正其文案口径(done=已完成数非待配、error>0≠红因后端有覆盖规则、精确待配需点明细)。2026-09-07 复审后二次修正约/保异常文案:原「{error} 户合同已作废」「{error} 户投保失败」以偏概全(后端合同 error 含作废中+已作废两态、保险 error 含已取消+投保失败两态),改为「{error} 户合同异常」「{error} 户保险异常」,精确原因走明细接口 GB-ADM-094(约)/GB-ADM-095(保);房/车「已打回」两个失败态语义一致,保持不变。前端已识别,按「先完成任务清单」排在 #7067 U2-U7 之后统一派发,本条保持 pending。	2026-09-07	dev-v3

团期看板：对齐后端契约的前端待办汇总（前端优化）

⚠️ 关键变化

后端 #7188 / #7189 / #7190 已上线且实测通过，但 hl-ui 尚未消费新字段与新参数，现场表现为三个「看起来像 bug」的现象。本篇把待办逐条列清，后端零改动（第 5 项例外，依赖后端 #7250）。

#	现象	根因	后端已给什么
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	芯片整格红，看不出哪户出了问题	现契约只给一个状态字符串	待后端 #7250 透出 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 命中，看板与团期详情零命中。

期望

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）：

{
  "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. 芯片红色可解释（依赖后端 #7250）

现状：芯片只返回一个状态字符串，规则是「只要有一户被打回就整格 ERROR（红）」，优先于「进行中」。现场产品 2044306857534636034 的 10-01 期 55 户活跃单里有 1 户处于「驳回给定制师」，房芯片就整格红，运营看不出是 1 户还是 55 户出问题。

期望：wx 2026-09-07 拍板「口径不改，透出计数」。后端 #7250 将在看板列表额外返回 chipStats.{hotel|vehicle|guide|photo|contract|insurance} = {done, total, error}（附加对象，chips 字符串不变，老前端不受影响）。前端在芯片上加悬停提示：「已完成 {done}/{total}」，error 大于 0 时追加异常说明——房/车「{error} 户已打回」、约「{error} 户合同异常」、保「{error} 户保险异常」（或统一「{error} 户异常」）。

约/保为什么只写「异常」不写具体原因（2026-09-07 复审二次修正）：后端 CONTRACT_FAILED = {VOIDING 作废中, VOIDED 已作废}、INSURANCE_FAILED = {CANCELLED 已取消, FAILED 投保失败}，每个都是两态。原口径写「合同已作废」「投保失败」会把正在作废的说成已作废、把主动退保的说成投保失败，以偏概全。要精确原因请点进对应芯片明细接口：约 = GB-ADM-094（GET .../chips/contract）、保 = GB-ADM-095（GET .../chips/insurance），明细里逐户给 status + statusText。

注意三点：done 是已完成户数，不是待办户数，不要写成「{done}/{total} 待配」；这三个数推不出精确的待配户数（现场 55 户里 48 户待房务配、1 户配房中、2 户待审核、3 户未开始、1 户打回，仅凭 done=0 / total=55 / error=1 推不出 48），要精确分布请点进该芯片对应的逐户明细（GB-ADM-090～095，房 090 / 车 091 / 导 092 / 摄 093 / 约 094 / 保 095）；error > 0 不等于芯片一定是红色——团期已流团、已返团（出行完毕 / 核团中 / 已结算）、或房车导摄未全部完成这三种情况下后端有状态覆盖规则，error 仍是真实户数而颜色分别是灰 / 绿 / 灰，颜色请一律以 chips.X 为准。字段名与例外矩阵以后端 changelog 为准：changelogs-v2/2026-09/07_7250_团期看板芯片透出chipStats计数-修改接口-管理后台.md（PR #7254 已合入 dev-v3 47c9a6d29；该篇已于 2026-09-07 通过测试服 AC-1~AC-9 实测并发布，commit 16e0133）。依赖已解除，本项可开工。

---

三、契约约束与正确调用方式

本篇不新增接口。以下是消费规则速查，字段详情见三份后端 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 项待 #7250）。
• 小程序、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