---
schema: "hl-changelog/v2"
ticket: "7472/7486/7502"
title: "费用报销：列表多状态筛选+详情付款记录、表单补申请人/收款账号/申请凭证、列表详情透出经办人"
consumer: "admin"
author: "yst"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "not_required"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "e5ca470ae4ef69cb574b2b5d3c8a2ab4666b8f50"
target_release: ""
verified_at: "2026-09-13"
status_note: "费用报销三件套：①page 加 statuses 多状态筛选 + detail 聚合 payRecords 付款记录 ②create/update 入参加 applicantId/payeeAccount/voucherUrl（出参透出 applicantName） ③page/detail 出参加 operatorId/operatorName 经办人。错误码 598705 文案放宽。出参只增不删向后兼容，入参新增均选填。 前端已交付(e5ca470a):状态筛选 statuses 多选非空优先,详情补申请人/经办人/收款账号/申请凭证+PAID 付款记录块,表单加申请人(员工选择器)/收款账号/申请凭证,部门切组织树字符串透传,经办人只读透出。"
updated_at: "2026-09-13"
base: "dev-v3"
---

# 费用报销 —— 多状态筛选 + 付款记录 + 申请人/经办人 + 表单补列

> **服务**: hl-order-service-v3（hl-finance 财务模块）
> **端**: 管理后台
> **类型**: 修改接口（出参只增不删向后兼容，入参新增均选填，非破坏）
> **日期**: 2026-09-13
> **关联**: Issue #7472 / #7486 / #7502；PR #7479 / #7496 / #7505（已合并 dev-v3）

## 一、接口背景

费用报销主链：申请 → 提交 → 审批 → 出纳付款。本批三件增强列表/详情的查询与展示能力，并补齐表单字段（申请人、收款账号、申请凭证）。报销付款链路见配套 changelog《费用支付（出纳）对接说明》。

## 二、变更清单

1. **列表多状态筛选**：`GET /page` 入参新增 `statuses`（多状态数组）。
2. **详情聚合付款记录**：`GET /{id}` 出参新增 `payRecords`（出纳付款流水，含付款凭证）。
3. **表单补列**：create/update 入参新增 `applicantId / payeeAccount / voucherUrl`；出参透出 `applicantId / applicantName / payeeAccount / voucherUrl`。
4. **透出经办人**：page Row / detail 出参新增 `operatorId / operatorName`。
5. **错误码 598705 文案放宽**：「部门或公司主体非法」→「部门/公司主体/申请人非法」（码值不变）。

## 三、接口详情（路径不变）

- 分页 `GET /admin/finance/expenses/page`
- 创建 `POST /admin/finance/expenses`
- 详情 `GET /admin/finance/expenses/{id}`
- 编辑 `PUT /admin/finance/expenses/{id}`（仅 PENDING）
- 删除 `DELETE /admin/finance/expenses/{id}`（仅 PENDING）
- 提交 `PUT /admin/finance/expenses/{id}/submit` ｜ 审批 `PUT /admin/finance/expenses/{id}/approve` ｜ 驳回 `PUT /admin/finance/expenses/{id}/reject`

## 四、入参

### 4.1 分页 `GET /page`

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| status | String | 否 | 单据状态单值 |
| **statuses** | List\<String\> | 否🆕 | 单据状态多值（IN 查询，如 ["APPROVED","PAID"]）。**非空优先于 status；与 status 均空=全部** |
| departmentId | Long(String) | 否 | 部门 ID（空=不限） |
| company | String | 否 | 公司主体名（空=不限） |
| keyword | String | 否 | 关键字（报销单号 / 公司主体名模糊） |
| page / pageSize | Integer | 否 | 分页 |

### 4.2 创建 / 编辑（PUT 同构）

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| expenseCategory | String | ✅ | 费用分类末级名称（fin_expense_category level=2 正常项） |
| departmentId | Long(String) | ✅ | 部门 ID（组织树选，关联接口②） |
| company | String | ✅ | 公司主体名（travel_agency 启用项，关联接口④，**传 agencyName 名字**） |
| amount | BigDecimal | ✅ | 报销金额 >0 |
| reason | String | ✅ | 报销事由 |
| **applicantId** | Long(String) | 否🆕 | 申请人 adminId（员工选择器选，关联接口③）。传则后端反查企微名落 applicantName 快照；不传存空（过渡期选填，前端全量跟上后收紧必填） |
| **payeeAccount** | String≤128 | 否🆕 | 收款账号（手填，本期明文） |
| **voucherUrl** | String≤512 | 否🆕 | **申请**凭证影像 URL（≠ 出纳付款凭证 payRecords.voucherUrl，两者不同字段） |
| offsetLoanIds | List\<Long(String)\> | 否 | 勾选冲抵的借款单 ID 列表（冲抵借款勾连，见 PR #7566；非空时 applicantId 必填否则 599112） |

## 五、出参

### 5.1 Row（分页）

id、expenseNo(FY-单号)、expenseCategory、departmentId、departmentName、company、amount、payableAmt(=amount−offsetLoanAmt)、reason、**applicantId🆕**、**applicantName🆕**、**payeeAccount🆕**、**voucherUrl🆕**、status、**operatorId🆕**、**operatorName🆕**、createTime

### 5.2 Detail（详情）= Row 全字段 + 以下

offsetLoanAmt、fundAccountId、approvalInstanceId、rejectReason、paidAt，及 **payRecords🆕**（见下）

### 5.3 payRecords🆕（付款记录，仅 PAID 有值，按付款时间升序）

| 字段 | 类型 | 说明 |
|---|---|---|
| flowNo | String | 资金流水号（LS- 前缀） |
| fundAccountName | String | 出账账户名（fin_fund_account 反查回填） |
| amount | BigDecimal | 实际打款金额 |
| fee | BigDecimal | 手续费 |
| payDate | DateTime | 付款时间 |
| voucherUrl | String | **出纳付款回单/凭证**影像 URL（≠ 申请凭证） |

> ⚠️ payRecords 每项**只有 voucherUrl，没有 voucherNo**（资金流水表无凭证号列）。

## 六、枚举 / 数据字典

| 字段 | 取值 |
|---|---|
| status / statuses | PENDING 草稿 / SUBMITTED 审批中 / APPROVED 已批准 / REJECTED 已驳回 / PAID 已付讫 |
| expenseCategory | 费用分类末级（fin_expense_category level=2 正常项，见关联接口⑤） |

## 七、错误码（HTTP 恒 200，判 code，按 message 原样提示）

| code | message | 说明 |
|---|---|---|
| 598705 | 部门/公司主体/申请人非法 | **文案放宽**（原"部门或公司主体非法"）：部门须在组织树 / 公司主体须 travel_agency 启用 / 申请人须存在且带真名 |
| 599112 | 冲抵借款时申请人必填 | offsetLoanIds 非空但 applicantId 空 |
| 599107 | 借款可冲余额不足，请重新勾选 | 勾选借款的 balanceAmt（可冲上限）不足以覆盖拟冲额 |
| 599113 | 勾选借款与报销申请人不一致 | offsetLoanIds 里借款单的借款人 ≠ 本报销单 applicantId |

**冲抵勾稽（自包含）**：勾选冲抵用 `GET /admin/finance/staff-loans/offsettable?staffId=<申请人adminId>` 查本申请人名下可冲借款，返回 `[{id, loanNo, amount, repaidAmt, balanceAmt(可冲上限), loanDate, purpose}]`，前端勾选后把选中借款单 `id` 数组传 `offsetLoanIds`。按勾选顺序逐笔 use=min(报销剩余额度, 该借款 balanceAmt)；后端汇总落 `offsetLoanAmt`，`payableAmt = amount − offsetLoanAmt`（出纳按此差额付款）。借款单侧字段/状态机详见 `13_staffloan_员工借款申请与审批-新增接口-管理后台.md`。

## 八、示例

### 典型·创建报销（含申请人/收款账号/申请凭证）

```json
POST /admin/finance/expenses
{
  "expenseCategory": "差旅费", "departmentId": "35",
  "company": "内蒙古呼籁国际旅行社有限公司", "amount": 1500.00, "reason": "出差海拉尔",
  "applicantId": "2083457702519873537", "payeeAccount": "6222020200112233", "voucherUrl": "https://oss/apply-voucher.jpg"
}
→ 200 { "code":200, "data":{ "id":"..." } }
详情出参含：applicantName="金卫"、operatorName="<当前登录人>"
```

### 典型·列表多状态筛选

```
GET /admin/finance/expenses/page?statuses=APPROVED&statuses=PAID&page=1&pageSize=20
→ 返回 APPROVED 或 PAID 的报销单（statuses 非空优先）
```

### 边界·详情付款记录（PAID 才有值）

```
GET /admin/finance/expenses/{id}   (status=PAID)
→ payRecords=[{ "flowNo":"LS2026...","fundAccountName":"呼籁国际-基本户","amount":1500.00,"fee":0,"payDate":"...","voucherUrl":"https://oss/pay-receipt.jpg" }]
   status 非 PAID 时 payRecords=[] 空数组
```

## 九、业务边界

- `statuses` 多状态与 `status` 单值：statuses 非空优先，两者均空=全部。
- `applicantName / operatorName` 为后端反查企微名落的快照/展示值，**前端不要传**，只读。
- `operatorId / operatorName` = 当前登录人（created_by）留痕，**只读透出**，前端不能传、仅展示；老数据或反查失败时 operatorName 为 null（不 fail-fast）。
- `applicantId` 传了非法（不存在/无真名）→ fail-fast 598705；不传则存空。

## 十、修改前后对比

| 项 | 改前 | 改后 |
|---|---|---|
| 列表状态筛选 | 仅 status 单值 | +statuses 多值（优先） |
| 详情付款记录 | 无 | +payRecords（含付款凭证） |
| 申请人 | 无 | +applicantId（选）/applicantName（快照） |
| 收款账号/申请凭证 | 无 | +payeeAccount / voucherUrl |
| 经办人 | 不透出 | +operatorId / operatorName（只读） |
| 598705 文案 | 部门或公司主体非法 | 部门/公司主体/申请人非法 |

## 十一、影响评估 / 回滚

- **非破坏**：出参只增不删向后兼容；入参新增均选填。旧前端不联动也能跑（看不到新字段/新筛选）。
- 回滚：接口层回退即可；DDL（V20260910_110 加 applicant_id/applicant_name/payee_account/voucher_url 4 列）保留无影响。

## 十二、关联接口（前端对接数据源，均现成）

**② 部门组织树** — `GET /admin/wechat/departments/tree`
- 出参树节点：id(String)、label、parentId(根=0)、children；选中 `id` 传 `departmentId`

**③ 申请人下拉（员工选择器）** — `GET /admin/user/employee-options`（🆕 不限角色，见 changelog `13_7625`）
- 入参：deptId / keyword / page / pageSize；出参：adminId、username、enterpriseWechatName、deptNames
- 选中取 `adminId` 传 `applicantId`

**④ 所属公司下拉** — `GET /v3/admin/travel-agency/enabled`（启用列表下拉）
- 出参项：agencyId、code、**agencyName**、isPrimary(1=主体公司,前端可默认选中)、sortOrder
- ⚠️ 选中后**传 `agencyName`（公司主体名字符串）给报销 `company`，不是 agencyId**

**⑤ 费用分类** — fin_expense_category level=2 正常项（按现有费用分类接口/字典取，此处不展开）

## 十三、关联 / 联系人

- Issue：https://git.1814.love:8443/wx/HL/issues/7472 ｜ /7486 ｜ /7502
- PR：https://git.1814.love:8443/wx/HL/pulls/7479 ｜ /7496 ｜ /7505
- 配套：费用支付（出纳）对接说明（见 `13_expense_费用支付出纳对接说明`）；员工选择器 `13_7625_员工选择器接口-新增接口-管理后台.md`
- 负责人：yst（腰苏图）