hl-api-changelog/changelogs-v2/2026-10/01_8693_fin_advance抽象化接通团期级预支-修改接口-管理后台.md

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	8693	fin_advance 抽象化：预支详情三件套反转 + 接通团期级预支进支付管理（#8693）	admin	yst(GIT)	修改接口	deployed	not_required	implemented	mmg	3dddf2de5000943503cd67e6cd3b6e05200333e6	v2.1	2026-10-02	【反转 #8680 台账 225】#8680 昨天新增的 GET /admin/finance/advances/{id} 详情出参里 orderId/orderNo 两字段，本 PR 反转改为 bizType/refId/refNo 三件套（同日开发阶段、前端尚未消费该两字段，按用户拍板直接改不留冗余）。根因：fin_advance 原本直挂 order_id/order_no 是订单级专用结构，团期级预支（order_id 空）审批通过后被显式跳过推送导致钱付不出去（T27-2859 实证）。本 PR 把 fin_advance 重构为 biz_type+ref_id+ref_no+payee_ref_type 抽象关联（对齐同域 fin_reimburse 范式），接通团期级预支进支付管理。影响两接口：①详情接口出参 orderId/orderNo→bizType/refId/refNo（teamNo 口径变化）；②出纳队列 ADVANCE 行新增 refNo 字段（additive）。前端交付(2026-10-02,与后端「前端尚未消费」自述相反,抽屉实际读 orderNo 属破坏点):LedgerDetailDrawer ADVANCE 归属行改按 bizType 分派(订单级「订单号」读 refNo+「团号」读 teamNo 可 null 兜底;团期级「团号」读 refNo,teamNo 同值不重复行),advance.js JSDoc 钉反转口径+ADVANCE_BIZ_TYPES,spec 13 例全绿,提交 3dddf2de。	2026-10-01	dev-v3

finance：fin_advance 抽象化，接通团期级司导预支进支付管理（管理后台）

⚠️ 反转说明：本 changelog 反转 台账 225（#8680） 昨天推送的详情出参 orderId/orderNo 两字段，改为 bizType/refId/refNo 三件套。两字段同日开发阶段、前端尚未消费，按用户拍板直接改不留冗余。

1. 接口背景

团期级司导预支（挂在出团批次下、不挂具体订单，如 T27-2859 给整个团派车司机预支油费）审批通过后，进不了支付管理，钱付不出去。

根因（两层）：

1. 直接根因：fin_advance 财务执行单表直挂 order_id/order_no，是订单级专用结构，无法表达「不挂订单」的团期级预支。
2. 结构根因：订单侧 approveAdvance 对团期级预支显式跳过财务推送（if orderId==null → 跳过），导致审批通过后没有任何财务执行单生成。

本次把 fin_advance 重构为 biz_type + ref_id + ref_no + payee_ref_type 抽象关联（与同域 fin_reimburse 报账执行单的 biz_* 范式对齐），让一张表同时承接订单级和团期级预支，并接通团期级进支付管理的推送链路。

2. 变更清单

#	接口	变更	类型
1	GET /admin/finance/advances/{id}	出参 orderId/orderNo → bizType/refId/refNo；teamNo 口径变化	🔴 修改接口（反转 #8680）
2	GET /admin/finance/cashier/advance/queue	行出参新增 refNo 字段	✅ additive

3. 接口详情

3.1 GET /admin/finance/advances/{id}（详情，修改）

按 fin_advance.advance_id 查单笔预支执行单详情。出参的「归属业务对象」由「订单ID/订单号」改为「bizType/refId/refNo 三件套」，以支持订单级与团期级两种来源。

3.2 GET /admin/finance/cashier/advance/queue（出纳预支队列，additive）

出纳预支待付/已付台账列表。每行新增 refNo 字段，展示该笔预支归属的业务单号（订单号或团号快照）。

4. 入参

两接口入参均无变化（详情 id path 参数；队列 pageNo/pageSize/tab 等查询参数不变）。

5. 出参

5.1 详情 FinAdvanceDetailRespVO（修改部分）

字段	类型	说明	变化
orderId	—	订单ID	🔴 删除，由 refId 承接
orderNo	—	订单号	🔴 删除，由 refNo 承接
bizType	String	归属业务类型：ADVANCE_ORDER 订单级 / ADVANCE_GROUP_BATCH 团期级	✅ 新增
refId	Long(string)	归属业务对象ID：bizType=ADVANCE_ORDER→订单ID；ADVANCE_GROUP_BATCH→出团批次ID	✅ 新增
refNo	String	归属业务单号快照：订单号 或 团号（展示用，冻结不追溯）	✅ 新增
teamNo	String	团号。ADVANCE_ORDER→按 refId 反查 order_main；ADVANCE_GROUP_BATCH→直接=refNo（团号即归属，不再反查）	🟡 口径变化

其余字段（id/advanceNo/orderAdvanceId/payeeStaffId/payeeName/advanceType/amount/purpose/fundAccountId/payFlowId/paidAt/status/operatorName/createTime）不变。

5.2 队列 AdvanceQueueRowRespVO（additive 部分）

字段	类型	说明	变化
refNo	String	归属业务单号（订单号/团号快照，fin_advance.ref_no）。bizNo 保持执行单号不变	✅ 新增

所有 Long 型 ID 均字符串化（@JsonSerialize(ToStringSerializer)），前端按 string 处理。

6. 枚举/数据字典

bizType（预支归属业务类型）

值	含义	refId 指向	refNo 快照
ADVANCE_ORDER	订单级司导预支	order_main.order_id	order_no 订单号
ADVANCE_GROUP_BATCH	团期级司导预支	order_group_batch.group_batch_id	batch_no 团号

payeeRefType（收款人多态类型，仅后端落库，详情/队列出参不透出）

值	payeeStaffId 指向
ORDER_ASSIGNMENT	order_staff_assignment.assignment_id（订单人员配置）
BATCH_STAFF	资源域 staff.staff_id（人员主档，团期级预支候选取自 order_batch_staff）

status（预支执行单状态，不变）

值	含义
APPROVED	已审批（待付款）
PAID	已付款

7. 错误码

错误码	含义	触发
599500	预支单不存在	详情 id 不存在或已软删（不变）
599505	预支快照非法	推送时 bizType/refId/refNo/payeeRefType 为空或枚举非法（后端内部校验，前端无感）

8. 示例

8.1 典型：订单级预支详情（bizType=ADVANCE_ORDER）

GET /admin/finance/advances/2104861782621462530
→ 200
{
  "id": "2104861782621462530",
  "advanceNo": "YZ-202609290001",
  "orderAdvanceId": "2104861625016287233",
  "bizType": "ADVANCE_ORDER",
  "refId": "2100743225424621570",
  "refNo": "HL20260918082629372",
  "teamNo": "26-8707",
  "payeeStaffId": "2100747615736897537",
  "payeeName": "刘大山",
  "advanceType": "CATERING",
  "amount": 260.0,
  "purpose": "满洲里中俄边境午餐代垫",
  "fundAccountId": "1962000000000008001",
  "payFlowId": "2105436186380242945",
  "paidAt": "2026-10-01 00:00:00",
  "status": "PAID",
  "operatorName": "金卫",
  "createTime": "2026-09-29 17:12:10"
}

8.2 边界：团期级预支详情（bizType=ADVANCE_GROUP_BATCH）

GET /admin/finance/advances/{id}
→ 200
{
  "bizType": "ADVANCE_GROUP_BATCH",
  "refId": "2104950790684889089",
  "refNo": "T27-2859",
  "teamNo": "T27-2859",
  ...
}

团期级 teamNo 直接等于 refNo（团号即归属，不再反查 order_main）。

8.3 异常：id 不存在

GET /admin/finance/advances/999999999999999999
→ {"code":599500,"message":"预支单不存在","data":null,"success":false}

9. 业务边界

• 详情出参不再有 orderId/orderNo：要跳订单维度预支列表，用 bizType=ADVANCE_ORDER 时取 refId 作为订单ID；团期级（ADVANCE_GROUP_BATCH）无订单概念。
• refNo 是快照字段（冻结不追溯），仅作展示；不做关联查询键。
• teamNo 对团期级 = refNo（团号），对订单级 = 反查 order_main（订单无团号 → null）。
• 队列行 bizNo 保持执行单号（YZ- 前缀）不变，新增 refNo 专用于展示归属业务单号。

10. 修改前后对比

详情接口出参

字段	修改前（#8680）	修改后（本 PR）
归属业务对象	orderId + orderNo（仅订单级）	bizType + refId + refNo（订单级/团期级通用）
团号 teamNo	按 orderId 反查 order_main	订单级反查 order_main；团期级 = refNo 直出

队列接口出参

字段	修改前	修改后
归属业务单号	无（只有 bizNo 执行单号）	新增 refNo（订单号/团号）

11. 影响评估/回滚

• 前端影响：详情出参 orderId/orderNo 被删。同日开发阶段、前端尚未消费这两字段（#8680 昨天刚合，前端按台账 225 的对接尚未上线消费），按用户拍板直接改不留冗余，无破坏性。队列 refNo 是 additive，旧前端零影响。
• 数据迁移：存量订单级执行单由 Flyway V20261001_131 自动回填 biz_type=ADVANCE_ORDER/ref_id=order_id/ref_no=order_no，部署时自动跑，无需手工干预。order_id/order_no 列已物理删除。
• 回滚：代码层 revert PR 即可；DDL 层 order_id/order_no 已 DROP 不可回滚（开发阶段接受）。

12. 注意事项

• Long 型 ID 全部是 string，前端勿按 number 解析。
• bizType 是判断归属业务类型的唯一权威字段，前端勿再用 orderId 是否为空判断订单级/团期级。
• refId/teamNo/operatorName 可能为 null（反查为空降级），前端做空值兜底展示。
• 本接口为只读查询，鉴权走网关 /admin/** 常规 JWT。

13. 关联/联系人

• Issue：wx/HL#8693
• PR：wx/HL#8698
• merge commit：2ccca1b7b4
• 反转对象：台账 225（#8680，PR #8682）
• Flyway：V20261001_131__fin_advance_abstract_ref.sql
• 后端负责人：腰苏图