160 行
7.3 KiB
Markdown
160 行
7.3 KiB
Markdown
---
|
||
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
|
||
- 后端负责人：腰苏图
|