docs(finance): 补推期初建账/业务外收支/出纳/费用报销 changelog（#7164/#7165/#7217/#7232）

2026-09-09 23:21:35 +08:00
@@ -0,0 +1,229 @@
 ---
 schema: "hl-changelog/v2"
 ticket: "7164"
 title: "往来期初建账（客户应收 / 供应商应付 / 员工往来 三本账）"
 consumer: "admin"
 author: "yst"
 change_type: "新增接口"
 backend_status: "deployed"
 gateway_status: "verified"
 frontend_status: "pending"
 frontend_owner: "hl-admin"
 frontend_ref: ""
 target_release: ""
 verified_at: "2026-09-06"
 status_note: "后端已合 dev-v3（hl-finance ledger 域）并部署测试服，E2E 验证通过。期初基准日=当前未封账账期起始日；净额=INIT+ΣADJUST 现算。"
 updated_at: "2026-09-06"
 base: "dev-v3"
 ---
 # 往来期初建账
 ## 1. 接口背景
 财务域「期初建账」：系统启用财务模块时，对客户应收、供应商应付、员工往来三本账做期初余额的一次性录入与后续调整。期初金额必须附佐证材料（影像 URL），期初基准日由后端取当前未封账账期的起始日，前端无需传。
 - 路径前缀：`/admin/finance/opening-balances`（3 个新端点）
 - 服务：hl-finance（财务服务）
 ## 2. 变更清单
 | 类型 | 接口 | 说明 |
 |---|---|---|
 | 新增 | GET `/admin/finance/opening-balances/page` | 往来期初分页（按账套过滤，支持类别/往来对象名筛选） |
 | 新增 | POST `/admin/finance/opening-balances` | 往来期初一次录入（同往来对象仅可录入一次初始期初） |
 | 新增 | POST `/admin/finance/opening-balances/adjust` | 往来期初调整单（须已录入初始期初；存调整全量值非差额） |
 ## 3. 接口详情
 ### 3.1 期初分页 GET /page
 - 使用场景：管理后台「期初建账」三个页签（客户应收 / 供应商应付 / 员工往来）的列表查询，页签切换 = 换 `ledgerType`。
 - 认证：管理后台管理员 Token（`Authorization: Bearer <admin-token>`），未登录返 401。
 - 幂等性：查询接口，天然幂等。
 - 限流：网关默认限流，无特殊配置。
 ### 3.2 期初一次录入 POST /
 - 使用场景：首次为某往来对象建立期初余额（INIT 行）。同一 `(ledgerType, refId)` 仅允许一条 INIT，重复录入报 598401。
 - 认证：同上。幂等性：非幂等（重复提交报 598401 不会产生重复 INIT 行，前端提交后应禁用按钮）。
 - 限流：网关默认。
 ### 3.3 期初调整单 POST /adjust
 - 使用场景：已录入 INIT 后修正期初金额。**存的是调整后全量值（非差额）**，每次调整落一行 `kind=ADJUST`，当前净额 = INIT + ΣADJUST 由后端现算。
 - 认证：同上。幂等性：非幂等（每次提交落一行调整记录）。
 - 限流：网关默认。
 ## 4. 接口入参
 ### 4.1 分页 Query（OpeningBalancePageReqVO）
 | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---:|---|---|
 | `ledgerType` | String | 是 | `CUSTOMER`/`SUPPLIER`/`STAFF` | 账套：CUSTOMER 客户应收 / SUPPLIER 供应商应付 / STAFF 员工往来 |
 | `kind` | String | 否 | `INIT`/`ADJUST` | 类别：INIT 初始 / ADJUST 期初调整；空=全部 |
 | `refName` | String | 否 | 模糊匹配 | 往来对象名筛选；空=不限 |
 | `page` | Number | 否 | ≥1，默认 1 | 页码 |
 | `pageSize` | Number | 否 | 默认 20 | 每页条数 |
 ### 4.2 一次录入 Body（OpeningBalanceCreateReqVO）
 | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---:|---|---|
 | `ledgerType` | String | 是 | 同上枚举 | 账套 |
 | `refId` | Number | 是 | — | 往来对象 ID（客户/供应商/员工主键，按账套对应） |
 | `refName` | String | 是 | ≤128 字 | 往来对象名称（冗余快照，落库后不随主数据改名） |
 | `openingPayable` | Number | 条件 | >0 | 期初应付（我欠他）；与 openingReceivable 至少填一项 |
 | `openingReceivable` | Number | 条件 | >0 | 期初应收（他欠我们）；与 openingPayable 至少填一项 |
 | `evidenceUrl` | String | 是 | — | 佐证材料影像 URL（必传，缺失抛 598402） |
 | `remark` | String | 否 | ≤200 字 | 备注 |
 ### 4.3 调整单 Body（OpeningBalanceAdjustReqVO）
 | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---:|---|---|
 | `ledgerType` | String | 是 | 同上枚举 | 账套 |
 | `refId` | Number | 是 | — | 往来对象 ID（须已存在 INIT 行，否则 598404） |
 | `openingPayable` | Number | 否 | >0 | 调整后**全量**期初应付（不调整传 null） |
 | `openingReceivable` | Number | 否 | >0 | 调整后**全量**期初应收（不调整传 null） |
 | `evidenceUrl` | String | 是 | — | 佐证材料影像 URL（必传，缺失抛 598402） |
 | `reason` | String | 是 | ≤200 字 | 调整原因（必填留痕） |
 ## 5. 出参字段
 ### 5.1 分页行（OpeningBalanceRowRespVO）
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `id` | String | 期初行 ID（雪花 ID，Long 序列化为字符串防 JS 精度丢失） |
 | `ledgerType` | String | 账套码（CUSTOMER/SUPPLIER/STAFF） |
 | `refId` | String | 往来对象 ID（雪花字符串） |
 | `refName` | String | 往来对象名称快照 |
 | `openingDate` | String | 期初基准日（yyyy-MM-dd，= 当前未封账账期起始日，后端带入） |
 | `kind` | String | 类别：INIT 初始 / ADJUST 期初调整 |
 | `openingPayable` | Number | 期初应付（无 = null） |
 | `openingReceivable` | Number | 期初应收（无 = null） |
 | `evidenceUrl` | String | 佐证材料影像 URL |
 | `recordedByName` | String | 录入人姓名快照 |
 | `createTime` | String | 创建时间（yyyy-MM-dd HH:mm:ss） |
 分页包裹：`data.records[]` / `data.total` / `data.page` / `data.pageSize`。
 ### 5.2 录入 / 调整响应（OpeningBalanceIdRespVO）
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `id` | String | 新落库期初行 ID（雪花字符串） |
 ## 6. 枚举 / 数据字典
 ### `ledgerType`（账套，代码枚举）
 | 值 | 中文 | 说明 |
 |---|---|---|
 | `CUSTOMER` | 客户应收 | 客户欠我们的期初 |
 | `SUPPLIER` | 供应商应付 | 我们欠供应商的期初 |
 | `STAFF` | 员工往来 | 员工借款/备用金期初 |
 ### `kind`（期初行类别，代码枚举）
 | 值 | 中文 | 说明 |
 |---|---|---|
 | `INIT` | 初始期初 | 首次录入，同往来对象唯一 |
 | `ADJUST` | 期初调整 | 调整单，存调整后全量值，可多条 |
 ## 7. 错误码（段位 598400-598499）
 | 错误码 | 含义 | 触发场景 |
 |---|---|---|
 | 598401 | 该往来对象期初已录入 | 同 `(ledgerType, refId)` 重复 POST 录入 INIT |
 | 598402 | 佐证材料必传 | `evidenceUrl` 为空 |
 | 598403 | 账期已封账，不允许录入或调整期初 | 当前账期已封账 / 无未封账账期（视同未开账） |
 | 598404 | 该往来对象尚未录入初始期初，不可调整 | POST /adjust 时无 INIT 行 |
 | 598405 | 期初应付/应收须至少填一项 | 两项均空或均 ≤0 |
 | 598406 | 账套类型非法，须为 SUPPLIER、CUSTOMER 或 STAFF | `ledgerType` 传其他值 |
 ## 8. 示例
 ### 8.1 典型成功（供应商应付期初录入）
 ```http
 POST /admin/finance/opening-balances
 Authorization: Bearer <admin-token>
 Content-Type: application/json
 {
  "ledgerType": "SUPPLIER",
  "refId": 2094123456789012345,
  "refName": "云山景区管理有限公司",
  "openingPayable": 50000.00,
  "openingReceivable": null,
  "evidenceUrl": "https://oss.example.com/evidence/abc.jpg",
  "remark": "2026 年 8 月对账单确认"
 }
 ```
 ```json
 {"code":200,"message":"成功","success":true,"data":{"id":"2094300011122233445"}}
 ```
 分页查询：
 ```http
 GET /admin/finance/opening-balances/page?ledgerType=SUPPLIER&page=1&pageSize=20
 ```
 ```json
 {"code":200,"success":true,"data":{"records":[{"id":"2094300011122233445","ledgerType":"SUPPLIER","refId":"2094123456789012345","refName":"云山景区管理有限公司","openingDate":"2026-09-01","kind":"INIT","openingPayable":50000.00,"openingReceivable":null,"evidenceUrl":"https://oss.example.com/evidence/abc.jpg","recordedByName":"腰苏图","createTime":"2026-09-06 10:00:00"}],"total":1,"page":1,"pageSize":20}}
 ```
 ### 8.2 边界情况（期初调整为零 / 双项同调）
 调整单传全量值，可把某项调成新值、另一项保持 null 不动：
 ```json
 {
  "ledgerType": "SUPPLIER",
  "refId": 2094123456789012345,
  "openingPayable": 48000.00,
  "openingReceivable": null,
  "evidenceUrl": "https://oss.example.com/evidence/def.jpg",
  "reason": "对方减免 2000 元尾款"
 }
 ```
 ```json
 {"code":200,"success":true,"data":{"id":"2094300099988877766"}}
 ```
 空分页：无数据时 `records=[]`、`total=0`，HTTP 200，前端正常渲染空列表。
 ### 8.3 业务失败（重复录入 / 未录初始就调整）
 ```http
 POST /admin/finance/opening-balances   # 同一 refId 再次录入
 ```
 ```json
 {"code":598401,"message":"该往来对象期初已录入","success":false,"data":null}
 ```
 ```http
 POST /admin/finance/opening-balances/adjust   # 该对象从未录入 INIT
 ```
 ```json
 {"code":598404,"message":"该往来对象尚未录入初始期初，不可调整","success":false,"data":null}
 ```
 缺佐证材料：`{"code":598402,"message":"佐证材料必传"}`；两项金额均空：`{"code":598405,"message":"期初应付/应收须至少填一项"}`。
 ## 9. 业务边界
 **适用**：
 - 财务模块上线初始化时，批量为三本账建立期初基准。
 - 期初金额有误时，通过调整单修正（保留全部调整留痕）。
 **不适用 / 限制**：
 - 同往来对象只能录入一次 INIT，后续一律走调整单。
 - 账期封账后禁止录入与调整（598403）；未开账（无未封账账期）同样拦截。
 - 期初基准日不可指定，由后端取当前未封账账期的 `start_date`。
 - 期初数据**暂未回流勾稽到往来账**（方案 A，留 TODO 接缝），本期仅作独立台账。
 **特殊边界**：
 - `refName` 是冗余快照，主数据改名不影响历史期初行显示。
 - 调整单存**全量值**不是差额，前端表单应展示「调整后金额」而非「调增/调减」。
 ## 10. 注意事项
 - 所有雪花 ID（`id` / `refId`）均已序列化为字符串，前端按 String 处理，勿转 Number。
 - `openingDate` 由后端带入，入参里没有该字段。
 - 前端三个页签（客户应收 / 供应商应付 / 员工往来）对应 `ledgerType` 三值，建议页签切换即重置筛选条件重新查询。
 - 新表 `fin_opening_balance`（Flyway `V20260906_101`），部署时自动执行，无需前端动作。
 ## 11. 关联 / 联系人
 - Issue：https://git.1814.love:8443/wx/HL/issues/7164
 - PR：https://git.1814.love:8443/wx/HL/pulls/7166
 - Commit：https://git.1814.love:8443/wx/HL/commit/d0f06fa2e8
 - Epic：https://git.1814.love:8443/wx/HL/issues/7163
 - 负责人：腰苏图（yst）
@@ -0,0 +1,274 @@
 ---
 schema: "hl-changelog/v2"
 ticket: "7165"
 title: "业务外收支流水（收入 IN / 支出 OUT 同表两入口）"
 consumer: "admin"
 author: "yst"
 change_type: "新增接口"
 backend_status: "deployed"
 gateway_status: "verified"
 frontend_status: "pending"
 frontend_owner: "hl-admin"
 frontend_ref: ""
 target_release: ""
 verified_at: "2026-09-06"
 status_note: "后端已合 dev-v3（hl-finance nonbiz 域）并部署测试服，E2E 验证通过。本期状态机只落 PENDING 草稿；提交/审批端点在 PR #7221 补齐，勾稽联动留 TODO。"
 updated_at: "2026-09-06"
 base: "dev-v3"
 ---
 # 业务外收支流水
 ## 1. 接口背景
 财务域「业务外收支」：记录与订单业务无关的公司收支（如利息收入、罚款支出、押金退回等），收入（IN）与支出（OUT）同表同接口、靠 direction 区分，管理后台拆成「业务外收入」「业务外支出」两个菜单页签。单据落库为 PENDING 草稿，本期草稿可编辑/删除；提交与审批流转在后续 PR #7221 补齐。
 - 路径前缀：/admin/finance/nonbiz-flows（5 个新端点）
 - 服务：hl-finance（财务服务）
 ## 2. 变更清单
 | 类型 | 接口 | 说明 |
 |---|---|---|
 | 新增 | GET /admin/finance/nonbiz-flows/page | 业务外收支分页（direction 必填区分收入/支出页签） |
 | 新增 | POST /admin/finance/nonbiz-flows | 业务外收支申请（收入/支出同接口，落 PENDING 草稿） |
 | 新增 | GET /admin/finance/nonbiz-flows/{id} | 收支单详情（收入/支出通用全字段） |
 | 新增 | PUT /admin/finance/nonbiz-flows/{id} | 编辑收支草稿（仅 PENDING；direction 不可改） |
 | 新增 | DELETE /admin/finance/nonbiz-flows/{id} | 删除收支草稿（仅 PENDING，软删） |
 ## 3. 接口详情
 ### 3.1 分页 GET /page
 - 使用场景：管理后台「业务外收入」「业务外支出」两个菜单共用一个接口，菜单切换 = 换 direction（IN/OUT）。
 - 认证：管理后台管理员 Token（Authorization: Bearer admin-token），未登录返 401。
 - 幂等性：查询接口，天然幂等。限流：网关默认。
 ### 3.2 申请 POST /
 - 使用场景：财务录入一笔业务外收入或支出，落 PENDING 草稿。
 - 认证：同上。幂等性：非幂等（每次创建生成新单据，前端提交后应禁用按钮）。限流：网关默认。
 ### 3.3 详情 GET /{id}
 - 使用场景：列表行点击进详情抽屉/页。
 - 认证：同上。幂等：查询接口。限流：网关默认。
 ### 3.4 编辑 PUT /{id}
 - 使用场景：修改 PENDING 草稿的类别/单位/金额/凭证等字段；方向不可改（收入单不能改成支出单）。
 - 认证：同上。幂等性：同参数重复提交效果一致。限流：网关默认。
 ### 3.5 删除 DELETE /{id}
 - 使用场景：作废 PENDING 草稿（软删，单据从所有列表消失）。
 - 认证：同上。幂等性：重复删除返 598504。限流：网关默认。
 ## 4. 接口入参
 ### 4.1 分页 Query（NonbizFlowPageReqVO）
 | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---:|---|---|
 | direction | String | 是 | IN/OUT | 方向：IN 业务外收入 / OUT 业务外支出 |
 | category | String | 否 | — | 收支类别码（fin_nonbiz_category，按方向分组）；空=不限 |
 | unitId | Number | 否 | — | 外部单位 ID；空=不限 |
 | status | String | 否 | 见状态枚举 | 单据状态；空=全部 |
 | occurDateStart | String | 否 | yyyy-MM-dd | 发生日期起 |
 | occurDateEnd | String | 否 | yyyy-MM-dd | 发生日期止 |
 | page | Number | 否 | 默认 1 | 页码 |
 | pageSize | Number | 否 | 默认 20 | 每页条数 |
 ### 4.2 申请 Body（NonbizFlowCreateReqVO）
 | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---:|---|---|
 | direction | String | 是 | IN/OUT | 方向 |
 | category | String | 是 | 不超64字 | 收支类别码，须为 fin_nonbiz_category 同方向组的正常项（598502） |
 | unitId | Number | 是 | — | 外部单位 ID（本期仅非空校验，存在性校验待往来账域接缝） |
 | unitName | String | 是 | 不超128字 | 外部单位名（冗余快照） |
 | amount | Number | 是 | 大于0 | 收支金额（598501） |
 | feeRate | Number | 否 | 千分率 | 手续费率（默认 0；收入页改动自动重算 fee） |
 | fee | Number | 否 | 不小于0 | 手续费（收入缺省按费率算、可手改；支出手填；actualAmount 联动重算） |
 | fundAccountId | Number | 否 | — | 入/出账公司账户 ID（空=批准时仅入账不联动资金结存） |
 | occurDate | String | 是 | yyyy-MM-dd | 发生日期 |
 | payMethod | String | 否 | 不超32字 | 收付方式（字典 fin_pay_way 码值） |
 | deptId | Number | 否 | — | 归属部门 ID（公司主体；用户域部门树） |
 | voucherNo | String | 否 | 不超64字 | 凭证号 |
 | voucherUrl | String | 否 | 不超500字 | 凭证影像 URL |
 | remark | String | 否 | 不超200字 | 备注 |
 ### 4.3 编辑 Body（NonbizFlowUpdateReqVO）
 字段与申请 Body 完全一致，唯不含 direction（方向由单据自身决定，编辑不换方向），见 4.2 表。
 ### 4.4 路径参数
 | 接口 | 字段 | 类型 | 说明 |
 |---|---|---|---|
 | GET/PUT/DELETE /{id} | id | Number | 收支单 ID（路径传数字即可，响应中为字符串） |
 ## 5. 出参字段
 ### 5.1 分页行（NonbizFlowRowRespVO）
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | id | String | 收支单 ID（雪花字符串） |
 | direction | String | 方向：IN / OUT |
 | category | String | 收支类别码 |
 | categoryName | String | 收支类别中文名（取自 fin_nonbiz_category；类别停用不影响历史单据回显） |
 | unitId | String | 外部单位 ID（雪花字符串） |
 | unitName | String | 外部单位名快照 |
 | amount | Number | 收支金额 |
 | fee | Number | 手续费（挂本单） |
 | actualAmount | Number | 实收/实付 = amount − fee |
 | deptId | String | 归属部门 ID（雪花字符串） |
 | operatorName | String | 经办人姓名快照 |
 | occurDate | String | 发生日期（yyyy-MM-dd） |
 | status | String | 单据状态码 |
 | payMethod | String | 收付方式码值（字典 fin_pay_way） |
 | payMethodName | String | 收付方式中文名（字典标签，字典缺失时为空） |
 ### 5.2 详情（NonbizFlowDetailRespVO）
 列表行全字段 + 以下增量字段：
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | feeRate | Number | 手续费率（千分率） |
 | fundAccountId | String | 入/出账公司账户 ID（空=批准时仅入账不联动结存） |
 | operatorId | String | 经办人 ID（雪花字符串） |
 | voucherNo | String | 凭证号 |
 | voucherUrl | String | 凭证影像 URL |
 | remark | String | 备注 |
 | createTime | String | 创建时间（yyyy-MM-dd HH:mm:ss） |
 ### 5.3 申请响应（NonbizFlowIdRespVO）
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | id | String | 新建收支单 ID（PENDING 草稿） |
 ### 5.4 编辑 / 删除响应
 data 为 null（Result<Void>），code=200 即成功。
 ## 6. 枚举 / 数据字典
 ### direction（方向，代码枚举）
 | 值 | 中文 |
 |---|---|
 | IN | 业务外收入 |
 | OUT | 业务外支出 |
 ### status（单据状态，代码枚举）
 | 值 | 中文 | 说明 |
 |---|---|---|
 | PENDING | 草稿 | 可编辑可删除（本期创建后唯一状态） |
 | SUBMITTED | 审批中 | 提交后锁定（流转端点在 PR #7221 补齐） |
 | APPROVED | 已批准 | 待出纳收付（流转端点在 PR #7221 补齐） |
 | REJECTED | 已驳回 | 审批驳回 |
 | PAID | 已收付讫 | 出纳执行完成，终态 |
 ### category（收支类别，基础数据表 fin_nonbiz_category）
 - 按类别码传值；类别按方向分组（IN 组 / OUT 组），跨组传值报 598502。
 - 类别维护走「业务外收支分类」管理接口（见 09_7052 changelog）。
 ### payMethod（收付方式，数据字典 fin_pay_way，dict_type_id=10157）
 | 码值 | 中文 |
 |---|---|
 | CASH | 现金 |
 | BANK_TRANSFER | 银行转账 |
 | WECHAT | 微信 |
 | ALIPAY | 支付宝 |
 字典标签由后端回显为 payMethodName，前端列表/详情直接展示，无需自行映射。
 ## 7. 错误码（段位 598500-598599）
 | 错误码 | 含义 | 触发场景 |
 |---|---|---|
 | 598501 | 金额无效（收支金额须大于0，且实收/实付不得为负） | amount≤0、fee<0 或 amount−fee<0 |
 | 598502 | 收支类别不存在或不属于该方向组 | category 不存在 / 跨方向组 / 已停用 |
 | 598503 | 当前状态不允许此操作，仅草稿可编辑或删除 | 非 PENDING 状态调 PUT/DELETE |
 | 598504 | 收支单不存在 | 详情/编辑/删除传错 ID（或已软删） |
 | 598505 | 状态流转非法（提交须草稿态，批准须审批中） | 状态机推进校验（流转端点见 PR #7221 changelog） |
 | 598506 | 方向非法，须为 IN 或 OUT | direction 传其他值 |
 ## 8. 示例
 ### 8.1 典型成功（录一笔业务外支出）
 ```http
 POST /admin/finance/nonbiz-flows
 Authorization: Bearer <admin-token>
 Content-Type: application/json
 {
  "direction": "OUT",
  "category": "DEPOSIT_REFUND",
  "unitId": 2094001122334455667,
  "unitName": "市文旅局",
  "amount": 2000.00,
  "fee": 0,
  "fundAccountId": 2097009988776655443,
  "occurDate": "2026-09-05",
  "payMethod": "BANK_TRANSFER",
  "deptId": 10086,
  "voucherNo": "PZ-20260905-01",
  "voucherUrl": "https://oss.example.com/voucher/pz01.jpg",
  "remark": "质保金退回"
 }
 ```
 ```json
 {"code":200,"message":"成功","success":true,"data":{"id":"2094311122233344455"}}
 ```
 收入页签分页：
 ```http
 GET /admin/finance/nonbiz-flows/page?direction=IN&page=1&pageSize=20&status=PENDING
 ```
 ```json
 {"code":200,"success":true,"data":{"records":[{"id":"2094311000000000001","direction":"IN","category":"INTEREST","categoryName":"利息收入","unitId":"2094001122334455667","unitName":"某银行","amount":500.00,"fee":0,"actualAmount":500.00,"deptId":"10086","operatorName":"腰苏图","occurDate":"2026-09-01","status":"PENDING","payMethod":"BANK_TRANSFER","payMethodName":"银行转账"}],"total":1,"page":1,"pageSize":20}}
 ```
 ### 8.2 边界情况（可选项全空 / 最小金额）
 ```json
 {
  "direction": "OUT",
  "category": "FINE",
  "unitId": 2094001122334455667,
  "unitName": "交管局",
  "amount": 0.01,
  "occurDate": "2026-09-06"
 }
 ```
 最小金额 0.01、可选项（feeRate/fee/fundAccountId/payMethod/deptId/voucher*/remark）全省略也可创建；actualAmount 后端按 amount − fee(默认0) 算好返回。空分页：records=[]、total=0，HTTP 200，前端正常渲染空列表。
 ### 8.3 业务失败（类别跨方向组 / 编辑非草稿）
 direction=IN 但传了 OUT 组的类别码：
 ```json
 {"code":598502,"message":"收支类别不存在或不属于该方向组","success":false,"data":null}
 ```
 对非 PENDING 单据调 PUT/DELETE：
 ```json
 {"code":598503,"message":"当前状态不允许此操作，仅草稿可编辑或删除","success":false,"data":null}
 ```
 amount=0 时：{"code":598501,"message":"金额无效（收支金额须大于0，且实收/实付不得为负）"}。
 ## 9. 业务边界
 适用：
 - 与订单无关的公司收支记账（利息、罚款、押金、捐赠等）。
 不适用 / 限制：
 - 本期（PR #7179）只落 PENDING 草稿 + 草稿编辑/删除；提交/审批流转端点在 PR #7221 补齐（submit/approve），状态机走到 PAID 依赖出纳域 cashier 端点。
 - 勾稽联动（批准后联动资金结存、进出纳队列、企微审批）本期未接通（方案 A，留 TODO 接缝）；fundAccountId 传了也只是记账引用，不会在批准时自动动账——动账由出纳域执行。
 - unitId 本期仅非空校验，不校验外部单位真实存在（待往来账域接缝，Epic #7163）。
 - direction 创建后不可改；改方向 = 删草稿重新录。
 特殊边界：
 - fee 收入单缺省按 feeRate（千分率）自动算、可手改覆盖；支出单手填。改 amount/feeRate/fee 后端联动重算 actualAmount。
 - 类别停用不删，历史单据 categoryName 正常回显。
 ## 10. 注意事项
 - 所有雪花 ID 均为字符串，前端按 String 处理，勿转 Number。
 - 两个菜单（收入/支出）共用接口，direction 必填，建议菜单切换即重置筛选重新查询。
 - payMethodName / categoryName 由后端字典回显，前端不要自己维护码表。
 - 新表 fin_nonbiz_flow（Flyway V20260906_102）+ 新字典 fin_pay_way（user-service V20260906_003，dict_type_id=10157），部署顺序先 user-service 后 finance，均部署自动执行。
 - 提交/审批端点（PUT /{id}/submit、/{id}/approve）与出纳付款能力见「07_7217_支付管理出纳」changelog。
 ## 11. 关联 / 联系人
 - Issue：https://git.1814.love:8443/wx/HL/issues/7165
 - PR：https://git.1814.love:8443/wx/HL/pulls/7179
 - Commit：https://git.1814.love:8443/wx/HL/commit/dc3b306f73
 - Epic：https://git.1814.love:8443/wx/HL/issues/7163
 - 负责人：腰苏图（yst）
@@ -0,0 +1,290 @@
 ---
 schema: "hl-changelog/v2"
 ticket: "7217"
 title: "支付管理·出纳（待付款队列 / 登记付款 / 已付款台账 / 收款确认 + 业务外状态机补全）"
 consumer: "admin"
 author: "yst"
 change_type: "新增接口"
 backend_status: "deployed"
 gateway_status: "verified"
 frontend_status: "pending"
 frontend_owner: "hl-admin"
 frontend_ref: ""
 target_release: ""
 verified_at: "2026-09-07"
 status_note: "后端已合 dev-v3（hl-finance cashier 域）并部署测试服。出纳统一付款执行出口：记资金流水 + 回写业务单 PAID + 重算结存 + 透支闸；本期队列/登记仅接通 NONBIZ 业务外线。"
 updated_at: "2026-09-07"
 base: "dev-v3"
 ---
 # 支付管理（出纳统一收付执行）
 ## 1. 接口背景
 财务域「支付管理」：出纳统一收付执行出口。上游业务单（本期=业务外支出）审批通过后进入出纳待付款队列，出纳在队列里选单登记付款——后端同事务完成「记资金流水 OUT + 回写业务单 PAID + 重算账户结存 + 透支闸校验」；业务外收入走「收款确认入账」端点直接记 IN 流水。同时业务外收支域补两个状态机推进端点（submit/approve），把单据从草稿推到已批准。
 - 出纳域路径前缀：/admin/finance/cashier（4 个新端点）
 - 业务外域补端点：/admin/finance/nonbiz-flows/{id}/submit、/{id}/approve（2 个新端点）
 - 服务：hl-finance（财务服务）
 ## 2. 变更清单
 | 类型 | 接口 | 说明 |
 |---|---|---|
 | 新增 | GET /admin/finance/cashier/queue | 出纳待付款队列（本期仅 NONBIZ 业务外支出进队列） |
 | 新增 | POST /admin/finance/cashier/pay | 登记付款（统一动作：记 OUT 流水 + 回写 PAID + 重算结存 + 透支闸） |
 | 新增 | GET /admin/finance/cashier/payments/page | 出纳已付款流水台账分页（数据源 fin_fund_flow OUT） |
 | 新增 | POST /admin/finance/cashier/confirm-in | 收款确认入账（业务外收入批准即入账：记 IN 流水 + 回写 PAID） |
 | 新增 | PUT /admin/finance/nonbiz-flows/{id}/submit | 提交收支单（PENDING → SUBMITTED，提交后锁定） |
 | 新增 | PUT /admin/finance/nonbiz-flows/{id}/approve | 批准收支单（SUBMITTED → APPROVED；本期手工置，企微审批待接通） |
 ## 3. 接口详情
 ### 3.1 待付款队列 GET /queue
 - 使用场景：管理后台「支付管理」待付款页签，出纳看待付单据列表。
 - 认证：管理后台管理员 Token（Authorization: Bearer admin-token），未登录返 401。
 - 幂等性：查询接口，天然幂等。限流：网关默认。
 ### 3.2 登记付款 POST /pay
 - 使用场景：出纳实际打款后在系统登记。后端同事务：记资金流水 OUT → 回写业务单 status=PAID → 重算账户结存 → 透支闸（余额不足且账户不允许透支时整单回滚报 598604）。
 - 认证：同上。幂等性：业务幂等——同一业务单重复付款被 CAS 条件更新拦截，返回 598602，不会重复记账。限流：网关默认。
 ### 3.3 已付款台账 GET /payments/page
 - 使用场景：出纳「已付款」页签，查历史付款流水（数据源为资金流水表 fin_fund_flow 的 OUT 出纳业务类记录）。
 - 认证：同上。幂等：查询接口。限流：网关默认。
 ### 3.4 收款确认入账 POST /confirm-in
 - 使用场景：业务外收入单批准（APPROVED）后，出纳确认钱已到账，记 IN 流水并回写单据 PAID。入账金额 = 单据实收 actualAmount，不可手改。
 - 认证：同上。幂等性：业务幂等——单据回写 PAID 后重复调用报 598606。限流：网关默认。
 ### 3.5 提交收支单 PUT /nonbiz-flows/{id}/submit
 - 使用场景：业务外收支草稿录入人提交审批，单据 PENDING → SUBMITTED 并锁定（不可编辑/删除）。
 - 认证：同上。幂等性：重复提交报 598505。限流：网关默认。无 Body。
 ### 3.6 批准收支单 PUT /nonbiz-flows/{id}/approve
 - 使用场景：财务负责人批准审批中的单据，SUBMITTED → APPROVED；支出单此后进出纳待付款队列，收入单待收款确认。本期为手工审批，企微审批流待接通。
 - 认证：同上。幂等性：重复批准报 598505。限流：网关默认。无 Body。
 ## 4. 接口入参
 ### 4.1 队列 Query（CashierQueueReqVO）
 | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---:|---|---|
 | payType | String | 否 | NONBIZ | 付款类型；空=NONBIZ。本期仅接通 NONBIZ（业务外支出），其余为预留枚举未建上游，传未接通值报 598607 |
 | page | Number | 否 | 默认 1 | 页码 |
 | pageSize | Number | 否 | 默认 20 | 每页条数 |
 ### 4.2 登记付款 Body（CashierPayReqVO）
 | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---:|---|---|
 | bizType | String | 是 | NONBIZ | 业务类型；本期仅 NONBIZ（业务外支出） |
 | bizId | Number | 是 | — | 业务单据 ID（须 status=APPROVED，否则 598602） |
 | payAccountId | Number | 是 | — | 出账公司账户 ID（fin_fund_account，不存在/停用报 598603） |
 | payMethod | String | 否 | — | 付款方式（字典 fin_pay_way 码值：CASH/BANK_TRANSFER/WECHAT/ALIPAY） |
 | amount | Number | 是 | 大于0 | 付款金额（598605） |
 | fee | Number | 否 | 不小于0 | 手续费（挂出账流水） |
 | voucherNo | String | 否 | — | 付款凭证号 |
 | voucherUrl | String | 否 | — | 付款凭证影像 URL |
 | payDate | String | 是 | yyyy-MM-dd | 付款日期（可回溯补录） |
 | operatorName | String | 否 | — | 后端忽略，统一取当前登录人快照；字段保留仅为入参兼容 |
 ### 4.3 台账 Query（CashierPaymentPageReqVO）
 | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---:|---|---|
 | bizType | String | 否 | NONBIZ | 业务类型筛选；空=NONBIZ |
 | fundAccountId | Number | 否 | — | 出账公司账户 ID；空=不限 |
 | flowNo | String | 否 | 模糊 | 流水号筛选 |
 | flowAtStart | String | 否 | yyyy-MM-dd | 收付日期起 |
 | flowAtEnd | String | 否 | yyyy-MM-dd | 收付日期止 |
 | page | Number | 否 | 默认 1 | 页码 |
 | pageSize | Number | 否 | 默认 20 | 每页条数 |
 ### 4.4 收款确认 Body（CashierConfirmInReqVO）
 | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---:|---|---|
 | bizId | Number | 是 | — | 业务单据 ID（须 direction=IN 且 status=APPROVED，否则 598606） |
 | payAccountId | Number | 是 | — | 入账公司账户 ID（fin_fund_account） |
 | payMethod | String | 否 | — | 收款方式（字典 fin_pay_way 码值） |
 | voucherNo | String | 否 | — | 收款凭证号 |
 | voucherUrl | String | 否 | — | 收款凭证影像 URL |
 | payDate | String | 是 | yyyy-MM-dd | 收款日期（可回溯补录） |
 ### 4.5 状态机端点路径参数
 | 接口 | 字段 | 类型 | 说明 |
 |---|---|---|---|
 | PUT /nonbiz-flows/{id}/submit、/{id}/approve | id | Number | 收支单 ID；无 Body |
 ## 5. 出参字段
 ### 5.1 队列行（CashierQueueRowRespVO）
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | id | String | 单据 ID（雪花字符串） |
 | bizNo | String | 业务单号（上游单据无单号列时为空，前端展示以 id 兜底） |
 | payType | String | 付款类型码（NONBIZ） |
 | payTypeName | String | 付款类型中文名（业务外支出） |
 | unitId | String | 外部单位 ID（雪花字符串） |
 | unitName | String | 外部单位名快照 |
 | category | String | 收支类别码 |
 | categoryName | String | 收支类别中文名（取自 fin_nonbiz_category） |
 | amount | Number | 付款金额 |
 | fee | Number | 手续费（挂本单） |
 | actualAmount | Number | 实付 = amount − fee |
 | operatorName | String | 申请人姓名快照 |
 | createTime | String | 申请时间（yyyy-MM-dd HH:mm:ss） |
 | occurDate | String | 发生日期（yyyy-MM-dd） |
 | status | String | 单据状态（队列内恒 APPROVED） |
 | remark | String | 备注 |
 ### 5.2 台账行（CashierPaymentRowRespVO）
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | id | String | 流水 ID（雪花字符串） |
 | flowNo | String | 流水号（LS+yyyyMMdd+4位序号） |
 | fundAccountId | String | 出账公司账户 ID（雪花字符串） |
 | accountName | String | 出账账户名称 |
 | amount | Number | 金额 |
 | fee | Number | 手续费（挂出账流水） |
 | balanceAfter | Number | 本笔记完后账户结存快照 |
 | bizType | String | 业务类型码（NONBIZ） |
 | bizTypeName | String | 业务类型中文名 |
 | bizId | String | 关联业务单据 ID（雪花字符串） |
 | bizNo | String | 业务单号（上游无单号列时为空） |
 | counterparty | String | 对方单位名快照 |
 | voucherUrl | String | 付款凭证影像 URL |
 | flowAt | String | 收付落账时间（yyyy-MM-dd HH:mm:ss） |
 | operatorName | String | 经办人姓名快照 |
 | remark | String | 备注 |
 ### 5.3 付款 / 收款确认响应（CashierPayRespVO）
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | flowId | String | 资金流水 ID（雪花字符串） |
 | flowNo | String | 资金流水号（LS+yyyyMMdd+4位序号） |
 | balanceAfter | Number | 本笔记完后账户结存快照 |
 | bizId | String | 业务单据 ID（已回写 PAID） |
 ### 5.4 状态机端点响应
 data 为 null（Result<Void>），code=200 即流转成功。
 ## 6. 枚举 / 数据字典
 ### payType / bizType（出纳业务类型，代码枚举）
 | 值 | 中文 | 说明 |
 |---|---|---|
 | NONBIZ | 业务外支出 | 本期唯一接通（队列/登记/台账均支持） |
 | EXPENSE / PAYMENT 等 | — | 预留枚举，上游未建，传入报 598607 |
 ### 业务外单据状态机（本次补全后）
 PENDING →(submit)→ SUBMITTED →(approve)→ APPROVED →(出纳 pay / confirm-in)→ PAID；SUBMITTED 可驳回为 REJECTED（驳回端点后续提供）。状态值见「06_7165_业务外收支流水」changelog 第 6 节。
 ### payMethod（收付方式，数据字典 fin_pay_way）
 | 码值 | 中文 |
 |---|---|
 | CASH | 现金 |
 | BANK_TRANSFER | 银行转账 |
 | WECHAT | 微信 |
 | ALIPAY | 支付宝 |
 ## 7. 错误码（段位 598600-598699 + 业务外段补 598505）
 | 错误码 | 含义 | 触发场景 |
 |---|---|---|
 | 598601 | 业务单不存在 | bizId 无效或已软删 |
 | 598602 | 业务单状态非已批准，不可付款 | 业务单非 APPROVED 即登记付款；同一单据重复付款（CAS 兜底）也报此码 |
 | 598603 | 出账账户不存在或已停用 | payAccountId 无效（recordFlow 内 FOR UPDATE 重读兜底） |
 | 598604 | 账户余额不足且不允许透支 | 出账触发透支闸（资金流水域 595103 在出纳边界的翻译） |
 | 598605 | 付款金额无效（金额须大于0，手续费不得为负） | amount≤0 或 fee<0 |
 | 598606 | 收款确认单状态非法（须为已批准的业务外收入单） | confirm-in 的单据非 direction=IN+APPROVED；重复确认也报此码 |
 | 598607 | 付款类型非法 | payType/bizType 传未接通值（本期仅 NONBIZ） |
 | 598505 | 状态流转非法（提交须草稿态，批准须审批中） | submit/approve 时状态不符（业务外收支段，见 7165 changelog） |
 ## 8. 示例
 ### 8.1 典型成功（队列选单 → 登记付款）
 ```http
 GET /admin/finance/cashier/queue?payType=NONBIZ&page=1&pageSize=20
 ```
 ```json
 {"code":200,"success":true,"data":{"records":[{"id":"2094311122233344455","bizNo":null,"payType":"NONBIZ","payTypeName":"业务外支出","unitId":"2094001122334455667","unitName":"市文旅局","category":"DEPOSIT_REFUND","categoryName":"押金退回","amount":2000.00,"fee":0,"actualAmount":2000.00,"operatorName":"腰苏图","createTime":"2026-09-06 11:00:00","occurDate":"2026-09-05","status":"APPROVED","remark":"质保金退回"}],"total":1,"page":1,"pageSize":20}}
 ```
 ```http
 POST /admin/finance/cashier/pay
 Content-Type: application/json
 {
  "bizType": "NONBIZ",
  "bizId": 2094311122233344455,
  "payAccountId": 2097009988776655443,
  "payMethod": "BANK_TRANSFER",
  "amount": 2000.00,
  "fee": 0,
  "voucherNo": "FK-20260907-01",
  "payDate": "2026-09-07"
 }
 ```
 ```json
 {"code":200,"success":true,"data":{"flowId":"2094400011122233445","flowNo":"LS202609070001","balanceAfter":112894.00,"bizId":"2094311122233344455"}}
 ```
 ### 8.2 边界情况（回溯补录 / 收款确认）
 付款日期可回溯补录历史付款：
 ```json
 {"bizType":"NONBIZ","bizId":2094311122233344460,"payAccountId":2097009988776655443,"amount":0.01,"payDate":"2026-08-15"}
 ```
 收款确认入账（业务外收入 APPROVED 单）：
 ```json
 {"bizId":2094311000000000001,"payAccountId":2097009988776655443,"payMethod":"BANK_TRANSFER","payDate":"2026-09-07"}
 ```
 入账金额由后端取单据 actualAmount，Body 无金额字段。空队列：records=[]、total=0，HTTP 200。
 ### 8.3 业务失败（重复付款 / 余额不足 / 类型非法）
 对同一单据再次登记付款：
 ```json
 {"code":598602,"message":"业务单状态非已批准，不可付款","success":false,"data":null}
 ```
 账户余额不足且不允许透支：
 ```json
 {"code":598604,"message":"账户余额不足且不允许透支","success":false,"data":null}
 ```
 payType 传未接通值：
 ```json
 {"code":598607,"message":"付款类型非法（本期仅支持 NONBIZ 业务外支出）","success":false,"data":null}
 ```
 ## 9. 业务边界
 适用：
 - 业务外支出（NONBIZ OUT）批准后的出纳付款执行与台账查询。
 - 业务外收入（NONBIZ IN）批准后的收款确认入账。
 - 业务外收支单从草稿到已批准的状态机推进（submit/approve）。
 不适用 / 限制：
 - 队列/登记付款本期仅接通 NONBIZ 一条线（方案 A）；工资/提成等类型已裁掉，其余枚举预留未建上游，传未接通值报 598607。
 - 批准本期为手工操作（approve 端点直接置 APPROVED），企微审批流留 TODO 未接通。
 - 出纳实付金额与单据 actualAmount 不一致时后端打 WARN 审计日志但不硬拦，允许出纳按实际打款登记。
 - confirm-in 入账金额恒等于单据 actualAmount，不支持部分入账。
 特殊边界：
 - operatorName 入参被后端忽略，经办人统一取当前登录人快照，防止冒名登记。
 - 登记付款 / 收款确认均为同事务「流水 + 回写」原子操作，失败整单回滚，不会出现只记流水不回写。
 - fin_nonbiz_flow 本 PR 补 3 列（pay_account_id/pay_flow_id/paid_at，Flyway V20260906_104），部署自动执行。
 ## 10. 注意事项
 - 所有雪花 ID 均为字符串，前端按 String 处理。
 - 队列行 bizNo 可能为空（上游单据无单号列），前端展示建议以单据 id 兜底。
 - 台账数据源是资金流水表（fin_fund_flow OUT），不是业务单表；一笔付款对应一行台账。
 - balanceAfter 是「本笔记完后」的账户结存快照，前端可直接展示无需再查账户余额。
 - 业务外收支域的 5 个基础端点见「06_7165_业务外收支流水」changelog；本文件只覆盖出纳 4 端点 + nonbiz 2 个流转端点。
 ## 11. 关联 / 联系人
 - Issue：https://git.1814.love:8443/wx/HL/issues/7217
 - PR：https://git.1814.love:8443/wx/HL/pulls/7221
 - Commit：https://git.1814.love:8443/wx/HL/commit/850cbf454c
 - Epic：https://git.1814.love:8443/wx/HL/issues/7216
 - 负责人：腰苏图（yst）
@@ -0,0 +1,510 @@
 ---
 schema: "hl-changelog/v2"
 ticket: "7232"
 title: "费用报销（申请→审批→出纳付款）+ 出纳队列接通费用线"
 consumer: "admin"
 author: "yst"
 change_type: "新增接口"
 backend_status: "deployed"
 gateway_status: "verified"
 frontend_status: "pending"
 frontend_owner: "hl-admin"
 frontend_ref: ""
 target_release: "v2.1"
 verified_at: "2026-09-07"
 status_note: "后端已合 dev-v3（hl-finance expense 域 + cashier 域扩 EXPENSE 分支）并部署测试服，E2E 16 PASS/0 FAIL。出纳 queue/pay/payments 入参枚举扩容 EXPENSE，省略时行为不变。"
 updated_at: "2026-09-07"
 base: "dev-v3"
 ---
 # 费用报销（申请→审批→出纳付款）+ 出纳队列接通费用线
 财务域新增**费用报销**子域：员工申请报销 → 财务审批（本期手工）→ 出纳付款 → 回写付讫。同时**出纳域待付款队列 / 付款登记 / 已付款台账**三个既有接口的入参枚举扩容，接通费用报销线（`payType/bizType` 新增 `EXPENSE` 值）。
 - expense 新域路径前缀：`/admin/finance/expenses`（8 个新端点）
 - cashier 既有域路径前缀：`/admin/finance/cashier`（3 个端点入参枚举扩容，无字段增删）
 ## 二、变更接口清单
 | # | 接口 | 方法 | 路径 | 变更类型 |
 |---:|---|---|---|---|
 | 1 | 报销分页 | GET | `/admin/finance/expenses/page` | 新增 |
 | 2 | 申请报销 | POST | `/admin/finance/expenses` | 新增 |
 | 3 | 报销详情 | GET | `/admin/finance/expenses/{id}` | 新增 |
 | 4 | 编辑草稿 | PUT | `/admin/finance/expenses/{id}` | 新增 |
 | 5 | 删除草稿 | DELETE | `/admin/finance/expenses/{id}` | 新增 |
 | 6 | 提交报销 | PUT | `/admin/finance/expenses/{id}/submit` | 新增 |
 | 7 | 批准报销 | PUT | `/admin/finance/expenses/{id}/approve` | 新增 |
 | 8 | 驳回报销 | PUT | `/admin/finance/expenses/{id}/reject` | 新增 |
 | 9 | 出纳待付款队列 | GET | `/admin/finance/cashier/queue` | 修改（入参 `payType` 扩容 `EXPENSE`） |
 | 10 | 出纳付款登记 | POST | `/admin/finance/cashier/pay` | 修改（入参 `bizType` 扩容 `EXPENSE`） |
 | 11 | 出纳已付款台账 | GET | `/admin/finance/cashier/payments/page` | 修改（入参 `bizType` 扩容 `EXPENSE`） |
 ## 三、接口详情
 ### 1. 报销分页 `GET /admin/finance/expenses/page`
 #### 使用场景
 管理后台「费用报销」列表页，按状态 / 部门 / 公司主体 / 关键字筛选分页查询。
 #### 认证 / 幂等性 / 限流
 - 认证：管理后台管理员 Token（`Authorization: Bearer <admin-token>`），未登录返 401。
 - 幂等性：查询接口，天然幂等。
 - 限流：走网关默认限流，无特殊配置。
 #### 入参（Query）
 | 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---:|---|---|
 | `status` | Query | String | 否 | 见状态枚举 | 按报销状态筛选，省略查全部 |
 | `departmentId` | Query | Number | 否 | 正整数 | 按部门 ID 筛选 |
 | `company` | Query | String | 否 | — | 按公司主体名称筛选 |
 | `keyword` | Query | String | 否 | — | 关键字模糊搜索（单号 / 事由） |
 | `page` | Query | Number | 是 | ≥1 | 页码 |
 | `pageSize` | Query | Number | 是 | 1-100 | 每页条数 |
 #### 出参
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `data.records[].id` | String | 报销单 ID（雪花 ID，Long 转字符串防 JS 精度丢失） |
 | `data.records[].expenseNo` | String | 报销单号（`FY-` 前缀） |
 | `data.records[].expenseCategory` | String | 费用分类末级名称 |
 | `data.records[].departmentId` | String | 部门 ID |
 | `data.records[].departmentName` | String | 部门名称 |
 | `data.records[].company` | String | 公司主体名称 |
 | `data.records[].amount` | Number | 报销金额 |
 | `data.records[].offsetLoanAmt` | Number | 冲销借款金额（本期恒 0，见业务边界） |
 | `data.records[].payableAmt` | Number | 应付金额（本期 = amount） |
 | `data.records[].reason` | String | 报销事由 |
 | `data.records[].rejectReason` | String | 驳回原因（仅 REJECTED 状态有值，其余为 null） |
 | `data.records[].fundAccountId` | String | 付讫资金账户 ID（仅 PAID 有值） |
 | `data.records[].status` | String | 状态码，见状态枚举 |
 | `data.records[].paidAt` | String | 付讫时间（仅 PAID 有值） |
 | `data.records[].approvalInstanceId` | String | 审批实例 ID（本期恒空，企微审批未接） |
 | `data.records[].createTime` | String | 创建时间 |
 | `data.total` / `page` / `pageSize` | Number | 分页元信息 |
 #### 请求示例（典型）
 ```http
 GET /admin/finance/expenses/page?page=1&pageSize=20&status=APPROVED&departmentId=10086
 Authorization: Bearer <admin-token>
 ```
 #### 响应示例（典型）
 ```json
 {
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "records": [
      {
        "id": "2094278854020399106",
        "expenseNo": "FY-20260907-0001",
        "expenseCategory": "市内交通费",
        "departmentId": "10086",
        "departmentName": "市场部",
        "company": "呼籁旅行社有限公司",
        "amount": 300.00,
        "offsetLoanAmt": 0,
        "payableAmt": 300.00,
        "reason": "客户拜访打车费",
        "rejectReason": null,
        "fundAccountId": null,
        "status": "APPROVED",
        "paidAt": null,
        "approvalInstanceId": null,
        "createTime": "2026-09-07 10:00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  }
 }
 ```
 #### 空数据 / 边界响应
 无匹配时 `records=[]`、`total=0`，HTTP 200，前端正常渲染空列表。
 ### 2. 申请报销 `POST /admin/finance/expenses`
 **VO**: `ExpenseCreateReqVO`
 #### 使用场景
 员工在管理后台提交一张费用报销单，落库为 PENDING 草稿（未进审批）。
 #### 认证 / 幂等性 / 限流
 - 认证：管理后台管理员 Token。
 - 幂等性：非幂等（每次创建生成新单号），重复提交产生多张单据，前端提交后应禁用按钮。
 - 限流：网关默认。
 #### 入参（Body）
 | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---:|---|---|
 | `expenseCategory` | String | 是 | 必须存在、为末级（level=2）、未停用 | 费用分类**末级名称**，按名称传不按 ID（取自 `fin_expense_category` 字典） |
 | `departmentId` | Number | 是 | 必须存在 | 部门 ID（用户域组织树 `wechat_department`） |
 | `company` | String | 是 | 必须为启用项 | 公司主体名称，按名称传（取自 `travel_agency` 启用项） |
 | `amount` | Number | 是 | >0 | 报销金额 |
 | `reason` | String | 是 | 非空 | 报销事由 |
 #### 出参
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `data.id` | String | 新建报销单 ID |
 | `data.expenseNo` | String | 报销单号（`FY-` 前缀） |
 | `data.status` | String | 创建后为 `PENDING` |
 #### 请求示例（典型成功）
 ```json
 {
  "expenseCategory": "市内交通费",
  "departmentId": 10086,
  "company": "呼籁旅行社有限公司",
  "amount": 300.00,
  "reason": "客户拜访打车费"
 }
 ```
 #### 请求示例（边界情况）
 金额为最小粒度 / 事由最长：
 ```json
 {
  "expenseCategory": "办公用品费",
  "departmentId": 10086,
  "company": "呼籁旅行社有限公司",
  "amount": 0.01,
  "reason": "采购 A4 打印纸一箱"
 }
 ```
 #### 请求示例（业务失败）
 费用分类传了非末级 / 已停用名称 → 598703：
 ```json
 {
  "expenseCategory": "交通费",
  "departmentId": 10086,
  "company": "呼籁旅行社有限公司",
  "amount": 300.00,
  "reason": "打车"
 }
 ```
 ```json
 {"code":598703,"message":"费用分类非法（不存在/非末级/已停用）","success":false,"data":null}
 ```
 金额 ≤0 → 598704；部门或公司主体非法 → 598705。
 ### 3. 报销详情 `GET /admin/finance/expenses/{id}`
 #### 入参
 | 字段 | 位置 | 类型 | 必填 | 说明 |
 |---|---|---|---:|---|
 | `id` | Path | String | 是 | 报销单 ID（雪花字符串） |
 #### 出参
 字段与分页行一致（`id/expenseNo/expenseCategory/departmentId/departmentName/company/amount/offsetLoanAmt/payableAmt/reason/rejectReason/fundAccountId/status/paidAt/approvalInstanceId/createTime`），见 §1 出参表。
 #### 错误响应
 ```json
 {"code":598701,"message":"报销单不存在","success":false,"data":null}
 ```
 ### 4. 编辑草稿 `PUT /admin/finance/expenses/{id}`
 **VO**: `ExpenseUpdateReqVO`（字段与 `ExpenseCreateReqVO` 完全一致，见 §2 入参表）
 #### 业务边界
 - 仅 `PENDING` 状态可编辑，其余状态调用返回 598702。
 - 编辑不改单号，状态保持 PENDING。
 #### 请求示例
 ```json
 {
  "expenseCategory": "市内交通费",
  "departmentId": 10086,
  "company": "呼籁旅行社有限公司",
  "amount": 350.00,
  "reason": "客户拜访打车费（含返程）"
 }
 ```
 #### 错误响应
 ```json
 {"code":598702,"message":"报销单状态非法（仅PENDING可编辑删除、提交须PENDING、审批须SUBMITTED）","success":false,"data":null}
 ```
 ### 5. 删除草稿 `DELETE /admin/finance/expenses/{id}`
 #### 业务边界
 - 仅 `PENDING` 状态可删除，其余状态调用返回 598702。
 - 删除为软删除，单据不再出现在任何列表。
 #### 出参
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `data` | Boolean | `true` 表示删除成功 |
 ### 6. 提交报销 `PUT /admin/finance/expenses/{id}/submit`
 #### 业务边界
 - 仅 `PENDING` 状态可提交，提交后流转 `PENDING → SUBMITTED`，单据进入锁定态（不可编辑 / 删除）。
 - 无 Body 入参。
 #### 出参
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `data.id` | String | 报销单 ID |
 | `data.status` | String | 提交后为 `SUBMITTED` |
 ### 7. 批准报销 `PUT /admin/finance/expenses/{id}/approve`
 #### 业务边界
 - 仅 `SUBMITTED` 状态可批准，流转 `SUBMITTED → APPROVED`，进入出纳待付款队列。
 - 本期为**手工审批**（不接企微审批流），`approvalInstanceId` 恒空。
 - 无 Body 入参。
 #### 出参
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `data.id` | String | 报销单 ID |
 | `data.status` | String | 批准后为 `APPROVED` |
 ### 8. 驳回报销 `PUT /admin/finance/expenses/{id}/reject`
 #### 入参（Body）
 | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---:|---|---|
 | `rejectReason` | String | 是 | 非空 | 驳回原因（回显在详情 `rejectReason` 字段） |
 #### 业务边界
 - 仅 `SUBMITTED` 状态可驳回，流转 `SUBMITTED → REJECTED`，不进出纳队列。
 #### 请求示例
 ```json
 {"rejectReason": "缺少打车发票附件，请补充后重新提交"}
 ```
 #### 出参
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `data.id` | String | 报销单 ID |
 | `data.status` | String | 驳回后为 `REJECTED` |
 ### 9. 出纳待付款队列 `GET /admin/finance/cashier/queue`（修改：payType 扩容）
 #### 变更点
 入参 `payType` 枚举由仅 `NONBIZ` 扩容为 `NONBIZ / EXPENSE`。传 `EXPENSE` 时返回费用报销线（`fin_expense` 表 `status=APPROVED` 的单据）；其余字段、结构、分页契约不变。
 #### 入参（Query，增量）
 | 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---:|---|---|
 | `payType` | Query | String | 否 | `NONBIZ` / `EXPENSE` | 付款类型筛选；省略 / 空 = 既有行为 |
 #### 出参（队列行，费用线字段填充规则）
 | 字段 | 类型 | 费用线（payType=EXPENSE）取值 |
 |---|---|---|
 | `id` | String | 报销单 ID |
 | `bizNo` | String | 报销单号（= expenseNo） |
 | `payType` | String | `EXPENSE` |
 | `payTypeName` | String | `费用` |
 | `unitId` / `unitName` | String | 槽位复用：部门 ID / 部门名称 |
 | `category` / `categoryName` | String | 费用分类（末级名称） |
 | `amount` | Number | 报销金额 |
 | `fee` | Number | 手续费（费用线为 0） |
 | `actualAmount` | Number | 应付金额（= payableAmt） |
 | `operatorName` | String | 申请人 |
 | `createTime` | String | 创建时间 |
 | `occurDate` | String | 发生日期 |
 | `status` | String | 队列状态 |
 | `remark` | String | 报销事由（= reason） |
 #### 请求示例
 ```http
 GET /admin/finance/cashier/queue?payType=EXPENSE
 Authorization: Bearer <admin-token>
 ```
 ### 10. 出纳付款登记 `POST /admin/finance/cashier/pay`（修改：bizType 扩容）
 #### 变更点
 入参 `bizType` 枚举新增 `EXPENSE` 值。`bizType=EXPENSE` 时 `bizId` 传报销单 ID，登记付款后回写 `fin_expense` 状态为 `PAID`、记录 `fundAccountId` / `paidAt`，同事务记资金流水。
 #### 入参（Body，关键字段）
 | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---:|---|---|
 | `bizType` | String | 是 | 新增 `EXPENSE` | 业务类型；费用报销传 `EXPENSE` |
 | `bizId` | String | 是 | 对应业务单据 ID | `bizType=EXPENSE` 时传报销单 ID |
 | `fundAccountId` | String | 是 | 必须存在 | 付款资金账户 ID |
 | `actualAmount` | Number | 是 | >0 | 出纳手录实际打款金额（默认带入 payableAmt，可改） |
 | 其余字段 | — | — | — | 与既有 NONBIZ 线一致，不变 |
 #### 业务边界
 - 出纳实际打款金额与 `payableAmt` 不一致时后端**打 WARN 审计日志但不硬拦**（允许出纳按实际打款登记）。
 - 并发防重：同事务记资金流水 + 条件更新回写，对同一报销单重复付款返回 598602。
 #### 错误响应
 重复付款：
 ```json
 {"code":598602,"message":"该单据已付款，请勿重复操作","success":false,"data":null}
 ```
 付款类型非法（598607 文案已扩为含 EXPENSE）：
 ```json
 {"code":598607,"message":"付款类型非法，本期支持 NONBIZ/EXPENSE","success":false,"data":null}
 ```
 ### 11. 出纳已付款台账 `GET /admin/finance/cashier/payments/page`（修改：bizType 扩容）
 #### 变更点
 入参新增 `bizType` 筛选，支持 `EXPENSE`；传空 / 省略 = 既有 NONBIZ 行为。其余字段、结构不变。
 #### 入参（Query，增量）
 | 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---:|---|---|
 | `bizType` | Query | String | 否 | `NONBIZ` / `EXPENSE` | 业务类型筛选；空 = NONBIZ（既有行为） |
 #### 请求示例
 ```http
 GET /admin/finance/cashier/payments/page?page=1&pageSize=20&bizType=EXPENSE
 Authorization: Bearer <admin-token>
 ```
 ## 六.5、枚举 / 数据字典
 ### `status`（报销单状态，代码枚举）
 **所属字段**: `ExpensePageReqVO.status / ExpenseRespVO.status` | **类型**: `String`
 | 值 | 中文 | 说明 |
 |---|---|---|
 | `PENDING` | 待提交 | 草稿态，可编辑可删除 |
 | `SUBMITTED` | 审批中 | 已提交，锁定（不可编辑 / 删除） |
 | `APPROVED` | 已批准 | 审批通过，待出纳付款 |
 | `REJECTED` | 已驳回 | 审批驳回，`rejectReason` 有值 |
 | `PAID` | 已付讫 | 出纳付款完成，终态只读 |
 状态机：`PENDING →(submit)→ SUBMITTED →(approve)→ APPROVED →(出纳付款)→ PAID`；`SUBMITTED →(reject)→ REJECTED`。
 ### `payType` / `bizType`（出纳域，枚举值扩容）
 **所属字段**: `cashier/queue` 入参 `payType`、`cashier/pay` 入参 `bizType`、`cashier/payments/page` 入参 `bizType` | **类型**: `String`
 | 值 | 中文 | 说明 |
 |---|---|---|
 | `NONBIZ` | 非业务付款 | 既有值，行为不变 |
 | `EXPENSE` | 费用（报销） | 新增值，费用报销线 |
 ### `expenseCategory`（费用分类，数据字典 `fin_expense_category`）
 - 按**末级名称**（level=2）传值，按名称不按 ID。
 - 仅正常（未停用）项可选；传非末级 / 不存在 / 已停用名称返回 598703。
 ### `company`（公司主体，数据字典 `travel_agency`）
 - 按名称传值，仅启用项可选；非法返回 598705。
 ### 错误码（新段 5987xx + 出纳段扩充）
 | 错误码 | 含义 | 触发场景 |
 |---|---|---|
 | 598701 | 报销单不存在 | 详情 / 编辑 / 删除 / 提交 / 审批传错 ID |
 | 598702 | 报销单状态非法 | 非 PENDING 编辑删除、非 PENDING 提交、非 SUBMITTED 审批 |
 | 598703 | 费用分类非法 | 分类不存在 / 非末级 / 已停用 |
 | 598704 | 金额无效 | `amount ≤ 0` |
 | 598705 | 部门或公司主体非法 | `departmentId` 不存在或 `company` 非启用项 |
 | 598706 | 单号取号撞号重试耗尽 | 极端并发下取号失败（重试后仍撞号） |
 | 598607 | 付款类型非法（文案扩充） | 出纳付款 / 台账传非 `NONBIZ/EXPENSE` 值 |
 ## 六.6、修改前后对比
 | 项目 | 修改前 | 修改后 |
 |---|---|---|
 | 费用报销接口 | 无 | 新增 `/admin/finance/expenses` 下 8 端点（分页 / 申请 / 详情 / 编辑 / 删除 / 提交 / 批准 / 驳回） |
 | 出纳队列 `payType` | 仅 `NONBIZ` | 扩容 `NONBIZ / EXPENSE` |
 | 出纳付款 `bizType` | 仅 `NONBIZ` | 扩容 `NONBIZ / EXPENSE` |
 | 出纳台账筛选 | 无 `bizType` 入参 | 新增 `bizType` 入参（空 = NONBIZ） |
 | 598607 文案 | 仅提示 NONBIZ | 扩为「付款类型非法，本期支持 NONBIZ/EXPENSE」 |
 ## 六.7、影响评估
 - **是否破坏向后兼容**：否。expense 8 端点为纯新增；出纳 3 端点为入参枚举扩容，省略新值时行为与之前完全一致。
 - **前端是否必须同步上线**：否。旧功能不受影响；费用报销页面与出纳队列费用线 Tab 可按节奏上线。
 - **前端 workaround 清理点**：无（全新能力）。
 ## 七、不影响范围
 - 小程序端（C 端）：费用报销为纯管理后台能力，`/mp/**` 零改动。
 - 出纳 NONBIZ 线：不传 `payType/bizType=EXPENSE` 时行为与之前完全一致。
 - 员工借款 / 冲销：本期未建借款域，`offsetLoanAmt` 恒 0、`payableAmt = amount`，留 TODO 后续接入。
 ## 八、测试环境已验证
 192.168.100.236 测试服行为级 E2E **16 PASS / 0 FAIL**：
 - 全链路走通：申请 → 提交 → 批准 → 出纳付款 → 回写 PAID。
 - 结存勾稽正确：付款前资金账户余额 114894 − 打款 300 = 114594。
 - 并发防重生效：重复付款返回 598602。
 - 四类校验生效：598702（状态非法）/ 598703（分类非法）/ 598704（金额无效）/ 598705（部门或公司非法）。
 ## 当前状态
 - 后端：已部署并已验证。
 - 前端：待处理（费用报销页面 + 出纳队列费用线 Tab）。
 ## 十、相关文档
 - Issue：[#7232](https://git.1814.love:8443/wx/HL/issues/7232)
 - 后端 PR：[#7247](https://git.1814.love:8443/wx/HL/pulls/7247)
 ## 关联 / 联系人
 - **Issue**: [#7232](https://git.1814.love:8443/wx/HL/issues/7232)
 - **PR**: [#7247](https://git.1814.love:8443/wx/HL/pulls/7247)
 - **后端负责人**: @yst
 - **当前状态**: 后端已就绪（TEST 已验证），前端待接入。