# 【新增接口·管理后台】预支审批列表接口 (#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 响应结构

```json
{
  "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 典型成功：查询待审批列表

**请求**：

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

无请求体。

**响应**：

```json
{
  "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 边界情况：无记录

**请求**：

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

无请求体。

**响应**：

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

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

**请求**：

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

无请求体。

**响应**：

```json
{
  "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](https://git.1814.love:8443/wx/HL/issues/5041)
- **PR**: [#5044](https://git.1814.love:8443/wx/HL/pulls/5044)
- **部署修复 Issue**: [#5045](https://git.1814.love:8443/wx/HL/issues/5045)
- **部署修复 PR**: [#5046](https://git.1814.love:8443/wx/HL/pulls/5046)
- **Merge commit**: [b1ac11c03](https://git.1814.love:8443/wx/HL/commit/b1ac11c030a56a94fd8623f44b5a630fb41f2da9)

### 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