wx/hl-api-changelog

派生 0

文件

T

Mimingguang 7e0cdffd7d

changelog-filename-gate / validate (push) Failing after 2s

详情

chore(8680): 追记批次 2 收官(7 域全接通,ref 更新 75b56e2f)

2026-10-01 17:03:49 +08:00

7.3 KiB

原始文件 永久链接 Blame 文件历史

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	8680	出纳已付台账 ADVANCE 页签补预支详情接口（#8680）	admin	yst(GIT)	新增接口	deployed	not_required	implemented	hl-admin(claude)	75b56e2f5d27ae0eebd82af183973d5e84d6ce6a	v2.1	2026-10-01	出纳已付台账 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 全绿。	2026-10-01	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 典型：已付款预支单详情

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 边界：订单无团号 / 登记人未登记企微名

GET /admin/finance/advances/{id}
→ 200，teamNo=null / operatorName=null（对应反查为空时降级为 null，不阻塞详情）

8.3 异常：id 不存在

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：wx/HL#8680
PR：wx/HL#8682
merge commit：93e5ee681d8e792a2d110faee5f3356ccb70cf8b
后端负责人：腰苏图

7.3 KiB 原始文件 永久链接 Blame 文件历史 Unescape Escape