hl-api-changelog/changelogs-v2/2026-09/17_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	团期详情补设置主报账人与流团审批横幅等原型缺口	admin	wx(GIT)	前端优化	not_required	not_required	verified	mmg	e4da94a6ca7a2897e9022f4983c1dcd0ade0b509		2026-09-17	纯前端条目，后端零改动。2026-09-17 原型×测试环境核对：团期详情有 5 处原型功能前端未做，所需接口与字段均已在 TEST 上线并实调确认。最急的是「设置主报账人」：七项发车硬门第 7 项依赖它，前端全仓无调用，团期无法经界面进入待出发。核团验团相关缺口后端未就绪（另开 #7868~#7873），房务 / 车务缺口由 wx 处理，均不在本条。[mmg 2026-09-17 交付] 五处缺口全部落地：①setGroupBatchStaffReporterRank+ReporterRankModal（候选名册 GUIDE/LEADER，保存后 recheck 第 7 门；路径变量为产品侧 productBatchId）；②DisbandBanner 挂 Hero 下（PENDING 蓝/REJECTED 红，approvalStatusName 不直显，驳回原因二次拉 approveRemark，PENDING 在途禁用发起流团）；③OverviewTab 成团与容量卡（数字全用 detail 真实字段，minToForm−formingRooms 算还差 N 户，操作记录推导手动成团/名额已调）；④底栏 deriveNextStep 纯函数引导；⑤Hero 步骤条 buildOpsStageSteps 用 batchStatus 九态折叠八桶——详情契约不返回 opsStage，本条正文误称 detail.opsStage 已按 01_6905 纠偏，功能3/5 均不读该字段。187 例全过，scoped checkpoint 13 项全绿。	2026-09-17	dev-v3

团期详情补设置主报账人与流团审批横幅等原型缺口（前端优化）

服务: hl-order-service-v3（后端零改动） 页面: 管理后台 /order-v2/batch → 团期详情 原型: 团期需求1/_verify/proto_local/batchDetail.jsx 前端基线: mmg/hl-ui v2.1 @ 15e3d7d（与 TEST 线上产物一致） 日期: 2026-09-17 影响范围: 仅前台；无端点、无出入参、无路由、无 DDL 变化

---

⚠️ 关键变化

🔴 界面上没有「设置主报账人」，团期卡在物料准备中。

七项发车硬门的第 7 项 PRIMARY_REPORTER「主报账人已设」只认 order_batch_staff.reporter_rank=PRIMARY。 后端设置接口早已上线，前端全仓没有调用。TEST 样本团期 2100132795706691585 的该门当前 passed=false、failReason="团期尚未指定主报账人"，界面上没有任何办法补上。

---

一、原型要求 vs 当前渲染

#	原型功能	原型位置	当前前端	所需接口（均已上线）
1	设置主报账人	batchDetail.jsx:880（整团总览底栏 payeeBtn），弹窗 batchOps.jsx「设置报账人」	❌ 无入口	GET/PUT /v3/admin/group-batch/{productBatchId}/staff…
2	流团审批中 / 已驳回横幅	batchDetail.jsx:305-326	⚠️ 提交后仅本地置灰，刷新即恢复	GET …/group-batch/approvals/page、GET …/group-batch/disband/{approvalId}
3	成团 / 容量卡的「（手动成团）」「（名额已调 ±N）」	batchDetail.jsx:398-407	❌ 未显示	GET …/group-batch/{groupBatchId}/status-logs
4	底栏「下一步」引导按钮	batchDetail.jsx:883-906	❌ 无	GET …/group-batch/{groupBatchId}（GB-ADM-002）
5	Hero 阶段步骤条	batchDetail.jsx:287-289（BatchForkSteps）	❌ 无	GB-ADM-002 opsStage

---

二、本次调整

2.1 设置主报账人（优先级最高）

入口：整团总览底栏「设置报账人」，与原型一致。候选为本团已配置的导游 / 领队，即原型「候选（已指派导游）」。

读候选：GET /v3/admin/group-batch/{productBatchId}/staff，前端已有 getGroupBatchStaff。

• 返回数组，每行含 staffId、staffName、staffRole、reporterRank（PRIMARY / SECONDARY / NONE）、reporterRankName
• 当前主报账人 = reporterRank === 'PRIMARY' 的那一行

保存：

PUT /v3/admin/group-batch/{productBatchId}/staff/{staffId}/reporter-rank
Content-Type: application/json

{ "reporterRank": "PRIMARY" }

• ⚠️ 路径变量是产品侧排期 ID productBatchId（详情 productBatchId 字段），不是 groupBatchId，与人员配置弹窗同源
• 团内 PRIMARY / SECONDARY 各唯一：设新主报账人时，原主报账人由后端自动降为 NONE，前端无需先清
• staffId 不是本团已配置人员 → 589508
• 权限码 group-batch:manage（团期管理员已授）
• 成功返回 data: null；之后调 POST …/{groupBatchId}/recheck-departure-gate（前端已有 recheckGroupBatchDepartureGate）或重新拉详情，第 7 门应变为通过

空态：本团未配置导游时，提示「请先在『配导游』里配置人员」，不要让按钮报错。

2.2 流团审批中 / 已驳回横幅

取数：进详情时按团期查最近一条流团审批：

GET /v3/admin/order/group-batch/approvals/page?bizType=DISBAND&groupBatchId={groupBatchId}&pageNum=1&pageSize=1

取最新一条的 approvalStatus	渲染
PENDING	蓝色横幅「流团审批中」，副文案：发起人 applicantName · 理由 reason · 影响 affectedOrderCount 户 · 退定金 estimatedRefundAmount；右侧「去审批中心」
REJECTED	红色横幅「流团申请已被驳回」，副文案 approvedByName 驳回 · 驳回原因；右侧「重新发起流团」
APPROVED / 无记录	不显示横幅

• 驳回原因不在列表里，需再调 GET /v3/admin/order/group-batch/disband/{approvalId}，取 approveRemark（拒绝时必非空）
• 「发起流团」按钮按 PENDING 禁用，不再只靠本地状态（现状刷新即恢复可点，后端 589543 兜底）
• ⚠️ 流团驳回时列表的 approvalStatusName 目前返回「已取消退单」（退单文案），横幅文案请按上表写死，不要直显该字段
• 实测可读角色：ADMIN / GROUP_BATCH_MANAGER / FINANCE 为 200；CUSTOMIZER 为 589507，本就打不开团期详情，不受影响

TEST 实调样本（驳回）：

{ "approvalId": "2100101026999656449", "bizType": "DISBAND", "groupBatchId": "2100047411383513090",
  "approvalStatus": "REJECTED", "affectedOrderCount": 3, "estimatedRefundAmount": 3000.0,
  "reason": "E2E-0916 R2 first disband submit", "applicantName": "admin", "approvedByName": "admin" }

详情 approveRemark: "E2E-0916 R2 reject, revert to clean state"

2.3 成团 / 容量卡的两处标注

原型：满员 {maxRooms} · 已售 … · 剩 … · 已建子订单 …（名额已调 ±N），下方 ✓ 已成团（手动成团）。

两个标注都从操作记录取（前端已有 getGroupBatchStatusLogs，操作记录 Tab 已在用）：

标注	规则
（手动成团）	最近一条 eventType === 'BATCH_GROUP' 的 operatorType === 'ADMIN'；系统自动成团为 operatorType === 'SYSTEM' 且 extra.trigger === 'AUTO'
（名额已调 ±N）	所有 eventType === 'BATCH_CAPACITY_ADJUST' 的 extra.capacityDelta 求和；和为 0 不显示

• 若最近一次成团之后有 BATCH_CANCEL_GROUP，则当前未成团，不显示「手动成团」
• TEST 实测 BATCH_CAPACITY_ADJUST.extra 形如 {"beforeMaxRooms":9,"afterMaxRooms":10,"capacityDelta":1,"reason":"…"}
• 卡片其余数字：满员 maxRooms、已售 enrolledRooms、剩 remainRooms、已建子订单取 GB-ADM-003 的 total；成团态看 opsStage !== 'RECRUIT'。未成团时「还差 N 户」按 max(0, minToForm − formingRooms)，必须用 formingRooms

2.4 底栏「下一步」引导按钮

纯前端推导，数据全在 GB-ADM-002。按原型 batchDetail.jsx:883-906 的顺序：

Tab	条件（从上往下取第一条）	按钮
整团总览	已成团且 requirementConfirmed=false	去催需求 → 查看需求 Tab
整团总览	四个 *Ready 未全为 true	去配置资源 → 配房 Tab
整团总览	materialConfirmed=false	去准备物资 → 物资 Tab
查看需求	requirementConfirmed=true	需求无误 · 去配置资源
配房 / 配车 / 导游 / 摄影	四项已齐	配置完成 · 去准备物资；否则「下一项 · 车辆 / 导游 / 摄影」

• 原型的「去确认无误」不做：人工总检已改为系统七项硬门（整团总览「发车硬门」块已有）
• 原型的「企微催需求」不做：接口文档无契约

2.5 Hero 阶段步骤条

按 opsStage 高亮当前段，段序取后端运营八桶： RECRUIT 招募中 → FORMED 已成团 → PENDING_TRIP 待出行 → TRAVELLING 出行中 → TRIP_FINISHED 出行完毕 → AUDITING 核团中 → CHECKED 已验团，分叉 DISBANDED 已流团。

• 中文直显 opsStageName，不建映射
• opsStage 为 null（脏数据）时不渲染步骤条

---

三、不在本条范围

缺口	原因 / 去向
核团验团 Tab、验团归档按钮、开票、导出核单	后端未就绪，已开 #7868 ~ #7873
查看需求的逐户用房 / 用车明细、配车 Tab 车辆司机明细、接送机、联系车务、导出分房表	房务 / 车务，wx 处理中
企微催需求 / 催报名、与导游摄影调度沟通	接口文档无契约
状态生命周期独立 Tab	已由「操作记录」时间线兼任，维持现状

---

四、验证建议

1. 主报账人：在 TEST 物料准备中的团里配一名导游，设为主报账人，点「重新校验」。第 7 门由红变绿；再换另一人为主，原主在名册里变为 NONE。
2. 横幅：发起流团后刷新页面，横幅仍在、「发起流团」仍禁用；在审批中心驳回后回到详情，显示红色横幅与驳回原因。
3. 标注：对一个团调整名额 +1 再 −2，卡片显示「（名额已调 −1）」；手动成团的团显示「（手动成团）」，自动成团的不显示。
4. 引导按钮：在资源未配齐的团上，整团总览底栏出现「去配置资源」并跳到配房 Tab。