diff --git a/changelogs-v2/2026-10/08_8801_团期核单页面前端对接指引-修改接口-管理后台.md b/changelogs-v2/2026-10/08_8801_团期核单页面前端对接指引-修改接口-管理后台.md new file mode 100644 index 00000000..1ccae7d2 --- /dev/null +++ b/changelogs-v2/2026-10/08_8801_团期核单页面前端对接指引-修改接口-管理后台.md @@ -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（腰苏图）