docs(changelog): fin_advance 抽象化接通团期级预支，反转 #8680 详情出参（#8693）
changelog-filename-gate / validate (push) Failing after 2s
changelog-filename-gate / validate (push) Failing after 2s
这个提交包含在：
yaosutu
@@ -0,0 +1,195 @@
|
||||
---
|
||||
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: "not_required"
|
||||
frontend_owner: ""
|
||||
frontend_ref: ""
|
||||
target_release: "v2.1"
|
||||
verified_at: "2026-10-01"
|
||||
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）。"
|
||||
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
|
||||
- 后端负责人：腰苏图
|
||||
在新工单中引用
屏蔽一个用户