wx/hl-api-changelog

派生 0

文件

T

Mimingguang 5cdf062dd2

changelog-filename-gate / validate (push) Failing after 2s

详情

docs(changelog): #7232 frontmatter 回写 EXPENSE 付款字段勘误前端修复证据

2026-09-10 15:42:42 +08:00

20 KiB

原始文件 Blame 文件历史

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	7232	费用报销（申请→审批→出纳付款）+ 出纳队列接通费用线	admin	yst	新增接口	deployed	verified	verified	mmg	860ad6bc	v2.1	2026-09-10	verified 2026-09-10 mmg: expense.js 八端点+EXPENSE_STATUS 五态映射;expense/expense 列表页(状态/部门/公司/关键字筛选,分类末级按名传/公司按名传/部门手录注释,驳回 rejectReason 必填,详情按 REJECTED/PAID 条件显,操作列按状态机分叉);出纳 cashier 三端点扩容 EXPENSE 线随 #7217 一并交付(commit 7278c5f9)。expense.spec 锁端点/ID 透传/状态兜底。checkpoint 全绿。2026-09-10 后端更正:§10 出纳付款登记入参字段名勘误——付款账户/金额实为统一扁平 payAccountId/amount(此前误写输出字段 fundAccountId/actualAmount,前端据此调用触发 400)。2026-09-10 mmg 跟进修复(commit 860ad6bc):buildCashierPayPayload 删 EXPENSE 分叉统一 payAccountId/amount,CashierQueuePage 清理双键+EXPENSE 手续费恒 0 不传 fee,cashier.spec 断言翻转;checkpoint 全绿(含 Vitest 全量+生产构建)。此前联调记录的 cashier/pay EXPENSE 400 实为本文档笔误所致,非后端校验 bug。	2026-09-10	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	分页元信息

请求示例（典型）

GET /admin/finance/expenses/page?page=1&pageSize=20&status=APPROVED&departmentId=10086
Authorization: Bearer <admin-token>

响应示例（典型）

{
  "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`

请求示例（典型成功）

{
  "expenseCategory": "市内交通费",
  "departmentId": 10086,
  "company": "呼籁旅行社有限公司",
  "amount": 300.00,
  "reason": "客户拜访打车费"
}

请求示例（边界情况）

金额为最小粒度 / 事由最长：

{
  "expenseCategory": "办公用品费",
  "departmentId": 10086,
  "company": "呼籁旅行社有限公司",
  "amount": 0.01,
  "reason": "采购 A4 打印纸一箱"
}

请求示例（业务失败）

费用分类传了非末级 / 已停用名称 → 598703：

{
  "expenseCategory": "交通费",
  "departmentId": 10086,
  "company": "呼籁旅行社有限公司",
  "amount": 300.00,
  "reason": "打车"
}

{"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 出参表。

错误响应

{"code":598701,"message":"报销单不存在","success":false,"data":null}

4. 编辑草稿 `PUT /admin/finance/expenses/{id}`

VO: ExpenseUpdateReqVO（字段与 ExpenseCreateReqVO 完全一致，见 §2 入参表）

业务边界

仅 PENDING 状态可编辑，其余状态调用返回 598702。
编辑不改单号，状态保持 PENDING。

请求示例

{
  "expenseCategory": "市内交通费",
  "departmentId": 10086,
  "company": "呼籁旅行社有限公司",
  "amount": 350.00,
  "reason": "客户拜访打车费（含返程）"
}

错误响应

{"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，不进出纳队列。

请求示例

{"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）

请求示例

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 统一扁平入参（NONBIZ / EXPENSE / PAYMENT / PREPAY 共用同一套字段），付款账户 / 金额字段名固定为 payAccountId / amount。下方为全量必填/关键字段：

字段	类型	必填	约束	说明
`bizType`	String	是	新增 `EXPENSE`	业务类型；费用报销传 `EXPENSE`
`bizId`	String	是	对应业务单据 ID	`bizType=EXPENSE` 时传报销单 ID
`payAccountId`	String	是	必须存在且 ACTIVE	出账资金账户 ID（fin_fund_account）
`amount`	Number	是	>0	付款金额（出纳按实际打款金额录入，可与应付不一致）
`payDate`	String	是	yyyy-MM-dd	付款日期（可回溯补录）
`payMethod`	String	否	字典 fin_pay_way	付款方式（CASH/BANK_TRANSFER/WECHAT/ALIPAY）
`fee`	Number	否	≥0	手续费（挂出账流水）
`voucherNo`	String	否	—	付款凭证号
`voucherUrl`	String	否	—	付款凭证影像 URL

请求示例（bizType=EXPENSE）

{
  "bizType": "EXPENSE",
  "bizId": "2097885645098659841",
  "payAccountId": "2095340438490583041",
  "amount": 300.00,
  "payDate": "2026-09-10",
  "payMethod": "BANK_TRANSFER"
}

成功响应

{
  "code": 200,
  "message": "成功",
  "data": { "flowId": "2097946971271495682", "flowNo": "LS202609100002", "balanceAfter": 114594.0, "bizId": "2097885645098659841" },
  "success": true
}

业务边界

出纳实际打款金额与 payableAmt 不一致时后端打 WARN 审计日志但不硬拦（允许出纳按实际打款登记）。
并发防重：同事务记资金流水 + 条件更新回写，对同一报销单重复付款返回 598602。

错误响应

重复付款：

{"code":598602,"message":"业务单状态非已批准，不可付款","success":false,"data":null}

付款类型非法（598607 文案已扩为含 EXPENSE）：

{"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（既有行为）

请求示例

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
后端 PR：#7247

关联 / 联系人

Issue: #7232
PR: #7247
后端负责人: @yst
当前状态: 后端已就绪（TEST 已验证），前端待接入。

20 KiB 原始文件 Blame 文件历史 Unescape Escape

费用报销（申请→审批→出纳付款）+ 出纳队列接通费用线

二、变更接口清单

三、接口详情

1. 报销分页 GET /admin/finance/expenses/page

使用场景

认证 / 幂等性 / 限流

入参（Query）

出参

请求示例（典型）

响应示例（典型）

空数据 / 边界响应

2. 申请报销 POST /admin/finance/expenses

使用场景

认证 / 幂等性 / 限流

入参（Body）

出参

请求示例（典型成功）

请求示例（边界情况）

请求示例（业务失败）

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

入参（Body）

业务边界

请求示例

出参

9. 出纳待付款队列 GET /admin/finance/cashier/queue（修改：payType 扩容）

变更点

入参（Query，增量）

出参（队列行，费用线字段填充规则）

请求示例

10. 出纳付款登记 POST /admin/finance/cashier/pay（修改：bizType 扩容）

变更点

入参（Body，关键字段）

请求示例（bizType=EXPENSE）

成功响应

业务边界

错误响应

11. 出纳已付款台账 GET /admin/finance/cashier/payments/page（修改：bizType 扩容）

变更点

入参（Query，增量）

请求示例

六.5、枚举 / 数据字典

status（报销单状态，代码枚举）

payType / bizType（出纳域，枚举值扩容）

expenseCategory（费用分类，数据字典 fin_expense_category）

company（公司主体，数据字典 travel_agency）

错误码（新段 5987xx + 出纳段扩充）

六.6、修改前后对比

六.7、影响评估

七、不影响范围

八、测试环境已验证

当前状态

十、相关文档

关联 / 联系人

20 KiB

原始文件 Blame 文件历史

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 扩容）

10. 出纳付款登记 `POST /admin/finance/cashier/pay`（修改：bizType 扩容）

11. 出纳已付款台账 `GET /admin/finance/cashier/payments/page`（修改：bizType 扩容）

`status`（报销单状态，代码枚举）

`payType` / `bizType`（出纳域，枚举值扩容）

`expenseCategory`（费用分类，数据字典 `fin_expense_category`）

`company`（公司主体，数据字典 `travel_agency`）