feat(finance): ADVANCE 已付台账补预支详情接口 changelog（#8680）

新增 GET /admin/finance/advances/{id}，补齐已付台账 8 页签明细抽屉最后一环。

changelogs-v2/2026-10/01_8680_advance已付台账补预支详情接口-新增接口-管理后台.md

@@ -0,0 +1,159 @@
+---
+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: "pending"
+frontend_owner: ""
+frontend_ref: ""
+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 纯新增，旧前端零影响。"
+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
+- 后端负责人：腰苏图