diff --git a/changelogs-v2/2026-09/17_frontend_团期物资清单补改数量删除与手工录入-前端优化-管理后台.md b/changelogs-v2/2026-09/17_frontend_团期物资清单补改数量删除与手工录入-前端优化-管理后台.md new file mode 100644 index 00000000..6e5c8e4b --- /dev/null +++ b/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` diff --git a/changelogs-v2/2026-09/17_frontend_团期详情补设置主报账人与流团审批横幅等原型缺口-前端优化-管理后台.md b/changelogs-v2/2026-09/17_frontend_团期详情补设置主报账人与流团审批横幅等原型缺口-前端优化-管理后台.md new file mode 100644 index 00000000..611dec45 --- /dev/null +++ b/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。