diff --git a/changelogs-v2/2026-07/18_5041_预支审批列表接口-新增接口-管理后台.md b/changelogs-v2/2026-07/18_5041_预支审批列表接口-新增接口-管理后台.md new file mode 100644 index 0000000..9acf61a --- /dev/null +++ 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