wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
文件
main
hl-api-changelog/changelogs-v2/2026-10/08_8801_团期核单页面前端对接指引-修改接口-管理后台.md
T

12 KiB
原始文件 永久链接 Blame 文件历史

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base
schema ticket title consumer author change_type backend_status gateway_status frontend_status frontend_owner frontend_ref target_release verified_at status_note updated_at base
hl-changelog/v2 8801 团期核单页面前端对接指引（列表默认 opsStage=REVIEW + 核算明细按 8714 重写） admin yst 修改接口 merged not_required implemented mmg f7a6eaa1c6a248ed50953def588d46742674e17a v2.1 2026-10-08 后端 8714 全套已部署测试服，本文为前端对接指引——列表默认传 opsStage=REVIEW；核算明细页按 8714 新契约重写（8 可编辑 tab+暂存+新增行+panel+确认核单），停用旧 audit 只读组件、勿自创聚合复核；预览行日期/规格/房型字段已补值。前端已交付(2026-10-08)：核单列表团期 tab 缺省 opsStage=REVIEW 且 REVIEW 时显式带 scope=ALL(对齐 #8671 看板口径)；团期核单详情页删「聚合复核」区块与「分类科目明细」只读壳(GroupCategoryItems 随删,与 AuditTab 同源双实例并行拉同一 tab 系明细加载失败/只读观感病根),核算明细只保留 8714 可编辑 AuditTab;finalize→confirm 财务主链按 8714 §581 保留在底栏;节点筛选清空=「全部节点」全量查(不传 opsStage、仍带 scope=ALL);提交 f18b3bda0+ee8182dcf+945e2a637(8 类合计表按后端复测口径下线);10-08 续:明细行新增/编辑按目标样式行内化(简单字段行内直改,拆账/凭证留弹层,SettlementLineModal 精简为 SettlementAllocModal),提交 7d6ad0d62;同轮拍板「确认核单」与页脚「完成核单」互斥(先确认核单再 finalize,AuditTab 上行 settle-status/承接 finalized 反向置灰)并消歧弹窗确认键「确认核单」→「确认完成」,提交 8170efc58;同日实测订正:已结算老链路团期首读即建行出 DRAFT 核单系 8714 设计行为,反向置灰(finalized 拦确认核单)会卡死补录/回炉,已撤(f7a6eaa1c),确认核单置灰只留「未定稿户」一因 2026-10-08 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（手工新增行未填时），渲染需兜底。

八、关联 / 联系人

在新工单中引用 查看 Git Blame 复制永久链接