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

2026-07-18 15:47:44 +08:00 · 2026-07-18 15:47:44 +08:00 · 4a88454172
--- a/changelogs-v2/2026-07/18_5041_预支审批列表接口-新增接口-管理后台.md
+++ b/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