---
schema: "hl-changelog/v2"
ticket: "frontend"
title: "答复前端《待后端支持事项汇总》（2026-09-26）非车务五项：四项后端早已交付且 hl-admin 已接入可销项，应收台账菜单缺口已记 #8369"
consumer: "admin"
author: "jw(GIT)"
change_type: "前端优化"
backend_status: "not_required"
gateway_status: "verified"
frontend_status: "not_required"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "答复 mmg 2026-09-26《前端待后端支持事项汇总》第 1/2/3/4/7 项（车务第 5/6/8/9 项不在本篇）。结论：①002 待收已由 #8045 unpaidAmount 交付（不是 balanceAmount），BatchHero.vue:147 已直显；②0 子订单行 chips 自 #7189 起六项 TODO，TEST 294 行 chips=null 为 0；③003 totalPrice + birthdayInTrip 跨年修正已交付（#6905 §十一 / #7066），estimatedCost 与预计毛利列已随 #7536 下线；④008 opsStage 已交付（#6926，#8271 起七桶），hl-admin index.vue:547 已传参；⑦应收台账 sys_menu 确实缺（TEST 库收款管理下只有 0601~0603），已记 #8369，前端零改动。前 4 项接口零变更、前端零代码改动，只需从待办清单销项。2026-09-26 经 TEST 网关实测。 前端 2026-09-26 已处理：第 1/2/3/4 项逐一 grep 实证（BatchHero.vue:147 unpaidAmount 直显 / PeriodRow.vue:326 chips 兜底 / batch index.vue 导出已传 opsStage / estimatedCost 全仓零消费仅注释），确认已接入并销项；sync-log 挂起区四条已关闭、#8248 菜单项关联 #8369；给后端的清单文档已同步修订。零代码改动，判 not_required（hl-admin 136973bf 为 sync-log 销项提交）。"
updated_at: "2026-09-26"
base: "dev-v3"
---

# 答复：前端《待后端支持事项汇总》（2026-09-26）非车务五项

> **端**: 管理后台 ｜ **来源**: mmg 2026-09-26《前端待后端支持事项汇总》 ｜ **范围**: 第 1 / 2 / 3 / 4 / 7 项；车务第 5 / 6 / 8 / 9 项不在本篇
>
> **本篇不含任何接口变更**：前 4 项后端早已交付，hl-admin 也早已接入；第 7 项的缺口已记工单。前端要做的只有一件事——**更新待办清单**。

---

## 一、结论先行

| # | 清单事项 | 实际状态 | 前端动作 |
|---|---|---|---|
| 1 | 002 补「待收尾款」字段 | **已交付**：#8045 新增 `unpaidAmount`（字段名不是 `balanceAmount`） | 销项。`BatchHero.vue:147` 已直显，`FinanceTab.vue` 已展示 `totals/items.unpaidAmount` |
| 2 | #6905 行接口 `chips` 恒 null | **已交付**：#7189 起 0 子订单行六项固定 `TODO`，不再为 null | 销项。`PeriodRow.vue:326` 的 `chips \|\| {}` 兜底留着无害 |
| 3 | #6929 003 补 `totalPrice` + 生日跨年 | **已交付**：#6905 §十一 / #7066（#7113 收敛字段名） | 销项。「`totalPrice − estimatedCost` 算预计毛利」一条**作废**：`estimatedCost` 与预计毛利列已随 #7536 下线 |
| 4 | #6926 008 导出补 `opsStage` | **已交付**：#6926，#8271 起按七桶过滤 | 销项。`index.vue:547` 已传 `opsStage` |
| 7 | 应收台账 sys_menu 补配 | **确实缺**：已记 **#8369**（hl-user-service Flyway 补菜单种子） | 前端零改动；清单保留此项，关联 #8369 |

> 行号均指 hl-admin `origin/v2.1` @ `b53414d4`。

---

## 二、逐项证据（2026-09-26 TEST 网关实测 + `origin/dev-v3` @ `355c578d1` 源码）

### 1. 002 团期详情：待收 = `unpaidAmount`

- **字段**：`unpaidAmount` = `max(0, receivableAmount − receivedAmount)`，恒非负、恒非 null，字符串金额（`GroupBatchDetailRespVO.unpaidAmount`，#8045）。
- **TEST 实测**：列表前 40 个团逐个调 `GET /v3/admin/order/group-batch/{groupBatchId}`，`unpaidAmount` 缺失或不等于公式的 **0 个**。样例团 `2103733823122690049`：

```json
{ "receivableAmount": "4000.00", "receivedAmount": "2000.00", "unpaidAmount": "2000.00",
  "totalReceivable": "4000.00", "totalReceived": "2000.00" }
```

- **清单原文的两处出入**：
  - 「002 只下发 `totalReceivable` / `totalReceived`」——这两个是 #7535 标了废弃的旧名，002 同时下发新名 `receivableAmount` / `receivedAmount` 和 `unpaidAmount`；
  - 字段名请用 `unpaidAmount`，**不要叫 `balanceAmount`**：同页子订单项已有 `balanceAmount`，是逐户「应收 − 已退 − 已付」、取消单归 0 的另一套口径，混名会在同一屏出现两套数。
- **口径提醒（沿用 #8045）**：`unpaidAmount` 按毛累计已付算，退款不回减；逐户扣退款的权威待收在财务 tab 的 `items[].unpaidAmount` / `totals.unpaidAmount`（财务 tab 顶层 `unpaidAmount` 与 002 同源同值）。hl-admin 现有实现与此一致。
- **既有交接件**：`2026-09/21_8045_团期详情返回整团待收unpaidAmount-修改接口-管理后台.md`（verified 2026-09-21，hl-admin `e680cf10`）。

### 2. 001 团期看板行：`chips` 不再为 null

- **源码**：`GroupBatchQueryService.resolveChipsMap` 对本页每个 `productBatchId` 都派生六芯片，0 子订单按零户口径出六项 `TODO`（#7189，两条基底统一）；`order_group_batch.product_batch_id` 为 NOT NULL，不存在取不到芯片的行。
- **TEST 实测**：
  - `GET /v3/admin/order/group-batch?scope=ALL` 全量 **294 行**，`chips=null` **0 行**；其中 `orderCount=0` 的 76 行六项均为 `TODO`，样例团 `2103060033518661633`：

```json
{ "hotel": "TODO", "vehicle": "TODO", "guide": "TODO", "photo": "TODO", "contract": "TODO", "insurance": "TODO" }
```

  - 带 `productId` 的合并基底（产品 `2100839045562077186`，11 行，其中 7 行未建团）：`chips=null` **0 行**。
- **既有交接件**：`2026-09/07_7189_团期看板产品全班期基底与scope范围筛选-修改接口-管理后台.md`（verified 2026-09-08）。

### 3. 003 团期子订单列表：`totalPrice` 与 `birthdayInTrip`

- **`totalPrice`**：本户应收 = `orderAmount + surchargeAmount − discountAmount`（下限 0），JSON 字符串两位小数；取消单返回 `"0.00"`（清单写的 `"0"` 以 `"0.00"` 为准）。
- **`birthdayInTrip` 跨年修正**：行程跨年时按出团年、返团年各年化比较一次，任一落在 `[departDate, endDate]` 即 true（`GroupBatchQueryService.inTripWindow`，#6929）。
- **TEST 实测**：遍历有子订单的团共 **510 条**子订单，`totalPrice` 全部存在且均为字符串；`includeTravelers=true` 时 `travelers[]` 字段为 `name / type / age / birthdayInTrip`。本列表不返回已取消子订单，本次未取到取消单样例，取消单归 `"0.00"` 以 #7066 于 2026-09-04 的 TEST 8 组实测为准。
- **预计毛利作废**：清单「解除后可用 `totalPrice − estimatedCost` 算预计毛利（`estimatedCost` 已可用）」已过时——#7536 已从 003 删除 `estimatedCost`，预计毛利列已下线、毛利改在核单页看（hl-admin `SubOrderTable.vue:114`、`RosterTable.vue:25` 的注释已写明）。
- **既有交接件**：`2026-09/01_6905_团期看板-4-接口对齐补全-GB-ADM-000-001-002-003-修改接口-管理后台.md` §十一、`2026-09/04_7066_团期子订单列表补应收总额-修改接口-管理后台.md`（均 verified）。

### 4. 008 导出：`opsStage` 过滤生效

- **源码**：`GroupBatchBoardStatsController.export` 接收 `opsStage`，Service 经 `GroupBatchStageBuckets.statusCodesOf(opsStage)` 过滤；#8271 起按七桶取值，旧八桶 code 仍兼容。
- **TEST 实测**（`GET /v3/admin/order/group-batch/export`，`scope=ALL`）：

| 请求 | CSV 数据行数 | 同条件列表中该桶行数 |
|---|---|---|
| 不带 `opsStage` | 294 | 294 |
| `opsStage=CONFIGURE` | 205 | 205 |
| `opsStage=RECRUIT` | 36 | 36 |

- hl-admin `src/views/order-v2/batch/index.vue:547` 已传 `opsStage: f.opsStage || undefined`。
- **既有交接件**：`2026-09/04_6926_导出补-opsStage-筛选-+-统计条自校验死代码修正（修改接口）-修改接口-管理后台.md`（verified 2026-09-04）、`2026-09/24_8271_团期看板与详情按六节点展示看板改七桶-修改接口-管理后台.md`。

### 7. 应收台账菜单：确实缺，已记 #8369

- **TEST 库实查**：`hl_user_service.sys_menu` 中「收款管理」（`menu_id=2026090900000000600`）下只有 `…0601` 业务外收入、`…0602` 公司借入、`…0603` 公司借款收回三项，没有应收台账；`origin/dev-v3` 的 Flyway 里也没有这条菜单。
- **工单**：[#8369](https://git.1814.love/wx/HL/issues/8369) 补挂三级菜单「应收台账」，`path` 与 `component` 均为 `/finance/receipt/receivable`（**带前导 `/`**，与同级「业务外收入」等一致；清单原文写的 `finance/receipt/receivable` 以带 `/` 为准），授权 `SUPER_ADMIN / ADMIN / FINANCE`。
- **接口**：`GET /admin/finance/receipt/receivable/page`（#8191）已在 TEST 可用，本项与接口无关。
- **前端**：零改动。页面 `src/views/finance/receipt/receivable/index.vue` 已就绪，菜单种子落库后侧栏自然出现。

---

## 三、给前端待办清单的建议

清单第 1~4 项沿用的是 #6905 / #6926 / #6929 复审返工期的描述，这三张单 2026-09-01~09-04 已关闭，对应交接件 hl-admin 也都已 verified。生成下一版清单前，建议先按 changelog 仓对应文件 frontmatter 的 `frontend_status` 过一遍，已 verified 的直接销项。

## 四、影响范围

- **接口**：零变更（本篇只答复，不改任何契约）。
- **前端代码**：零改动要求。
- **前端动作**：清单第 1 / 2 / 3 / 4 项销项；第 7 项关联 #8369。

## 关联 / 联系人

- 答复人：jw（后端）
- 相关工单：#8045、#7189、#6905、#6929、#7066、#7536、#6926、#8271、#8191、#8369