docs(changelog): 团期原型核对的两条纯前端缺口（团期详情主报账人/流团横幅等、物资改删与手工录入）

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

changelogs-v2/2026-09/17_frontend_团期物资清单补改数量删除与手工录入-前端优化-管理后台.md

@@ -0,0 +1,120 @@
+---
+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: "纯前端条目，后端零改动。SuppliesPanel.vue:76 注释「调整数量 / 删除行 / 手工录入待后端补契约后接入」已过时——三个能力后端均已上线（改数量 PUT、删除 DELETE、手工录入复用 POST 的 suppliesName 分支，#6986）。原型「物资清单」Tab 的添加 / 删除操作因此可直接接入。"
+updated_at: "2026-09-17"
+base: "dev-v3"
+---
+
+# 团期物资清单补改数量删除与手工录入（前端优化）
+
+> **服务**: hl-order-service-v3（后端零改动）
+> **页面**: 管理后台 `/order-v2/batch` → 团期详情 → 物资 Tab
+> **组件**: `src/views/order-v2/batch/detail/components/SuppliesPanel.vue`、`SuppliesPickerModal.vue`
+> **原型**: `团期需求1/_verify/proto_local/batchDetail.jsx`「物资清单」Tab
+> **前端基线**: `mmg/hl-ui` v2.1 @ `15e3d7d`
+> **日期**: 2026-09-17
+> **影响范围**: 仅前台；无端点、无出入参、无路由、无 DDL 变化
+
+---
+
+## ⚠️ 关键变化
+
+🔵 **组件注释已过时。** `SuppliesPanel.vue:76` 写着「调整数量 / 删除行 / 手工录入**待后端补契约**后接入」，
+这三项后端都已上线，可以直接接。
+
+---
+
+## 一、原型要求 vs 当前渲染
+
+| 原型功能 | 当前前端 | 后端接口 |
+|---|---|---|
+| 物资清单表 | ✅ 已有（候选列表 `added` 标记） | `GET …/{groupBatchId}/supplies/candidates` |
+| 从备品库加入 | ✅ 已有 | `POST …/{groupBatchId}/supplies`（传 `suppliesResourceId`） |
+| **添加物资（名称 + 数量规格）手工录入** | ❌ 缺 | 同一个 `POST`，传 `suppliesName` 不传 `suppliesResourceId` |
+| **行内改数量** | ❌ 缺 | `PUT …/supplies/{batchSuppliesId}/quantity` |
+| **删除物资（行尾 ✕）** | ❌ 缺 | `DELETE …/supplies/{batchSuppliesId}` |
+| 确认物资清单 | ✅ 已有 | `POST …/{groupBatchId}/confirm-material` |
+
+接口前缀均为 `/v3/admin/order/group-batch`。
+
+---
+
+## 二、本次调整
+
+### 2.1 已选清单改用团期物资列表
+
+改数量、删除都要行 ID。建议已选清单直接读：
+
+```http
+GET /v3/admin/order/group-batch/{groupBatchId}/supplies
+```
+
+每行字段：`id`（即 `batchSuppliesId`）、`suppliesResourceId`（手工录入行为 null）、`suppliesName`、`category`、`hasCost`、`billingType`、`unitPrice`、`quantity`、`sortOrder`、`remark`。
+
+候选接口的 `batchSuppliesId` 也能用，但手工录入的行不在候选库里，只有这个列表能看到。
+
+### 2.2 手工录入
+
+```http
+POST /v3/admin/order/group-batch/{groupBatchId}/supplies
+Content-Type: application/json
+
+{ "suppliesName": "急救包", "category": "…", "quantity": 2, "remark": "规格：大号" }
+```
+
+- `suppliesName` 与 `suppliesResourceId` **二选一**：不传库 ID 时名称必填，否则报「备品名称不能为空（未指定备品库 ID 时必填）」
+- `quantity` 必填
+- 可选：`category`（字典 `supplies_category`）、`hasCost`、`billingType`、`unitPrice`、`sortOrder`、`remark`
+- 原型「数量规格」一栏：数量进 `quantity`，规格文字进 `remark`
+
+### 2.3 改数量
+
+```http
+PUT /v3/admin/order/group-batch/supplies/{batchSuppliesId}/quantity
+Content-Type: application/json
+
+{ "quantity": 3 }
+```
+
+⚠️ 路径里**没有** `groupBatchId`。
+
+### 2.4 删除
+
+```http
+DELETE /v3/admin/order/group-batch/supplies/{batchSuppliesId}
+```
+
+软删，删除后重新拉 2.1 的列表。
+
+### 2.5 共同约束
+
+- **阶段门**：三个写操作只在团期 `batchStatus = MATERIAL_PREPARING` 时放行，其他阶段返回 `589520`「物资清单只能在『准备物资』阶段配置」。按钮按同一条件显隐或置灰，与现有「确认物资」一致
+- **权限**：写操作 `group-batch:manage`，列表 `group-batch:view`（团期管理员均已授）
+- 物资确认后是否仍允许改：后端只看阶段（jw 2026-09-02 / 09-03 两次确认「只要还在准备物资就放行」），**前端不要另加只读判断**
+
+---
+
+## 三、不在本条范围
+
+- 物资确认、从备品库选择：已上线，不改
+- 备品库本身的维护（资源 → 备品）：另一模块
+
+---
+
+## 四、验证建议
+
+1. 在 TEST 物料准备中的团里手工录入「急救包 ×2」，列表出现该行，`suppliesResourceId` 为空
+2. 改数量为 3，刷新后仍为 3；删除后该行消失
+3. 找一个资源准备中的团，三个写按钮不可用；强行调用返回 `589520`

changelogs-v2/2026-09/17_frontend_团期详情补设置主报账人与流团审批横幅等原型缺口-前端优化-管理后台.md

@@ -0,0 +1,164 @@
+---
+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: "纯前端条目，后端零改动。2026-09-17 原型×测试环境核对：团期详情有 5 处原型功能前端未做，所需接口与字段均已在 TEST 上线并实调确认。最急的是「设置主报账人」：七项发车硬门第 7 项依赖它，前端全仓无调用，团期无法经界面进入待出发。核团验团相关缺口后端未就绪（另开 #7868~#7873），房务 / 车务缺口由 wx 处理，均不在本条。"
+updated_at: "2026-09-17"
+base: "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'` 的那一行
+
+**保存**：
+
+```http
+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 流团审批中 / 已驳回横幅
+
+**取数**：进详情时按团期查最近一条流团审批：
+
+```http
+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 实调样本（驳回）：
+
+```json
+{ "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。