feat(changelog): 费用报销三件套(#7472/#7486/#7502) + 费用支付出纳对接说明

- 费用报销：page 加 statuses 多状态筛选、detail 加 payRecords 付款记录、表单补 applicantId/payeeAccount/voucherUrl、透出经办人 operatorId/operatorName、598705 文案放宽；含部门组织树/员工选择器/所属公司 travel_agency/费用分类关联接口指引 - 费用支付：出纳域对接说明（queue/pay/payments 按 EXPENSE 路由），接口无变更
2026-09-13 16:25:38 +08:00
@@ -0,0 +1,187 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7472/7486/7502"
+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: "费用报销三件套：①page 加 statuses 多状态筛选 + detail 聚合 payRecords 付款记录 ②create/update 入参加 applicantId/payeeAccount/voucherUrl（出参透出 applicantName） ③page/detail 出参加 operatorId/operatorName 经办人。错误码 598705 文案放宽。出参只增不删向后兼容，入参新增均选填。"
+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 / 599113 | 冲抵借款相关 | 见 PR #7566 冲抵借款 changelog |
+
+## 八、示例
+
+### 典型·创建报销（含申请人/收款账号/申请凭证）
+
+```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（腰苏图）
@@ -0,0 +1,77 @@
+---
+schema: "hl-changelog/v2"
+ticket: "expense-pay"
+title: "费用支付（出纳）：报销审批通过后的付款链路对接说明——队列/登记付款/已付台账按 EXPENSE 路由"
+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=EXPENSE 路由。本文给前端费用支付页的对接口径。"
+updated_at: "2026-09-13"
+base: "dev-v3"
+---
+
+# 费用支付（出纳）—— 报销付款链路对接说明
+
+> **服务**: hl-order-service-v3（hl-finance 财务模块·出纳域）
+> **端**: 管理后台
+> **类型**: 📘 对接说明（出纳域接口本次**无变更**，仅说明费用支付页怎么接）
+> **日期**: 2026-09-13
+> **关联**: 费用报销 changelog（`13_expense_费用报销多状态与申请人经办人`）
+
+## 一、接口背景
+
+费用报销单 `APPROVED`（审批通过）后进入**出纳待付款队列**，由出纳登记打款、回写报销单 PAID。费用支付**不单独建接口**，复用财务统一出纳接口 `/admin/finance/cashier/*`，按 `payType / bizType = EXPENSE` 路由出报销这一类的待付/已付数据。
+
+## 二、付款链路（报销视角）
+
+```
+报销单 approve(APPROVED)  →  出纳队列出现该待付单  →  出纳登记付款(pay, bizType=EXPENSE)
+  →  记资金流水 OUT + 回写报销单 PAID + 重算结存  →  已付款台账可查 / 报销详情 payRecords 回显
+```
+
+> 报销单若有"冲抵借款"（offsetLoanAmt>0），出纳按 `payableAmt`（应付差额）付款，非全额 amount。
+
+## 三、涉及接口（均为出纳域现有接口，按 EXPENSE 过滤）
+
+### ① 出纳待付款队列 — `GET /admin/finance/cashier/queue`
+- 入参：`payType=EXPENSE`（费用报销）+ page/pageSize（其余筛选项按 VO）
+- 出参行：报销单号 / 申请人 / 金额（应付 payableAmt）/ 状态 / 等
+- **费用支付页"待付款"列表 = 本接口 payType=EXPENSE**
+
+### ② 登记付款 — `POST /admin/finance/cashier/pay`
+- 入参：`bizType=EXPENSE` + `bizId`(报销单ID) + 出账账户 fundAccountId + 金额 + 手续费 + 付款日期 + 凭证 voucherUrl 等
+- 动作：记资金流水 OUT + 回写报销单 PAID + 重算账户结存 + 透支闸校验
+- 幂等/并发：同一报销单重复付款会被状态守卫拦截（已 PAID 不可重复付）
+
+### ③ 已付款流水台账 — `GET /admin/finance/cashier/payments/page`
+- 入参：`bizType=EXPENSE` + page/pageSize
+- **费用支付页"已付款"列表 = 本接口 bizType=EXPENSE**
+
+## 四、字段对接要点
+
+| 前端展示 | 来源 |
+|---|---|
+| 待付款列表 | `cashier/queue?payType=EXPENSE` |
+| 已付款列表 | `cashier/payments/page?bizType=EXPENSE` |
+| 登记付款动作 | `cashier/pay`（bizType=EXPENSE） |
+| 单张报销的付款记录（含付款凭证） | 报销详情 `GET /admin/finance/expenses/{id}` 的 `payRecords`（见报销 changelog） |
+
+## 五、注意事项
+
+1. 费用支付复用统一出纳队列/付款/台账接口，**不要**为报销单独写支付接口；靠 `payType/bizType=EXPENSE` 区分业务类型。
+2. 付款金额以报销单 `payableAmt`（应付差额）为准（有冲抵借款时 ≠ 报销总额 amount）。
+3. 付款凭证（出纳回单）通过 `cashier/pay` 的 voucherUrl 上传，回显在报销详情 `payRecords[].voucherUrl`，与报销"申请凭证" voucherUrl 是两个不同字段。
+4. 出账账户下拉用资金账户接口（`GET /admin/finance/fund-accounts` 启用项，取 ACTIVE 且非冻结账户）。
+
+## 六、关联 / 联系人
+
+- 报销单据 changelog：`13_expense_费用报销多状态与申请人经办人-修改接口-管理后台.md`
+- 出纳域（统一收付）：hl-finance `CashierController`（queue/pay/payments/confirm-in）
+- 负责人：yst（腰苏图）