---
schema: "hl-changelog/v2"
ticket: "8680"
title: "出纳已付台账 ADVANCE 页签补预支详情接口（#8680）"
consumer: "admin"
author: "yst(GIT)"
change_type: "新增接口"
backend_status: "deployed"
gateway_status: "not_required"
frontend_status: "implemented"
frontend_owner: "hl-admin(claude)"
frontend_ref: "75b56e2f5d27ae0eebd82af183973d5e84d6ce6a"
target_release: "v2.1"
verified_at: "2026-10-01"
status_note: "出纳已付台账 8 个页签的明细抽屉，7 个域详情接口此前已就绪，唯独 ADVANCE 订单预支是缺口：已付台账 ADVANCE 行 bizId 指向 fin_advance.advance_id，但无单笔详情接口，前端抽屉只能拿流水回单兜底（看不到订单/团号/报账人/用途）。本次新增 GET /admin/finance/advances/{id} 司导预支执行单详情，补齐最后一环。出参含订单/团号/收款人/金额/用途/付讫三列；teamNo 由后端按 orderId 反查 order_main 补齐，前端可据此跳订单维度预支列表。additive 纯新增，旧前端零影响。【前端 2026-10-01 交付】changelog 前提「7 域抽屉已就绪」实证不成立,用户拍板 8 域统一抽屉立项;批次 1 骨架+ADVANCE 已落地(新建 api/finance/advance.js+LedgerDetailDrawer 统一骨架,CashierQueuePage ADVANCE 线「明细」列),其余 7 域随后续批次。checkpoint 全绿,22 例 spec 全绿。【批次 2 同日收官】其余 7 域(EXPENSE/NONBIZ/PAYMENT/PREPAY/STAFF_LOAN/REIMBURSE/COMPANY_LOAN)已全接通:抽屉改配置驱动 8 域分派,字段布局向原型各域详情弹窗对齐,操作列全 8 线统一(专项入口+明细);页面与操作列改动随 f5644271、抽屉组件随 75b56e2f 两提交入库,32 例 spec 全绿。"
updated_at: "2026-10-01"
base: "dev-v3"
---

# finance：出纳已付台账 ADVANCE 页签补预支详情接口（管理后台）

> ✅ **additive 纯新增接口**：新增 `GET /admin/finance/advances/{id}`，旧前端不受影响。

## 1. 接口背景

出纳「已付台账」按业务类型分 8 个页签（NONBIZ/EXPENSE/PAYMENT/PREPAY/STAFF_LOAN/REIMBURSE/COMPANY_LOAN/ADVANCE），每行点「明细」打开抽屉展示该笔业务详情。此前 7 个域都有各自的单笔详情接口，唯独 **ADVANCE 订单预支**没有：已付台账 ADVANCE 行的 `bizId` 指向 `fin_advance.advance_id`（司导预支财务执行单），但后端没有对应的单笔详情查询接口，前端抽屉只能用资金流水回单兜底，看不到订单号、团号、收款人、用途等关键业务信息。

本次补 `GET /admin/finance/advances/{id}`，让 ADVANCE 页签抽屉与其它 7 个页签一样能展示完整业务明细。

## 2. 变更清单

| # | 接口 | 变更 | 类型 |
|---|---|---|---|
| 1 | GET /admin/finance/advances/{id} | 新增司导预支执行单详情 | ✅ 新增接口 |

## 3. 接口详情

`GET /admin/finance/advances/{id}`（业务调用**不带**服务前缀，网关按 `/admin/finance/**` 路由到 order-v3）。

按 `fin_advance.advance_id` 查单笔预支执行单详情，供已付台账 ADVANCE 页签明细抽屉使用。

## 4. 入参

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| id | path | Long | 是 | 预支执行单ID（`fin_advance.advance_id`，即已付台账 ADVANCE 行的 `bizId`） |

## 5. 出参

`FinAdvanceDetailRespVO`：

| 字段 | 类型 | 说明 |
|---|---|---|
| id | Long(string) | 预支执行单ID |
| advanceNo | String | 预支单号（YZ- 前缀） |
| orderAdvanceId | Long(string) | 订单侧预支单ID（order_advance） |
| orderId | Long(string) | 订单ID |
| orderNo | String | 订单号 |
| teamNo | String | 团号（后端按 orderId 反查 order_main 补齐；订单无团号 → null） |
| payeeStaffId | Long(string) | 收款人员工ID |
| payeeName | String | 收款人姓名（报账人/司导） |
| advanceType | String | 预支类型（如 CATERING 餐饮 / FUEL 油费等，见数据字典） |
| amount | BigDecimal | 预支金额 |
| purpose | String | 用途说明 |
| fundAccountId | Long(string) | 出账资金账户ID |
| payFlowId | Long(string) | 付款资金流水ID（可跳流水回单） |
| paidAt | LocalDateTime | 付讫时间 |
| status | String | 状态（APPROVED 已审批 / PAID 已付款） |
| operatorName | String | 登记人姓名（用户域反查 createdBy；未登记企微名 → null） |
| createTime | LocalDateTime | 创建时间 |

> 所有 Long 型 ID 均已字符串化（`@JsonSerialize(ToStringSerializer)`），前端按 string 处理，避免 JS 精度丢失。

## 6. 枚举/数据字典

### status（预支执行单状态）
| 值 | 含义 |
|---|---|
| APPROVED | 已审批（待付款） |
| PAID | 已付款 |

### advanceType（预支类型）
走业务数据字典（如 CATERING 餐饮 / FUEL 油费 / TICKET 门票 等），具体取值以字典接口为准，前端展示走字典 label。

## 7. 错误码

| 错误码 | 含义 | 触发 |
|---|---|---|
| 599500 | 预支单不存在 | id 不存在或已软删 |

## 8. 示例

### 8.1 典型：已付款预支单详情
```http
GET /admin/finance/advances/2104861782621462530
→ 200
{
  "id": "2104861782621462530",
  "advanceNo": "YZ-202609290001",
  "orderAdvanceId": "2104861625016287233",
  "orderId": "2100743225424621570",
  "orderNo": "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 边界：订单无团号 / 登记人未登记企微名
```http
GET /admin/finance/advances/{id}
→ 200，teamNo=null / operatorName=null（对应反查为空时降级为 null，不阻塞详情）
```

### 8.3 异常：id 不存在
```http
GET /admin/finance/advances/999999999
→ {"code":599500,"message":"预支单不存在","data":null,"success":false}
```

## 9. 业务边界

- `teamNo` 由后端按 `orderId` 反查 `order_main` 实时补齐（订单无团号或订单不存在 → null），**非 fin_advance 快照字段**；前端可据此跳「订单维度预支列表」`/v3/admin/order/{orderId}/advances`。
- `operatorName` 反查用户域 createdBy，未登记企微名 / 用户域暂不可用 → 降级为 null（查询类不 fail-fast）。
- 已付台账 ADVANCE 行的 `bizId` 即本接口的 `id`，前端抽屉直接用行 `bizId` 调本接口。

## 10. 修改前后对比

新增接口，无「修改前」。

| 项 | 修改前 | 修改后 |
|---|---|---|
| ADVANCE 页签明细抽屉 | 无详情接口，只能流水回单兜底 | 可调本接口展示完整业务明细 |

## 11. 影响评估/回滚

- additive 纯新增，旧前端零影响；不调用本接口无变化。
- 回滚：删除该 Controller/Service/VO 即可，无 DDL、无数据迁移。

## 12. 注意事项

- Long 型 ID 全部是 string，前端勿按 number 解析。
- `teamNo` / `operatorName` 可能为 null（反查为空降级），前端做空值兜底展示。
- 本接口为只读查询，鉴权走网关 `/admin/**` 常规 JWT。

## 13. 关联/联系人
- Issue：https://git.1814.love/wx/HL/issues/8680
- PR：https://git.1814.love/wx/HL/pulls/8682
- merge commit：93e5ee681d8e792a2d110faee5f3356ccb70cf8b
- 后端负责人：腰苏图