diff --git a/changelogs-v2/2026-09/13_staffloan_员工借款支付出纳放款-修改接口-管理后台.md b/changelogs-v2/2026-09/13_staffloan_员工借款支付出纳放款-修改接口-管理后台.md new file mode 100644 index 00000000..c0a06845 --- /dev/null +++ b/changelogs-v2/2026-09/13_staffloan_员工借款支付出纳放款-修改接口-管理后台.md @@ -0,0 +1,89 @@ +--- +schema: "hl-changelog/v2" +ticket: "7521/7520" +title: "员工借款支付(支付管理/员工借款支付):借款审批通过后的出纳放款链路对接说明——队列/登记放款/已放款台账按 STAFF_LOAN 路由" +consumer: "admin" +author: "yst" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "not_required" +frontend_status: "not_required" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "📘 对接说明(出纳域接口本次无变更):员工借款 APPROVED 后进出纳待放款队列,复用统一出纳接口 /admin/finance/cashier/*,按 payType/bizType=STAFF_LOAN 路由。本文给前端「支付管理/员工借款支付」页的对接口径。菜单 V20260913_001 已挂载(PR #7642)。" +updated_at: "2026-09-13" +base: "dev-v3" +--- + +# 员工借款支付(支付管理/员工借款支付)—— 出纳放款链路对接说明 + +> **服务**: hl-order-service-v3(hl-finance 财务模块·出纳域) +> **端**: 管理后台 +> **类型**: 📘 对接说明(出纳域接口本次**无变更**,仅说明员工借款支付页怎么接) +> **日期**: 2026-09-13 +> **关联**: Epic #7520 / PR #7549;菜单挂载 PR #7642(均已合并 dev-v3) + +## 一、接口背景 + +员工借款单 `APPROVED`(审批通过)后进入**出纳待放款队列**,由出纳登记线下放款、回写借款单 PAID。员工借款支付**不单独建接口**,复用财务统一出纳接口 `/admin/finance/cashier/*`,按 `payType / bizType = STAFF_LOAN` 路由出员工借款这一类的待放款/已放款数据。 + +## 二、菜单↔功能↔接口 对应表 + +| 菜单 | 功能 | 接口 | +|---|---|---| +| 支付管理/员工借款支付 | 待放款队列 | `GET /admin/finance/cashier/queue?payType=STAFF_LOAN` | +| 支付管理/员工借款支付 | 登记放款 | `POST /admin/finance/cashier/pay`(bizType=STAFF_LOAN) | +| 支付管理/员工借款支付 | 已放款台账 | `GET /admin/finance/cashier/payments/page?bizType=STAFF_LOAN` | + +> 菜单 path(已挂载):员工借款支付 = `/finance/pay/staff-loan`。 + +## 三、放款链路(借款视角) + +``` +借款单 approve(APPROVED) → 出纳队列出现该待放款单 → 出纳登记放款(pay, bizType=STAFF_LOAN) + → 记资金流水 OUT + 回写借款单 PAID(落 fund_account_id/paid_at)+ 重算账户结存 + → 已放款台账可查 / 借款详情 paidAt+fundAccountId 回显 +``` + +## 四、涉及接口(均为出纳域现有接口,按 STAFF_LOAN 过滤) + +### ① 出纳待放款队列 — `GET /admin/finance/cashier/queue` +- 入参:`payType=STAFF_LOAN`(员工借款)+ page/pageSize +- 队列源:fin_staff_loan 状态 APPROVED 的借款单 +- **员工借款支付页"待放款"列表 = 本接口 payType=STAFF_LOAN** + +### ② 登记放款 — `POST /admin/finance/cashier/pay` +- 入参:`bizType=STAFF_LOAN` + `bizId`(借款单ID) + 出账账户 fundAccountId + 金额 + 手续费 + 付款日期 + 凭证 voucherUrl 等 +- 动作:记资金流水 OUT + 回写借款单 APPROVED→PAID(落 fund_account_id/paid_at)+ 重算账户结存 +- 并发/幂等:放款前 selectForUpdate 锁借款行 + 锁内校验存在且 APPROVED,已 PAID 不可重复放款(598602) + +### ③ 已放款流水台账 — `GET /admin/finance/cashier/payments/page` +- 入参:`bizType=STAFF_LOAN` + page/pageSize +- **员工借款支付页"已放款"列表 = 本接口 bizType=STAFF_LOAN** + +## 五、字段对接要点 + +| 前端展示 | 来源 | +|---|---| +| 待放款列表 | `cashier/queue?payType=STAFF_LOAN` | +| 已放款列表 | `cashier/payments/page?bizType=STAFF_LOAN` | +| 登记放款动作 | `cashier/pay`(bizType=STAFF_LOAN) | +| 单张借款的放款结果(放款时间/出账账户) | 借款详情 `GET /admin/finance/staff-loans/{id}` 的 `paidAt` / `fundAccountId`(见员工借款篇) | + +## 六、注意事项 + +1. 员工借款支付复用统一出纳队列/付款/台账接口,**不要**为员工借款单独写支付接口;靠 `payType/bizType=STAFF_LOAN` 区分业务类型。 +2. 放款金额以借款单 `amount`(全额)为准——员工借款无"冲抵差额"概念(报销才有 payableAmt),放款即全额。 +3. 放款凭证(出纳回单)通过 `cashier/pay` 的 voucherUrl 上传;与借款"申请凭证"voucherUrl 是两个不同字段。 +4. 出账账户下拉用资金账户接口(`GET /admin/finance/fund-accounts/options`,取启用账户)。 +5. 错误码:598607(bizType 非法文案含 STAFF_LOAN)/ 598602(借款单已放款不可重复)等出纳域既有码,按 message 原样提示。 + +## 七、关联 / 联系人 + +- 员工借款(申请+核销)changelog:`13_staffloan_员工借款申请与核销-新增接口-管理后台.md` +- Epic:https://git.1814.love:8443/wx/HL/issues/7520 | PR:https://git.1814.love:8443/wx/HL/pulls/7549 +- 菜单挂载:https://git.1814.love:8443/wx/HL/pulls/7642(Issue #7641) +- 出纳域(统一收付):hl-finance `CashierController`(queue/pay/payments/confirm-in) +- 负责人:yst(腰苏图) diff --git a/changelogs-v2/2026-09/13_staffloan_员工借款申请与核销-新增接口-管理后台.md b/changelogs-v2/2026-09/13_staffloan_员工借款申请与核销-新增接口-管理后台.md new file mode 100644 index 00000000..36ce3c19 --- /dev/null +++ b/changelogs-v2/2026-09/13_staffloan_员工借款申请与核销-新增接口-管理后台.md @@ -0,0 +1,215 @@ +--- +schema: "hl-changelog/v2" +ticket: "7521/7520" +title: "员工借款(付款管理/员工借款):借款申请+审批+还款核销+报销冲抵 全域接口对接说明" +consumer: "admin" +author: "yst" +change_type: "新增接口" +backend_status: "deployed" +gateway_status: "not_required" +frontend_status: "required" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "员工借款域后端已全量接通(Epic #7520 四 PR:#7543 CRUD+审批 / #7549 出纳放款 / #7557 还款核销 / #7566 报销冲抵)。本篇覆盖「付款管理/员工借款」菜单的申请+审批+核销+冲抵(/admin/finance/staff-loans 全域);出纳放款见配套《员工借款支付》篇。菜单 V20260913_001 已挂载(PR #7642)。" +updated_at: "2026-09-13" +base: "dev-v3" +--- + +# 员工借款(付款管理/员工借款)—— 申请 + 审批 + 还款核销 + 报销冲抵 + +> **服务**: hl-order-service-v3(hl-finance 财务模块·员工借款域) +> **端**: 管理后台 +> **类型**: 🆕 新增接口(员工借款域首次对接说明) +> **日期**: 2026-09-13 +> **关联**: Epic #7520;PR #7543 / #7549 / #7557 / #7566;菜单挂载 PR #7642(均已合并 dev-v3) + +## 一、接口背景 + +员工借款主链:**申请 → 提交 → 审批 → 出纳放款 → 还款核销**。本域在管理后台对应原型菜单「付款管理 / 员工借款」,承载借款申请、审批、还款核销(现金/转账)、报销冲抵选借款四块功能。出纳放款(登记线下付款流水)在「支付管理 / 员工借款支付」,见配套 changelog《员工借款支付(出纳放款)》。 + +## 二、菜单↔功能↔接口 对应表 + +| 菜单 | 功能 | 接口 | +|---|---|---| +| 付款管理/员工借款 | 借款单列表/新建/详情/编辑/删除 | `GET /page`、`POST /`、`GET /{id}`、`PUT /{id}`、`DELETE /{id}` | +| 付款管理/员工借款 | 提交审批 / 批准 / 驳回 | `PUT /{id}/submit`、`PUT /{id}/approve`、`PUT /{id}/reject` | +| 付款管理/员工借款 | 还款核销(现金/转账)登记/列表/红冲 | `POST /{id}/repays`、`GET /{id}/repays`、`DELETE /repays/{repayId}` | +| 付款管理/员工借款 | 报销冲抵——查某员工可冲抵借款 | `GET /offsettable?staffId=` | + +> 菜单 path(已挂载):员工借款 = `/finance/payable/staff-loan`。 + +## 三、接口清单(基础路径 `/admin/finance/staff-loans`) + +| 方法 | 路径 | 说明 | 状态前置 | +|---|---|---|---| +| GET | `/page` | 借款单分页 | - | +| GET | `/offsettable?staffId=` | 可冲抵借款(PAID/SETTLING 且余额>0) | - | +| POST | `/` | 创建借款单(PENDING 草稿)→ `{id}` | - | +| GET | `/{id}` | 借款单详情(含 repayRecords) | - | +| PUT | `/{id}` | 编辑 | 仅 PENDING | +| DELETE | `/{id}` | 软删 | 仅 PENDING | +| PUT | `/{id}/submit` | 提交审批 | PENDING→SUBMITTED | +| PUT | `/{id}/approve` | 批准 | SUBMITTED→APPROVED | +| PUT | `/{id}/reject` | 驳回(body `{reason}` 必填≤512) | SUBMITTED→REJECTED(终态) | +| POST | `/{id}/repays` | 登记还款(现金/转账) | PAID/SETTLING | +| GET | `/{id}/repays` | 还款记录列表 | - | +| DELETE | `/repays/{repayId}` | 还款红冲(反向流水+状态回退) | 非 EXPENSE_OFFSET 行 | + +## 四、入参 + +### 4.1 分页 `GET /page` + +| 字段 | 类型 | 必填 | 说明 | +|---|---|---|---| +| status | String | 否 | 单据状态单值 | +| statuses | List\ | 否 | 单据状态多值(IN 查询)。**非空优先于 status;均空=全部** | +| staffId | Long(String) | 否 | 借款人 adminId(空=不限) | +| keyword | String | 否 | 关键字(借款单号 / 借款人姓名模糊) | +| page / pageSize | Integer | 否 | 分页 | + +### 4.2 创建 `POST /` / 编辑 `PUT /{id}`(同构) + +| 字段 | 类型 | 必填 | 说明 | +|---|---|---|---| +| staffId | Long(String) | ✅ | 借款人 adminId(员工选择器选,关联接口①)。后端反查企微名落 staffName 快照,查不到/无真名 → 599104 | +| amount | BigDecimal | ✅ | 借款金额 >0(否则 599103) | +| purpose | String≤200 | ✅ | 借款事由 | +| loanDate | Date | 否 | 借款日期 | +| dueDate | Date | 否 | 应还日期 | +| voucherUrl | String≤500 | 否 | 申请凭证影像 URL | + +### 4.3 驳回 `PUT /{id}/reject` + +| 字段 | 类型 | 必填 | 说明 | +|---|---|---|---| +| reason | String≤512 | ✅ | 驳回原因 | + +### 4.4 登记还款 `POST /{id}/repays` + +| 字段 | 类型 | 必填 | 说明 | +|---|---|---|---| +| repayWay | String | ✅ | 还款方式:`CASH` 现金 / `TRANSFER` 转账(**EXPENSE_OFFSET 不收** → 599110,报销冲销由报销域自动产生) | +| amount | BigDecimal | ✅ | 还款金额 >0,超剩余余额 → 599106 | +| fundAccountId | Long(String) | ✅ | 入账资金账户(关联接口③) | +| voucherUrl | String | 否 | 还款凭证影像 URL | +| repaidAt | DateTime | 否 | 还款时间(默认当前时间) | + +## 五、出参 + +### 5.1 Row(分页) + +id、loanNo(JK- 前缀单号)、staffId、staffName、amount、repaidAmt(已还)、balanceAmt(剩余余额)、loanDate、dueDate、status、operatorId、operatorName(经办人=登录人留痕,只读)、createTime + +### 5.2 Detail(详情)= Row 全字段 + 以下 + +purpose、voucherUrl、fundAccountId、paidAt(放款时间)、approvalInstanceId(本期留空)、rejectReason、repayRecords[] + +### 5.3 repayRecords[](还款记录) + +| 字段 | 类型 | 说明 | +|---|---|---| +| id | String | 还款记录 ID | +| repayNo | String | 还款单号(HK- 前缀) | +| amount | BigDecimal | 还款金额 | +| repayWay | String | 还款方式码 | +| repayWayName | String | 还款方式中文 | +| fundAccountId | String | 入账账户(EXPENSE_OFFSET 恒 null,不记资金流水) | +| voucherUrl | String | 还款凭证 | +| repaidAt | DateTime | 还款时间 | + +### 5.4 可冲抵借款 `GET /offsettable` 出参项 + +id、loanNo、amount、repaidAmt、balanceAmt(**可冲上限**)、loanDate、purpose + +## 六、枚举 / 数据字典 + +| 字段 | 取值 | +|---|---| +| status / statuses | PENDING 草稿 / SUBMITTED 审批中 / APPROVED 已批准 / REJECTED 已驳回(终态)/ PAID 已放款 / SETTLING 核销中 / SETTLED 已核销 | +| repayWay | CASH 现金 / TRANSFER 转账 / EXPENSE_OFFSET 报销冲销(系统产生,手工还款不收) | + +**状态机**:`PENDING → SUBMITTED → APPROVED / REJECTED(终态) →(出纳放款) PAID →(有还款未清) SETTLING →(SUM≥amount) SETTLED`。 + +## 七、错误码(HTTP 恒 200,判 code,按 message 原样提示) + +| code | message | 触发 | +|---|---|---| +| 599101 | 借款单不存在 | id 无效 | +| 599102 | 借款单状态非法,当前状态不允许此操作 | 状态前置不满足 | +| 599103 | 借款金额无效(须大于0) | amount≤0 | +| 599104 | 借款人非法(不存在或未登记真名) | staffId 查不到/无企微真名 | +| 599105 | 借款单号生成冲突,请重试 | 单号并发撞号(重试即可) | +| 599106 | 还款金额超过借款剩余余额 | 还款 amount>balanceAmt | +| 599107 | 借款可冲余额不足,请重新勾选 | 报销冲抵勾选超额 | +| 599108 | 还款单号生成冲突,请重试 | 还款单号撞号 | +| 599109 | 还款记录不存在或已撤销 | repayId 无效 | +| 599110 | 还款方式非法(仅支持现金/转账) | 手工还款传 EXPENSE_OFFSET | +| 599111 | 报销冲销还款不可手工撤销 | 红冲 EXPENSE_OFFSET 行 | +| 599112 | 勾选冲抵借款时申请人必填 | 报销 offsetLoanIds 非空但 applicantId 空 | +| 599113 | 勾选借款与报销申请人不一致 | 报销勾选人≠借款人 | + +## 八、示例 + +### 典型·新建借款单 + +```json +POST /admin/finance/staff-loans +{ "staffId":"2083457702519873537", "amount":5000.00, "purpose":"出差备用金", + "loanDate":"2026-09-13", "dueDate":"2026-10-13" } +→ 200 { "code":200, "data":{ "id":"..." } } +详情出参含:loanNo="JK-20260913-0001"、staffName="金卫"、status="PENDING" +``` + +### 典型·登记现金还款 + +```json +POST /admin/finance/staff-loans/{id}/repays +{ "repayWay":"CASH", "amount":2000.00, "fundAccountId":"2095340438490583041" } +→ 记资金流水 IN + 重算状态(SUM)勾选冲抵本申请人名下借款:非空时 applicantId 必填(599112)、勾选人须=借款人(599113)、按勾选顺序 use=min(报销剩余额度,借款 balanceAmt)。出参 `offsetLoanAmt`(冲销额)+ `payableAmt = amount − offsetLoanAmt`(出纳按应付差额付款)。详见《费用报销》changelog。 + +## 十一、影响评估 / 回滚 + +- 新增域接口,无破坏性。前端按本篇对接「付款管理/员工借款」页。 +- 回滚:菜单下线(sys_menu)+ 接口不下线即可;表 fin_staff_loan / fin_staff_loan_repay 保留无影响。 + +## 十二、关联接口(前端对接数据源,均现成) + +**① 借款人下拉(员工选择器)** — `GET /admin/user/employee-options`(🆕 不限角色,PR #7627 / changelog `13_7625`) +- 入参:deptId / keyword / page / pageSize;出参:adminId、username、enterpriseWechatName、deptNames +- 选中取 `adminId` 传 `staffId` + +**② 报销单(冲抵勾稽)** — `GET/POST /admin/finance/expenses`(见《费用报销》changelog,offsetLoanIds/offsetLoanAmt/payableAmt) + +**③ 资金账户下拉(还款入账账户)** — `GET /admin/finance/fund-accounts/options` +- 出参启用资金账户,选中取 fundAccountId 传还款 `fundAccountId` + +## 十三、关联 / 联系人 + +- Epic:https://git.1814.love:8443/wx/HL/issues/7520 +- PR:https://git.1814.love:8443/wx/HL/pulls/7543 | /7549 | /7557 | /7566 +- 菜单挂载:https://git.1814.love:8443/wx/HL/pulls/7642(Issue #7641) +- 配套:《员工借款支付(出纳放款)》;员工选择器 `13_7625_员工选择器接口-新增接口-管理后台.md` +- 负责人:yst(腰苏图)