12 KiB
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 | 7521/7520 | 员工借款（付款管理/员工借款）：借款申请+审批（手工推进状态）+ 核销进度只读 + 报销冲抵选借款 | admin | yst | 新增接口 | deployed | not_required | verified | mmg | 2a2ec01df823c841f5a608a9ee6b6ffeb09ce133 | 2026-09-13 | 员工借款域后端已全量接通（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 纯只读。 | 2026-09-13 | 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）发生在出纳侧，见支付篇。
八、示例
典型·新建借款单
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（终态）
异常·借款人非法 / 状态非法
{ "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（腰苏图）