wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

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

浏览代码
这个提交包含在：
yaosutu 2026-07-18 15:47:44 +08:00
父节点 cb3c557702
当前提交 4a88454172
共有 1 个文件被更改，包括 319 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

319
changelogs-v2/2026-07/18_5041_预支审批列表接口-新增接口-管理后台.md 普通文件
查看文件

@ -0,0 +1,319 @@
# 【新增接口·管理后台】预支审批列表接口 (#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