feat(finance): 预付款功能 changelog（#7428）

后端全链路就绪，前端需补「付款管理/预付款」菜单+页面；
应付款支付页支持 payType=PREPAY。

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

@@ -0,0 +1,175 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7428"
+title: "预付款功能：后端全链路已就绪，前端需补「预付款」菜单与页面"
+consumer: "admin"
+author: "yst(GIT)"
+change_type: "新增接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-15"
+status_note: "预付款域（#7428）后端全链路接口已就绪并部署：申请/编辑/删除/提交/批准/驳回/分页/详情 + 出纳付款(cashier/pay bizType=PREPAY) + 冲抵余额(available_amount)。但真实管理后台尚未提供「付款管理 / 预付款」菜单与页面（前端 finance 模块下无 prepay 视图），功能当前不可用。请前端补菜单 + 页面并对接本文接口清单；出纳「应付款支付」页需支持 payType=PREPAY 队列与付款。"
+updated_at: "2026-09-15"
+base: "dev-v3"
+---
+
+# 预付款功能：后端全链路已就绪，前端需补「预付款」菜单与页面（新增接口）
+
+> **服务**: hl-order-service-v3（hl-finance 模块）
+> **Issue**: [#7428](https://git.1814.love:8443/wx/HL/issues/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 申请预付款
+
+```http
+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 走完整审批链
+
+```http
+PUT /admin/finance/prepays/{id}/submit     # PENDING → SUBMITTED
+PUT /admin/finance/prepays/{id}/approve    # { "remark":"同意" }  SUBMITTED → APPROVED
+```
+
+### 8.3 出纳付款（应付款支付页，payType=PREPAY）
+
+```http
+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](https://git.1814.love:8443/wx/HL/issues/7428)（预付款域后端）
+- 相关: [#7713](https://git.1814.love:8443/wx/HL/issues/7713)（付款金额锁死 598610）、[#7698](https://git.1814.love:8443/wx/HL/issues/7698)（方式↔账户校验 598609）
+- 负责人: 腰苏图（yst）