wx/hl-api-changelog

派生 0

yaosutu 4a88454172 新增预支审批列表接口变更说明

2026-07-18 15:47:44 +08:00

11 KiB

原始文件 Blame 文件历史

【新增接口·管理后台】预支审批列表接口 (#5041)

PR: #5044 / #5046 | 服务: hl-order-service-v3 + hl-user-service | 更新时间: 2026-07-18 15:40

1. 接口背景

管理后台需要在财务菜单下独立查看待审批、已通过、已驳回的订单预支记录。此前预支记录只能从订单详情上下文查看，财务人员缺少全局审批列表入口。

本次新增全局分页查询接口，并新增菜单入口：

菜单目录：财务管理
菜单名称：预支审批
菜单路由：advance-approvals
前端组件：finance/AdvanceApprovalList
列表权限：order:advance-approval:page
通过按钮权限：order:advance-approval:approve
驳回按钮权限：order:advance-approval:reject

2. 变更清单

#	接口	方法	路径	变更类型	说明
1	分页查询预支审批列表	GET	`/v3/admin/order/advance-approvals/page`	新增接口	按审批状态分页查询预支记录，并返回订单摘要字段

3. 接口详情

3.1 分页查询预支审批列表

使用场景：财务人员进入“财务管理 / 预支审批”页面时查询预支审批列表。
认证：需要管理后台 JWT。
权限点：order:advance-approval:page。
幂等性：是。该接口只读，不修改数据。
排序：按 submittedAt 倒序，其次按 createTime 倒序，再按 id 倒序。

4. 接口入参

4.1 Query 参数

字段	类型	必填	默认值	说明	校验规则
`page`	Integer	否	`1`	页码	最小值 `1`
`pageSize`	Integer	否	`20`	每页条数	最小值 `1`，最大值 `100`
`status`	String	否	`SUBMITTED`	审批状态	可传 `SUBMITTED` / `APPROVED` / `REJECTED`；大小写不敏感，后端会转大写
`orderId`	String	否	无	订单 ID 精确筛选	雪花 ID，前端按字符串处理
`keyword`	String	否	无	订单关键字	模糊匹配订单号、团号、产品名
`payeeName`	String	否	无	收款人姓名	模糊匹配
`createdByName`	String	否	无	申请人姓名	模糊匹配
`submittedAtFrom`	String	否	无	提交时间开始	格式 `yyyy-MM-dd'T'HH:mm:ss`
`submittedAtTo`	String	否	无	提交时间结束	格式 `yyyy-MM-dd'T'HH:mm:ss`

4.2 请求体

无请求体。

5. 出参

5.1 响应结构

{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [],
    "total": 0,
    "page": 1,
    "pageSize": 20
  },
  "traceId": "可选链路追踪ID",
  "success": true
}

5.2 `data` 字段

字段	类型	说明
`records`	Array	当前页记录列表
`total`	Integer	总记录数
`page`	Integer	当前页码
`pageSize`	Integer	每页条数

5.3 `records[]` 字段

字段	类型	说明
`id`	String	预支 ID
`orderId`	String	订单 ID
`payeeStaffId`	String	收款人对应的订单人员分配 ID
`payeeName`	String	收款人姓名
`payeeRole`	String	收款人角色编码
`payeeRoleText`	String	收款人角色中文
`advanceType`	String	预支类型
`amount`	Number	预支金额
`purpose`	String	用途说明
`voucherUrl`	String	凭证 URL，可为空
`status`	String	预支审批状态编码
`statusText`	String	预支审批状态中文
`rejectReason`	String	驳回原因，仅驳回记录通常有值
`createdByName`	String	申请人姓名
`createTime`	String	创建时间，格式为 ISO 日期时间
`submittedAt`	String	提交审批时间，格式为 ISO 日期时间
`approvedAt`	String	审批时间，通过或驳回后有值
`approvedBy`	String	审批人姓名
`orderNo`	String	订单号
`teamNo`	String	团号
`productName`	String	产品名称
`departDate`	String	出发日期，格式 `yyyy-MM-dd`
`returnDate`	String	返程日期，格式 `yyyy-MM-dd`
`consultantName`	String	定制师姓名
`orderStatus`	String	订单状态编码
`orderStatusName`	String	订单状态中文
`flowStatus`	String	流程状态编码
`flowStatusName`	String	流程状态中文
`payStatus`	String	支付状态编码
`payStatusName`	String	支付状态中文
`settlementStatus`	String	结算状态编码
`settlementStatusName`	String	结算状态中文
`orderAmount`	String	订单应收金额
`paidAmount`	String	订单已收金额

6. 枚举 / 数据字典

6.1 `status` / `records[].status`：预支审批状态

值	中文	说明
`SUBMITTED`	待审批	创建预支后进入待审批状态；默认查询此状态
`APPROVED`	已通过	财务审批通过
`REJECTED`	已驳回	财务审批驳回，通常带 `rejectReason`

6.2 `records[].payeeRole`：收款人角色

值	中文	说明
`DRIVER`	司机	司机人员
`LEADER`	导游	导游人员
`PHOTOGRAPHER`	摄影师	摄影人员
`OTHER`	其他	其他人员

6.3 订单状态类字段

orderStatus、flowStatus、payStatus、settlementStatus 返回系统内已有状态编码；对应中文展示优先使用同记录里的 orderStatusName、flowStatusName、payStatusName、settlementStatusName，前端不需要硬编码中文。

7. 错误码

code	含义	触发场景
`200`	成功	查询成功
`585005`	预支当前状态不允许此操作	`status` 传入值不在 `SUBMITTED` / `APPROVED` / `REJECTED` 内
`400`	参数校验失败	`page < 1`、`pageSize < 1`、`pageSize > 100` 或日期格式不符合要求
`401`	未认证	未携带有效管理后台 JWT

8. 示例

8.1 典型成功：查询待审批列表

请求：

GET /v3/admin/order/advance-approvals/page?page=1&pageSize=10&status=SUBMITTED HTTP/1.1
Authorization: Bearer {adminToken}

无请求体。

响应：

{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "id": "2077000000000000001",
        "orderId": "2076000000000000001",
        "payeeStaffId": "2076000000000000101",
        "payeeName": "张三",
        "payeeRole": "DRIVER",
        "payeeRoleText": "司机",
        "advanceType": "ACCOMMODATION_DEPOSIT",
        "amount": 500.00,
        "purpose": "住宿押金",
        "voucherUrl": "https://example.test/voucher/advance-001.jpg",
        "status": "SUBMITTED",
        "statusText": "待审批",
        "rejectReason": null,
        "createdByName": "腰苏图",
        "createTime": "2026-07-18T10:20:30",
        "submittedAt": "2026-07-18T10:20:30",
        "approvedAt": null,
        "approvedBy": null,
        "orderNo": "HL202607180001",
        "teamNo": "T202607180001",
        "productName": "草原亲子 3 日游",
        "departDate": "2026-07-21",
        "returnDate": "2026-07-23",
        "consultantName": "腰苏图",
        "orderStatus": "PENDING_DEPARTURE",
        "orderStatusName": "待出行",
        "flowStatus": "PENDING_DEPARTURE",
        "flowStatusName": "待出行",
        "payStatus": "PAID",
        "payStatusName": "已支付",
        "settlementStatus": "NONE",
        "settlementStatusName": "未核单",
        "orderAmount": "3600.00",
        "paidAmount": "3600.00"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 10
  },
  "success": true
}

8.2 边界情况：无记录

请求：

GET /v3/admin/order/advance-approvals/page?page=1&pageSize=20&status=APPROVED&keyword=NO_MATCH_KEYWORD HTTP/1.1
Authorization: Bearer {adminToken}

无请求体。

响应：

{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [],
    "total": 0,
    "page": 1,
    "pageSize": 20
  },
  "success": true
}

8.3 异常情况：非法审批状态

请求：

GET /v3/admin/order/advance-approvals/page?page=1&pageSize=10&status=BAD_STATUS HTTP/1.1
Authorization: Bearer {adminToken}

无请求体。

响应：

{
  "code": 585005,
  "message": "预支当前状态不允许此操作",
  "data": null,
  "success": false
}

9. 业务边界

status 不传时默认查 SUBMITTED。
status 支持小写或混合大小写，后端统一转大写后校验。
keyword 只匹配订单号、团号、产品名。
payeeName 只匹配收款人姓名。
createdByName 只匹配申请人姓名。
submittedAtFrom 与 submittedAtTo 都是闭区间过滤条件。
金额字段中，预支金额 amount 为数值；订单金额 orderAmount、paidAmount 为字符串，前端按字符串展示或转高精度数值处理。
ID 类字段均按字符串处理，避免 JS 数字精度问题。

10. 修改前后对比

新增接口，无旧接口对比。

11. 影响评估 / 回滚

新增接口和新增菜单入口，不破坏已有接口契约。

是否破坏向后兼容：否。
前端是否必须同步上线：否；未接入该页面时不影响原订单详情预支能力。
回滚影响：回滚后“财务管理 / 预支审批”菜单和列表接口不可用。

12. 注意事项

前端页面应挂到 财务管理 / 预支审批。
查询接口只负责列表展示，不执行审批动作。
审批通过、驳回按钮权限已经随菜单一起下发，按钮可以按权限点控制展示或禁用。
当前菜单按钮节点 visible=false，用于权限控制，不作为侧边栏可见菜单展示。

13. 关联 / 联系人

13.1 链接

Issue: #5041
PR: #5044
部署修复 Issue: #5045
部署修复 PR: #5046
Merge commit: b1ac11c03

13.2 验证记录

测试服 hl-user-service 8081/8181 双实例部署成功。
测试服 hl-order-service-v3 8086/8186 双实例部署成功。
网关实调 GET /v3/admin/order/advance-approvals/page?page=1&pageSize=10&status=SUBMITTED 返回 code=200、records=1。
网关实调非法 status=BAD_STATUS 返回 code=585005。
网关实调 /admin/menu/my 已返回“预支审批”菜单和通过/驳回按钮权限。

13.3 联系人

后端负责人: @yst

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

【新增接口·管理后台】预支审批列表接口 (#5041)

1. 接口背景

2. 变更清单

3. 接口详情

3.1 分页查询预支审批列表

4. 接口入参

4.1 Query 参数

4.2 请求体

5. 出参

5.1 响应结构

5.2 data 字段

5.3 records[] 字段

6. 枚举 / 数据字典

6.1 status / records[].status：预支审批状态

6.2 records[].payeeRole：收款人角色

6.3 订单状态类字段

7. 错误码

8. 示例

8.1 典型成功：查询待审批列表

8.2 边界情况：无记录

8.3 异常情况：非法审批状态

9. 业务边界

10. 修改前后对比

11. 影响评估 / 回滚

12. 注意事项

13. 关联 / 联系人

13.1 链接

13.2 验证记录

13.3 联系人

11 KiB

原始文件 Blame 文件历史

5.2 `data` 字段

5.3 `records[]` 字段

6.1 `status` / `records[].status`：预支审批状态

6.2 `records[].payeeRole`：收款人角色