diff --git a/changelogs-v2/2026-10/01_8693_fin_advance抽象化接通团期级预支-修改接口-管理后台.md b/changelogs-v2/2026-10/01_8693_fin_advance抽象化接通团期级预支-修改接口-管理后台.md new file mode 100644 index 00000000..d31349a9 --- /dev/null +++ b/changelogs-v2/2026-10/01_8693_fin_advance抽象化接通团期级预支-修改接口-管理后台.md @@ -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 +- 后端负责人:腰苏图