hl-api-changelog/changelogs-v2/2026-09/15_7428_预付款功能后端就绪前端补菜单页面-新增接口-管理后台.md

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	7428	预付款功能：后端全链路已就绪，前端需补「预付款」菜单与页面	admin	yst(GIT)	新增接口	deployed	verified	required				2026-09-15	预付款域（#7428）后端全链路接口已就绪并部署：申请/编辑/删除/提交/批准/驳回/分页/详情 + 出纳付款(cashier/pay bizType=PREPAY) + 冲抵余额(available_amount)。但真实管理后台尚未提供「付款管理 / 预付款」菜单与页面（前端 finance 模块下无 prepay 视图），功能当前不可用。请前端补菜单 + 页面并对接本文接口清单；出纳「应付款支付」页需支持 payType=PREPAY 队列与付款。	2026-09-15	dev-v3

预付款功能：后端全链路已就绪，前端需补「预付款」菜单与页面（新增接口）

服务: hl-order-service-v3（hl-finance 模块） Issue: #7428（预付款域） 日期: 2026-09-15（后端已部署测试服） 影响范围: 新增「预付款」整域接口；前端需新增菜单 + 页面，并在「应付款支付」页支持预付款付款

---

⚠️ 一句话结论

预付款后端接口已全部做好并部署，但真实管理后台没有预付款菜单和页面（src/views/finance/ 下无 prepay 目录），功能当前在前端用不了。请前端新增「付款管理 / 预付款」菜单 + 页面，按本文接口清单对接。

---

一、背景与业务链路

预付款 = 先付给供应商一笔钱挂着，后续给该供应商付应付款时用这笔预付余额冲抵（少付现金）。

预付款申请(PENDING) → 提交(SUBMITTED) → 批准(APPROVED) → 出纳付款(PAID，记资金流水)
   → 钱挂到供应商名下 available_amount（可冲抵余额）
   → 后续付该供应商应付款(PAYMENT)时，用预付余额冲抵

• 预付款与应付款是两个独立单据类型（出纳付款 bizType 分别为 PREPAY / PAYMENT），不混表。
• 预付款付款后产生 available_amount（可冲抵金额），随冲抵递减。

二、变更清单（前端待办）

项	说明
新增菜单	「付款管理 / 预付款」（原型 pay-adv 页，页内子 Tab：预付款 / 冲抵记录）
预付款列表页	分页 + 状态/供应商筛选 + 单号/供应商名关键字
申请/编辑弹窗	新建 PENDING 草稿、编辑草稿（仅 PENDING）
审批操作	提交 / 批准（可录审批意见）/ 驳回（录驳回原因）
删除草稿	仅 PENDING，软删
详情	全字段只读
应付款支付页	出纳队列/付款需支持 payType=PREPAY（与既有 PAYMENT 并列）

三、接口清单（全部已就绪，base 前缀 /admin/finance）

操作	方法/路径	说明
分页	GET /admin/finance/prepays/page	状态/供应商筛选 + 关键字
申请	POST /admin/finance/prepays	落 PENDING 草稿
详情	GET /admin/finance/prepays/{id}	全字段
编辑	PUT /admin/finance/prepays/{id}	仅 PENDING
删除	DELETE /admin/finance/prepays/{id}	仅 PENDING，软删
提交	PUT /admin/finance/prepays/{id}/submit	PENDING → SUBMITTED
批准	PUT /admin/finance/prepays/{id}/approve	SUBMITTED → APPROVED，可录意见
驳回	PUT /admin/finance/prepays/{id}/reject	SUBMITTED → REJECTED，录原因
出纳队列	GET /admin/finance/cashier/queue?payType=PREPAY	待付款预付款单
出纳付款	POST /admin/finance/cashier/pay（bizType=PREPAY）	APPROVED → PAID，记流水

四、入参

4.1 申请预付款 POST /admin/finance/prepays

字段	类型	必填	说明
supplierId	long	✅	付款单位供应商ID
offsetSupplierId	long	否	冲抵单位供应商ID，默认=supplierId
amount	number	✅	预付金额（>0）
availableAmount	number	否	可冲抵金额，默认=预付金额；须 0 ≤ x ≤ 预付金额
payDate	string	✅	付款日期 yyyy-MM-dd
remark	string	否	备注

4.2 批准 PUT /{id}/approve：{ "remark": "审批意见" }（可空）

4.3 驳回 PUT /{id}/reject：{ "reason": "驳回原因" }

五、出参（列表行 / 详情共有字段）

字段	类型	说明
id	string	预付款ID（Long 序列化 string）
prepayNo	string	预付单号（YF- 前缀）
supplierId / supplierName	long/string	付款单位供应商
offsetSupplierId / offsetSupplierName	long/string	冲抵单位供应商
amount	number	预付金额
availableAmount	number	可冲抵金额（随冲抵递减）
payDate	string	付款日期
status	string	状态码（见六）
operatorName	string	经办人
createTime	string	创建时间

六、状态机（status 码值）

值	含义	可执行操作
PENDING	草稿	编辑 / 删除 / 提交
SUBMITTED	审批中	批准 / 驳回
APPROVED	已批准（待付款，入出纳队列）	出纳付款
REJECTED	已驳回	—（终态）
PAID	已付讫（出纳已打款，产生可冲抵余额）	后续被应付款冲抵

七、错误码

码	含义	触发
598610	付款金额与单据应付金额不一致	出纳付款 amount ≠ 审批预付金额 amount（#7713 金额锁死）
598609	收付账户与收付方式不匹配	出纳付款账户类型与方式不符（#7698）
PrepayErrorCode 段	状态非法/单据不存在/金额校验	如对非 PENDING 编辑、可冲抵金额超预付金额 等

八、示例

8.1 申请预付款

POST /admin/finance/prepays
Content-Type: application/json

{ "supplierId": 2095340000000000001, "amount": 5000, "payDate": "2026-09-15", "remark": "某酒店预付定金" }

→ { "code":200, "data":{ "id": "..." }, "success":true }（落 PENDING）

8.2 走完整审批链

PUT /admin/finance/prepays/{id}/submit     # PENDING → SUBMITTED
PUT /admin/finance/prepays/{id}/approve    # { "remark":"同意" }  SUBMITTED → APPROVED

8.3 出纳付款（应付款支付页，payType=PREPAY）

POST /admin/finance/cashier/pay
{ "bizType":"PREPAY", "bizId":<预付款ID>, "payAccountId":<出账账户ID>,
  "payMethod":"BANK", "amount":5000, "payDate":"2026-09-15" }

⚠️ amount 必须 = 审批预付金额（本例 5000），否则 598610（#7713 锁死）。成功 → PAID，记资金流水。

九、业务边界

• 预付款批准后进出纳队列（payType=PREPAY），由出纳真正打款；审批本身不动钱。
• 出纳打款后钱挂到 available_amount，付应付款时冲抵（冲抵能力属应付款域，本次不含）。
• 企微审批未接通，批准/驳回本期为手工置状态（同应付款/报销口径）。
• 预付款自身不关联订单/团，是纯供应商维度的预付。

十、影响评估 / 回滚

• 纯新增功能，不动既有接口契约，无破坏性。
• 前端未接前功能不可用，无存量影响；接入后即可用。

十一、注意事项

• Long 入参（supplierId/bizId/payAccountId）JSON 传 number；出参 Long 已序列化 string。
• 出纳「应付款支付」页务必加 payType=PREPAY 的队列查询与付款入口（与 PAYMENT 并列），否则预付款批了也没法打款。
• 付款金额只读展示审批预付金额（#7713 锁死口径）。

十二、关联 / 联系人

• Issue: #7428（预付款域后端）
• 相关: #7713（付款金额锁死 598610）、#7698（方式↔账户校验 598609）
• 负责人: 腰苏图（yst）