diff --git a/changelogs-v2/2026-09/15_7428_预付款功能后端就绪前端补菜单页面-新增接口-管理后台.md b/changelogs-v2/2026-09/15_7428_预付款功能后端就绪前端补菜单页面-新增接口-管理后台.md new file mode 100644 index 00000000..66a5fe9e --- /dev/null +++ b/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)