docs(changelog): 8801 团期核单页面前端对接指引（列表默认 opsStage=REVIEW + 核算明细按 8714 重写）

2026-10-08 15:25:08 +08:00
@@ -0,0 +1,176 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8801"
+title: "团期核单页面前端对接指引（列表默认 opsStage=REVIEW + 核算明细按 8714 重写）"
+consumer: "admin"
+author: "yst"
+change_type: "修改接口"
+backend_status: "merged"
+gateway_status: "not_required"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "后端 8714 全套已部署测试服，本文为前端对接指引——列表默认传 opsStage=REVIEW；核算明细页按 8714 新契约重写（8 可编辑 tab+暂存+新增行+panel+确认核单），停用旧 audit 只读组件、勿自创聚合复核；预览行日期/规格/房型字段已补值"
+updated_at: "2026-10-08"
+base: "dev-v3"
+---
+
+# 团期核单页面 · 前端对接指引（后端已就绪，测试服已部署实测通过）
+
+> 面向：管理后台前端（hl-admin）
+> 日期：2026-10-08 ｜ 后端：order-v3 已部署测试服，接口实测 200
+> 本文性质：**前端对接指引**（非新契约）。完整字段表 / 枚举 / 错误码 / 3 组示例以同仓主契约为准：
+> `changelogs-v2/2026-10/04_8714_团期核单重做8类tab明细+公摊拆账-修改接口-管理后台.md`
+
+---
+
+## 一、接口背景
+
+团期核单（结算）页面后端已在 8714 整体重做：旧「四表模型」的 `/audit/*` 6 个只读端点**全部下线 404**，替换为 8 个可编辑分类 tab 明细 + 整 tab 暂存 + 新增/删除行 + 面板 + 确认核单的新契约。8714 全套（含 teamNo 补字段 #8779、确认门禁订正 #8783、alloc-preview 试算 teamNo 订正 #8786、预览行日期/规格/房型补值 #8801）已合并并部署测试服。
+
+当前测试环境核单页面仍是旧样子（有「聚合复核」区块、「分类科目明细」报"明细加载失败"、核算明细只读），需要前端按本文清单重新对接。
+
+---
+
+## 二、变更清单
+
+| # | 改动点 | 类型 | 说明 |
+|---|--------|------|------|
+| 1 | 核单列表页默认传 `opsStage=REVIEW` + `scope=ALL` | 🔧 调用参数修正 | 1 行改动，立刻让核单列表数据变对 |
+| 2 | 核算明细页按 8714 新契约整页重写 | ⚠️ 页面级重做 | 8 可编辑 tab + 暂存 + 新增行 + panel + 确认核单；停用旧 audit 组件 |
+
+---
+
+## 三、核单列表页 `/finance/settlement`（1 行改动，先做）
+
+调 `GET /v3/admin/order/group-batch` 时**默认传 `opsStage=REVIEW`**。
+
+- 现状：没传 → 后端返回全量 76 条（招募中/已取消/资源准备中全混入），所以列表"数据不对"。
+- 修法：传 `opsStage=REVIEW` → 精确返回核单三态：
+  - `PENDING_REVIEW` 待核单
+  - `REVIEWING` 核单中
+  - `SETTLED` 已结算
+- ⚠️ 核单三态的团期返团日可能已过，列表需带 `scope=ALL`（缺省 `ONGOING` 会滤掉已返团的团期）。
+- 列表口径完整契约：`changelogs-v2/2026-10/01_8671_团期核单页签扩为核单三态-修改接口-管理后台.md`
+
+---
+
+## 四、核算明细页（点进团期后）—— 重点，按新契约重写
+
+### 4.1 两个「不要」
+
+1. ❌ **不要复用旧只读组件** `order-v2/batch/detail/components/audit/SettlementCategoryTab.vue`（旧「四表模型」时代的只读 audit 组件）。8714 已把旧 `/audit/*` 6 个端点**全部下线，调用返回 404**，旧组件调它们必然"明细加载失败"。
+2. ❌ **不要自创「聚合复核」区块**。目标样式里没有这个东西。
+
+### 4.2 目标样式（要做成这样）
+
+```
+┌ 团号 26-8290  [待核算]            操作日志   ①基础信息与尾款 > ②核算明细 ┐
+│ [住宿][门票/游玩][餐食][车辆][导游][摄影师][其他收入][其他支出]            │  ← 8 分类页签
+│ ┌ 门票/游玩项目核算明细 [当前分类]                          [暂存][+新增项目] ┐ │
+│ │ 共 6 条 · 分类合计 ¥335.00                                            │ │
+│ │ 日期|项目名称|票种规格|数量|核算单价|付款类型|核算金额|确认状态|备注来源|凭证 │ │  ← 可编辑表格
+│ │ ...（行内可编辑：日期/单价/付款类型下拉/确认状态下拉/凭证上传）            │ │
+│ └───────────────────────────────────────────────────────────────┘ │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 4.3 后端接口全齐（路径前缀 `/v3/admin/order/group-batch/{groupBatchId}/settlement`）
+
+| 用途 | 方法/路径 | 说明 |
+|---|---|---|
+| 8 tab 读 | `GET …/{hotels\|activities\|meals\|vehicles\|guide-fees\|photographer-fees\|other-incomes\|other-expenses}` | 返回该 tab 明细行 |
+| 8 tab 暂存 | `PUT …/{同上 8 段}` | 整 tab 全量替换 + `expectedVersion` 乐观锁 |
+| 新增行 | `POST …/lines` | 单条明细新增 |
+| 删行 | `DELETE …/lines/{lineId}?category=&expectedVersion=` | 级联删拆账 |
+| 面板 | `GET …/panel` | 状态主行 + 8 类合计 + 在团户视图 |
+| 确认核单 | `POST …/panel/confirm` | ⚠️ 路径是 `panel/confirm` 不是 `/confirm`；确认后不可逆 |
+| 拆账试算 | `POST …/alloc-preview` | 不落库，录入期预览 |
+| 开票 | `POST …/invoice` | 门禁 = 核单 CONFIRMED |
+
+> ⚠️ 注意：门票·游玩 tab 的路径段是 **`activities`**，但出参里 `category` 恒为 `TICKET`。
+
+### 4.4 分类 tab 读接口出参（GroupSettleTabRespVO）
+
+```
+groupBatchId / category / categoryName / status(DRAFT|CONFIRMED) /
+version(乐观锁,写时回传) / editable(=status==DRAFT,false时禁用全部写交互) /
+budgetTotal / actualTotal / allocatedTotal / lines[]
+```
+
+- **「共 N 条」** = `lines.length`；**「分类合计 ¥x」** = `actualTotal`。
+- **editable=false（已确认）时**，前端禁用 暂存/新增/删除/行内编辑。
+
+### 4.5 明细行 lines[]（LineVO）与目标表格列的映射
+
+| 目标表格列 | 取字段 | 说明 |
+|---|---|---|
+| 日期 | 门票=`dayDate`；住宿=`stayDate`；餐食=`mealDate`（LocalDate，yyyy-MM-dd） | ✅ 后端 2026-10-08 已补值（#8801，之前恒 null），直接取 |
+| 项目名称 | 门票=`scenicName`；住宿=`hotelName`；餐食=`mealName` | 快照名 |
+| 票种/规格 | 门票=`specName`；住宿=`roomTypeName` | ✅ 后端已补值（#8801） |
+| 数量 | 门票=`ticketCount`；住宿=`roomCount`；餐食=`quantity` | |
+| 核算单价 | 门票=`ticketUnitPrice`；其余=`unitPrice`（金额字符串） | |
+| 付款类型 | `paymentMethod`：`SIGNED`签单 / `COMPANY_PAID`对公已付 / `CASH_PAID`现金已付 | 固定 3 值枚举，不走字典 |
+| 核算金额 | `actualAmount`（金额字符串） | |
+| 确认状态 | `confirmStatus`：`UNCONFIRMED`未确认 / `CONFIRMED`已确认 | 下拉 |
+| 备注/来源 | `remark` + `sourceType`：`MANUAL`手工 / `CARRY_OVER`带出 / `BATCH_COST`共享 | |
+| 凭证 | `voucherUrls`（string[]），上传按钮 | |
+
+> 出参是**全类别字段并集**，非本 tab 的特有列恒 null，按当前 category 取本类列即可。金额/ID 一律字符串，前端不要当 number 处理。
+
+### 4.6 写交互注意（重要）
+
+- **整 tab 暂存是全量替换语义**：把本 tab 所有行一起 PUT 回去，`expectedVersion` 填 GET 返回的 `version` 原样回传。
+- **并发冲突**：返回错误码 `589573` 时说明别人改过，**必须重新 GET 读回全量再提交**，不要本地叠加。
+- **CONFIRMED 后所有写口返回错误码 `589568`**，前端靠 `editable=false` 提前禁用。
+- 拆账（公摊/指定报名）枚举与 splits 结构见主契约 8714 §6 与 §5.3，录入期可用 `alloc-preview` 试算。
+
+---
+
+## 五、优先级建议
+
+1. **先做列表（三）**：1 行改动，立刻让核单列表数据变对。
+2. **再做明细页（四）**：大头，按 04_8714 整页重写，删掉旧 audit 组件和「聚合复核」。
+
+后端无遗留问题，接口随时可联调（测试服已部署）。有疑问直接找后端。
+
+---
+
+## 六、影响评估 / 回滚
+
+- 本文是指引类 changelog，**后端本次无新接口契约变更**；契约变更已在 8714 系列 changelog 推送。
+- 旧 `/audit/*` 6 个端点已 404 下线（8714 PR-6 落），前端继续调用只会报错，不存在兼容窗口。
+- 前端改造期间后端无需配合改动；如前端需回退页面，后端不提供旧端点恢复（旧表已 DROP），只能按新契约对接。
+
+---
+
+## 七、注意事项
+
+1. 金额 / ID 字段一律按字符串处理（防 JS Long 精度丢失 + 金额精度）。
+2. `expectedVersion` 乐观锁贯穿暂存 / 删行两个写口，务必原样回传，不要自增。
+3. 确认核单入口 `POST …/panel/confirm` 确认后**不可逆**，前端需二次确认弹窗。
+4. 日期字段（`dayDate`/`stayDate`/`mealDate`）格式 `yyyy-MM-dd`，可能为 null（手工新增行未填时），渲染需兜底。
+
+---
+
+## 八、关联 / 联系人
+
+- 本指引 Issue：https://git.1814.love/wx/HL/issues/8801
+- 本指引 PR：https://git.1814.love/wx/HL/pulls/8802 ｜ commit https://git.1814.love/wx/HL/commit/b0f618c10e
+- 主契约 Issue（8714）：https://git.1814.love/wx/HL/issues/8714
+- 8714 PR 序列：
+  - PR-1 建表迁移：https://git.1814.love/wx/HL/pulls/8716 ｜ commit https://git.1814.love/wx/HL/commit/3bad2ad276
+  - PR-2 DO/Mapper/枚举骨架：https://git.1814.love/wx/HL/pulls/8718 ｜ commit https://git.1814.love/wx/HL/commit/ee90112a2d
+  - PR-3 公摊/指定报名拆账计算器：https://git.1814.love/wx/HL/pulls/8722 ｜ commit https://git.1814.love/wx/HL/commit/34d10981c0
+  - PR-4 8 类 tab + 面板/暂存/确认/开票 Service 与接口：https://git.1814.love/wx/HL/pulls/8737 ｜ commit https://git.1814.love/wx/HL/commit/788b9c1493
+  - PR-5 下游改造（D2 汇总读新 8 表 + 验团门禁切新主表）：https://git.1814.love/wx/HL/pulls/8764 ｜ commit https://git.1814.love/wx/HL/commit/b9f22e3adc
+  - PR-6 旧代码清理 + DROP 旧四表：https://git.1814.love/wx/HL/pulls/8778 ｜ commit https://git.1814.love/wx/HL/commit/30f83ada81
+  - teamNo 补字段（#8779）：https://git.1814.love/wx/HL/pulls/8780 ｜ commit https://git.1814.love/wx/HL/commit/d759fba111
+- 相关口径 changelog（同仓）：
+  - `changelogs-v2/2026-10/04_8714_团期核单重做8类tab明细+公摊拆账-修改接口-管理后台.md`（主契约，必读）
+  - `changelogs-v2/2026-10/04_8783_团期核单确认门禁订正-修改接口-管理后台.md`
+  - `changelogs-v2/2026-10/04_8786_团期核单alloc-preview试算teamNo订正-修改接口-管理后台.md`
+  - `changelogs-v2/2026-10/01_8671_团期核单页签扩为核单三态-修改接口-管理后台.md`（列表口径）
+- 后端负责人：yst（腰苏图）