206 行
12 KiB
Markdown
206 行
12 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "7521/7520"
|
||
title: "员工借款（付款管理/员工借款）：借款申请+审批（手工推进状态）+ 核销进度只读 + 报销冲抵选借款"
|
||
consumer: "admin"
|
||
author: "yst"
|
||
change_type: "新增接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "not_required"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "2a2ec01df823c841f5a608a9ee6b6ffeb09ce133"
|
||
target_release: ""
|
||
verified_at: "2026-09-13"
|
||
status_note: "员工借款域后端已全量接通（Epic #7520 四 PR：#7543 CRUD+审批 / #7549 出纳放款 / #7557 还款核销 / #7566 报销冲抵）。本篇覆盖「付款管理/员工借款」菜单：借款申请+审批（submit/approve/reject 手工推进状态，approvalInstanceId 留空待后期统一接企微审批流）+ 核销进度只读 + 报销冲抵选借款。出纳放款与还款核销登记见配套《员工借款支付（出纳放款·核销）》篇。菜单 V20260913_001 已挂载（PR #7642）。 前端已交付(eb6812c2):新建 staff-loan API+payable/staff-loan 主域页(列表 statuses+keyword 筛选/新建编辑(员工选择器 staffId)/七态状态机操作/详情含 repayRecords),报销冲抵勾选接 offsettable+offsetLoanIds(offsetGuard 守卫编辑回填),snowflake 全串;staff-loan.spec 11 例,checkpoint 13 项全绿。⚠️前端该版含页内还款登记/红冲，本期归属已按原型修正为出纳侧（支付篇），前端需把还款登记从本页挪走。 核销归属修正已落地(2a2ec01d):还款登记/红冲从申请页挪出纳侧(支付页台账行内还款核销弹窗),申请页 repayRecords 纯只读。"
|
||
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《员工借款支付（出纳放款·核销）》。本页只**看**核销进度（已核销金额 / 借款余额 / 还款记录），不做还款登记。
|
||
|
||
> ⚠️ **审批本期为手工推进状态**：`approve`/`reject` 直接改状态推进，**暂不接企业微信审批流**；详情出参 `approvalInstanceId`（企微审批实例号）本期**留空**，为后期统一接入审批流预留。
|
||
|
||
## 二、菜单↔功能↔接口 对应表
|
||
|
||
| 菜单 | 功能 | 接口 |
|
||
|---|---|---|
|
||
| 付款管理/员工借款 | 借款单列表/新建/详情/编辑/删除 | `GET /page`、`POST /`、`GET /{id}`、`PUT /{id}`、`DELETE /{id}` |
|
||
| 付款管理/员工借款 | **审批**：提交 / 批准 / 驳回（手工推进状态） | `PUT /{id}/submit`、`PUT /{id}/approve`、`PUT /{id}/reject` |
|
||
| 付款管理/员工借款 | 核销进度查看（还款记录只读） | `GET /{id}`（详情含 repayRecords）、`GET /{id}/repays` |
|
||
| 付款管理/员工借款 | 报销冲抵——查某员工可冲抵借款 | `GET /offsettable?staffId=` |
|
||
|
||
> 菜单 path（已挂载）：员工借款 = `/finance/payable/staff-loan`。
|
||
> ❌ 本页**不**调 `POST /{id}/repays` / `DELETE /repays/{repayId}`（还款登记/红冲在出纳侧，见支付篇）。
|
||
|
||
## 三、接口清单（基础路径 `/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（终态） |
|
||
| GET | `/{id}/repays` | 还款记录列表（**只读**，核销进度） | - |
|
||
|
||
> `POST /{id}/repays`、`DELETE /repays/{repayId}` 为出纳侧还款登记/红冲，**见支付篇**，本页不用。
|
||
|
||
## 四、入参
|
||
|
||
### 4.1 分页 `GET /page`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| status | String | 否 | 单据状态单值 |
|
||
| statuses | List\<String\> | 否 | 单据状态多值（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 | ✅ | 驳回原因 |
|
||
|
||
## 五、出参
|
||
|
||
### 5.1 Row（分页）
|
||
|
||
id、loanNo（JK- 前缀单号）、staffId、staffName、amount、repaidAmt（**已核销**，只读）、balanceAmt（**借款余额**，只读）、purpose（**借款事由**，PR #7655 起 Row 也返回）、loanDate、dueDate、status、operatorId、operatorName（经办人=登录人留痕，只读）、createTime
|
||
|
||
### 5.2 Detail（详情）= Row 全字段 + 以下
|
||
|
||
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`。
|
||
- 本页负责 `PENDING→SUBMITTED→APPROVED/REJECTED` 段（申请+审批，手工推进）。
|
||
- `APPROVED→PAID` 由出纳放款触发、`PAID→SETTLING→SETTLED` 由还款核销触发（均在支付篇）。
|
||
|
||
## 七、错误码（HTTP 恒 200，判 code，按 message 原样提示）
|
||
|
||
| code | message | 触发 |
|
||
|---|---|---|
|
||
| 599101 | 借款单不存在 | id 无效 |
|
||
| 599102 | 借款单状态非法，当前状态不允许此操作 | 状态前置不满足 |
|
||
| 599103 | 借款金额无效（须大于0） | amount≤0 |
|
||
| 599104 | 借款人非法（不存在或未登记真名） | staffId 查不到/无企微真名 |
|
||
| 599105 | 借款单号生成冲突，请重试 | 单号并发撞号（重试即可） |
|
||
| 599107 | 借款可冲余额不足，请重新勾选 | 报销冲抵勾选超额 |
|
||
| 599112 | 勾选冲抵借款时申请人必填 | 报销 offsetLoanIds 非空但 applicantId 空 |
|
||
| 599113 | 勾选借款与报销申请人不一致 | 报销勾选人≠借款人 |
|
||
|
||
> 还款登记相关错误码（599106/599108/599109/599110/599111）发生在出纳侧，见支付篇。
|
||
|
||
## 八、示例
|
||
|
||
### 典型·新建借款单
|
||
|
||
```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"
|
||
```
|
||
|
||
### 典型·审批（手工推进状态，不接企微）
|
||
|
||
```
|
||
PUT /admin/finance/staff-loans/{id}/submit → PENDING→SUBMITTED
|
||
PUT /admin/finance/staff-loans/{id}/approve → SUBMITTED→APPROVED（批准后进出纳待放款队列）
|
||
PUT /admin/finance/staff-loans/{id}/reject body {"reason":"事由不充分"} → SUBMITTED→REJECTED（终态）
|
||
```
|
||
|
||
### 异常·借款人非法 / 状态非法
|
||
|
||
```json
|
||
{ "staffId":"999...", ... } → { "code":599104, "message":"借款人非法（不存在或未登记真名）" }
|
||
对 PENDING 单 approve → { "code":599102, "message":"借款单状态非法，当前状态不允许此操作" }
|
||
```
|
||
|
||
## 九、业务边界
|
||
|
||
- staffName / operatorName 为后端反查企微名落的快照/展示值，**前端不要传**，只读。
|
||
- `operatorId/operatorName` = 当前登录人（created_by）留痕，只读透出。
|
||
- `approvalInstanceId` 本期恒 null（审批手工推进），后期接企微审批流后由后端回写，前端只需预留展示位。
|
||
- 已核销金额 repaidAmt / 借款余额 balanceAmt 不存列，由还款记录现算，**只读**。
|
||
- 报销冲销（EXPENSE_OFFSET）还款行由报销域产生、不记资金流水（fundAccountId 恒 null），只读展示。
|
||
|
||
## 十、报销冲抵（跨域勾稽）
|
||
|
||
报销单 create/update 入参 `offsetLoanIds`（List\<Long\>）勾选冲抵本申请人名下借款：非空时 applicantId 必填（599112）、勾选人须=借款人（599113）、按勾选顺序 use=min（报销剩余额度，借款 balanceAmt）。出参 `offsetLoanAmt`（冲销额）+ `payableAmt = amount − offsetLoanAmt`（出纳按应付差额付款）。本页用 `GET /offsettable?staffId=` 供报销勾选借款。详见《费用报销》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）
|
||
|
||
## 十三、关联 / 联系人
|
||
|
||
- 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（腰苏图）
|