---
schema: "hl-changelog/v2"
ticket: "8693"
title: "fin_advance 抽象化：预支详情三件套反转 + 接通团期级预支进支付管理（#8693）"
consumer: "admin"
author: "yst(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "not_required"
frontend_status: "implemented"
frontend_owner: "mmg"
frontend_ref: "3dddf2de5000943503cd67e6cd3b6e05200333e6"
target_release: "v2.1"
verified_at: "2026-10-02"
status_note: "【反转 #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。"
updated_at: "2026-10-01"
base: "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）
```http
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）
```http
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 不存在
```http
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：https://git.1814.love/wx/HL/issues/8693
- PR：https://git.1814.love/wx/HL/pulls/8698
- merge commit：2ccca1b7b4
- 反转对象：台账 225（#8680，PR #8682）
- Flyway：V20261001_131__fin_advance_abstract_ref.sql
- 后端负责人：腰苏图