wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
文件
10b46812d23a51304c00ee1537254b4a07c7265c
hl-api-changelog/changelogs-v2/2026-09/15_7428_预付款功能后端就绪前端补菜单页面-新增接口-管理后台.md
T
Mimingguang 71c31c475d
changelog-filename-gate / validate (push) Failing after 2s
详情
docs(changelog): #7428 预付款菜单路径纠错回写(advance 对齐 sys_menu)
2026-09-15 17:06:32 +08:00

9.2 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 7428 预付款功能：后端全链路已就绪，前端需补「预付款」菜单与页面 admin yst(GIT) 新增接口 deployed verified verified mmg 30bb7ebb53b90d5290a9d6af3a81e516ad35f3ae 2026-09-15 预付款域（#7428）后端全链路接口已就绪并部署：申请/编辑/删除/提交/批准/驳回/分页/详情 + 出纳付款(cashier/pay bizType=PREPAY) + 冲抵余额(available_amount)。但真实管理后台尚未提供「付款管理 / 预付款」菜单与页面（前端 finance 模块下无 prepay 视图），功能当前不可用。请前端补菜单 + 页面并对接本文接口清单；出纳「应付款支付」页需支持 payType=PREPAY 队列与付款。 前端已交付(e268e348):api/finance/prepay.js 8 端点+五态字典;新增「付款管理/预付款」管理页 finance/payable/prepay(状态/供应商弹窗筛选/关键字,申请/编辑弹窗对齐原型 pay-adv,保存并提交审核两段,批准录意见/驳回录原因,状态门显隐,详情抽屉;冲抵记录 Tab 无接口本期不做);出纳侧 CashierQueuePage payType 加 PREPAY(外部单位线含手续费,继承 #7713 金额锁死与 #7695 账户过滤)+薄壳 finance/pay/prepay。菜单行(付款管理/预付款 component=finance/payable/prepay、支付管理/预付款支付 component=finance/pay/prepay)需后端 yst 在 sys_menu 配置,动态路由落位即解析。spec 22/22,checkpoint 13 项全绿。 菜单路径纠错(30bb7ebb):后端 sys_menu 实配 component=finance/payable/advance(与原预估 prepay 不符),前端 git mv finance/payable/prepay→advance、finance/pay/prepay→advance 对齐,storage key 改 finance-payable-advance;api/finance/prepay.js 不动(API 契约 /admin/finance/prepays/* 不变)。「支付管理/预付款支付」菜单行 sys_menu 尚未配置,待后端补配。spec 22/22 复跑全绿。 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）
在新工单中引用 查看 Git Blame 复制永久链接