hl-api-changelog/changelogs-v2/2026-09/13_staffloan_员工借款申请与核销-新增接口-管理后台.md

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	required					员工借款域后端已全量接通（Epic #7520 四 PR：#7543 CRUD+审批 / #7549 出纳放款 / #7557 还款核销 / #7566 报销冲抵）。本篇覆盖「付款管理/员工借款」菜单的申请+审批+核销+冲抵（/admin/finance/staff-loans 全域）；出纳放款见配套《员工借款支付》篇。菜单 V20260913_001 已挂载（PR #7642）。	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《员工借款支付（出纳放款）》。

二、菜单↔功能↔接口 对应表

菜单	功能	接口
付款管理/员工借款	借款单列表/新建/详情/编辑/删除	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<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	✅	驳回原因

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	勾选借款与报销申请人不一致	报销勾选人≠借款人

八、示例

典型·新建借款单

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"

典型·登记现金还款

POST /admin/finance/staff-loans/{id}/repays
{ "repayWay":"CASH", "amount":2000.00, "fundAccountId":"2095340438490583041" }
→ 记资金流水 IN + 重算状态（SUM<amount → SETTLING；SUM≥amount → SETTLED）

异常·借款人非法 / 还款超额

{ "staffId":"999...", ... }              → { "code":599104, "message":"借款人非法（不存在或未登记真名）" }
还款 amount 超 balanceAmt               → { "code":599106, "message":"还款金额超过借款剩余余额" }
手工还款传 EXPENSE_OFFSET               → { "code":599110, "message":"还款方式非法（仅支持现金/转账）" }

九、业务边界

• staffName / operatorName 为后端反查企微名落的快照/展示值，前端不要传，只读。
• operatorId/operatorName = 当前登录人（created_by）留痕，只读透出。
• 报销冲销（EXPENSE_OFFSET）还款行由报销域产生、不记资金流水（fundAccountId 恒 null），不可手工红冲（599111）。
• 还款红冲走 DELETE /repays/{repayId}：反向 OUT 流水 + 软删 + 状态回退，仅现金/转账行可冲。
• 已还金额不存列，repaidAmt/balanceAmt 由还款记录现算。

十、报销冲抵（跨域勾稽）

报销单 create/update 入参 offsetLoanIds（List<Long>）勾选冲抵本申请人名下借款：非空时 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（腰苏图）