diff --git a/changelogs-v2/2026-10/01_8680_advance已付台账补预支详情接口-新增接口-管理后台.md b/changelogs-v2/2026-10/01_8680_advance已付台账补预支详情接口-新增接口-管理后台.md new file mode 100644 index 00000000..f4dab430 --- /dev/null +++ b/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 +- 后端负责人:腰苏图