diff --git a/changelogs-v2/2026-06/26_4452_订单预支管理-新增接口-管理后台.md b/changelogs-v2/2026-06/26_4452_订单预支管理-新增接口-管理后台.md index 512e083..5b88b62 100644 --- a/changelogs-v2/2026-06/26_4452_订单预支管理-新增接口-管理后台.md +++ b/changelogs-v2/2026-06/26_4452_订单预支管理-新增接口-管理后台.md @@ -12,7 +12,7 @@ ## ① 接口背景 -常规订单详情提供「预支借款」能力：定制师为订单的**主报账人**（司机/导游等）申请一笔预支款，财务审批通过/驳回。预支金额受订单待收尾款上限约束，借款类型走数据字典。 +常规订单详情提供「预支借款」能力：定制师为订单的**某位人员**（借款对象，从本单人员下拉选定，默认主报账人，#4465）申请一笔预支款，财务审批通过/驳回。预支金额受订单待收尾款上限约束，借款类型走数据字典。 **流程（去草稿后，#4452）**：创建即进「待审批」→ 财务通过（APPROVED，触发后置事件）/ 驳回（REJECTED）。财务审批前申请人可撤回。 @@ -22,11 +22,12 @@ | # | 方法 | 路径 | 说明 | |---|---|---|---| -| 1 | POST | `/v3/admin/order/{orderId}/advance` | 创建预支（创建即待审批 SUBMITTED） | -| 2 | PUT | `/v3/admin/order/advance/{advanceId}/approve` | 财务审批通过 | -| 3 | PUT | `/v3/admin/order/advance/{advanceId}/reject` | 财务审批驳回 | -| 4 | DELETE | `/v3/admin/order/advance/{advanceId}` | 撤回待审批预支（仅 SUBMITTED 可撤） | -| 5 | GET | `/v3/admin/order/{orderId}/advances` | 分页查询本单预支列表 | +| 1 | GET | `/v3/admin/order/{orderId}/advance/payee-candidates` | 借款对象候选下拉（全部人员，主报账人默认，#4465） | +| 2 | POST | `/v3/admin/order/{orderId}/advance` | 创建预支（创建即待审批 SUBMITTED；#4465 入参加 payeeStaffId） | +| 3 | PUT | `/v3/admin/order/advance/{advanceId}/approve` | 财务审批通过 | +| 4 | PUT | `/v3/admin/order/advance/{advanceId}/reject` | 财务审批驳回 | +| 5 | DELETE | `/v3/admin/order/advance/{advanceId}` | 撤回待审批预支（仅 SUBMITTED 可撤） | +| 6 | GET | `/v3/admin/order/{orderId}/advances` | 分页查询本单预支列表 | **⚠️ 已删除端点（#4452，旧路径调用返回 code=404「接口不存在」）**： @@ -40,16 +41,20 @@ 统一响应包：`{ code, message, data, success }`，`code=200` 成功；业务异常 `code` 为对应错误码（见 ⑦），HTTP 状态恒 200。 +### 0. 借款对象候选下拉 — GET `/v3/admin/order/{orderId}/advance/payee-candidates`（#4465） + +返回本单全部人员（order 人员配置），供创建预支时选择借款对象。主报账人（reporter_rank=PRIMARY）排第一并标 `isDefault=true`，前端默认选中。候选项 `id` 即创建预支的 `payeeStaffId` 入参。返回 `PageResult`（单页全量，`records / total`）。 + ### 1. 创建预支 — POST `/v3/admin/order/{orderId}/advance` 入口门槛（不满足抛对应错误码）： - 订单状态 ∈ {待出发 PENDING_DEPARTURE / 出行中 TRAVELLING}，否则 585001（#4462 收紧：已完成 COMPLETED、已取消 CANCELLED、定制中、待付款均不可创建预支） - 订单结算状态 ≠ 已结算完成，否则 585001 -- 订单须已配置主报账人（reporter_rank=PRIMARY），否则 585002 +- 借款对象 `payeeStaffId` 须为本单人员（取候选下拉的 id），否则 585007（#4465） - 借款类型须为字典 `advance_type` 内的值，否则 585006 - 预支金额 0 < amount ≤ 可用上限（可用上限 = 待收尾款 − 本单在途预支之和），否则 585003 / 585004 -报账人（payee）不入参，后端强制取该订单主报账人快照写入。创建成功状态直接为 `SUBMITTED`。 +借款对象由前端从候选下拉选定（#4465，不再强制主报账人，去掉原 585002 门槛），后端校验属本单后快照该人员姓名/角色写入。创建成功状态直接为 `SUBMITTED`。 ### 2. 审批通过 — PUT `/v3/admin/order/advance/{advanceId}/approve` @@ -75,12 +80,15 @@ | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| +| payeeStaffId | Long(字符串) | 是 | 借款对象，取候选下拉项的 id（#4465），须为本单人员，否则 585007 | | advanceType | String | 是 | 借款类型，取字典 `advance_type` 的 dictValue（见 ⑥） | | amount | BigDecimal | 是 | 预支金额，须 > 0（≥ 0.01） | | purpose | String | 否 | 用途说明 | | voucherUrl | String | 否 | 凭证文件 URL | -> payeeStaffId 不入参，后端取订单主报账人。 +### 候选下拉 / 分页查询 path + +候选下拉 `GET /v3/admin/order/{orderId}/advance/payee-candidates` 仅路径参数 `orderId`，无 query。 ### 驳回 请求体 RejectAdvanceReqVO @@ -101,7 +109,18 @@ approve / reject / revoke 仅路径参数 `advanceId`（approve/revoke 无请求 ## ⑤ 出参 -创建/审批/驳回 返回 `data` 为单个 OrderAdvanceRespVO；分页查询 `data` 为 `PageResult`（`records / total / page / pageSize`）。 +创建/审批/驳回 返回 `data` 为单个 OrderAdvanceRespVO；分页查询 `data` 为 `PageResult`；候选下拉 `data` 为 `PageResult`。 + +### AdvancePayeeCandidateVO（借款对象候选，#4465） + +| 字段 | 类型 | 说明 | +|---|---|---| +| id | String | 候选 ID（=创建预支 payeeStaffId，order 人员分配 ID） | +| staffName | String | 员工姓名 | +| staffRole | String | 员工角色代码（DRIVER/LEADER/PHOTOGRAPHER/OTHER 等） | +| staffRoleText | String | 员工角色文案（司机/导游/摄影师/其他） | +| reporterRank | String | 报账人等级（PRIMARY/SECONDARY/NONE） | +| isDefault | boolean | 是否默认选中（主报账人为 true，前端默认选此项） | ### OrderAdvanceRespVO @@ -159,22 +178,39 @@ approve / reject / revoke 仅路径参数 `advanceId`（approve/revoke 无请求 |---|---| | 585000 | 预支记录不存在 | | 585001 | 订单当前状态不可创建预支 | -| 585002 | 订单尚未配置主报账人，无法创建预支 | +| 585002 | ~~订单尚未配置主报账人~~（#4465 起借款对象可选任一人员，本码已废弃不再返回） | | 585003 | 预支金额必须大于 0 | | 585004 | 预支金额超过可用余额上限 | | 585005 | 预支当前状态不允许此操作（如撤回/审批一条非 SUBMITTED 的记录） | | 585006 | 借款类型非法（须为字典 advance_type 内的值） | -| 400 | 参数校验失败（如 advanceType 未填「借款类型必填」、amount 为空/≤0、reason 未填） | +| 585007 | 借款对象不属于本订单人员（payeeStaffId 非本单人员，#4465） | +| 400 | 参数校验失败（如 payeeStaffId 未填「借款对象必填」、advanceType 未填「借款类型必填」、amount 为空/≤0、reason 未填） | --- ## ⑧ 示例 -### 典型：创建预支 +### 典型：借款对象候选下拉（#4465） + +请求 `GET /v3/admin/order/2070038865875230722/advance/payee-candidates` +```json +{ + "code": 200, "success": true, "message": "成功", + "data": { + "total": 2, "page": 1, "pageSize": 2, + "records": [ + { "id": "9000000000000000001", "staffName": "刘领队", "staffRole": "LEADER", "staffRoleText": "导游", "reporterRank": "PRIMARY", "isDefault": true }, + { "id": "9000000000000000002", "staffName": "孙师傅", "staffRole": "DRIVER", "staffRoleText": "司机", "reporterRank": "NONE", "isDefault": false } + ] + } +} +``` + +### 典型：创建预支（#4465 带 payeeStaffId） 请求 `POST /v3/admin/order/2070038865875230722/advance` ```json -{ "advanceType": "TICKET", "amount": 100, "purpose": "景区门票预付" } +{ "payeeStaffId": "9000000000000000002", "advanceType": "TICKET", "amount": 100, "purpose": "景区门票预付" } ``` 响应 ```json @@ -182,8 +218,8 @@ approve / reject / revoke 仅路径参数 `advanceId`（approve/revoke 无请求 "code": 200, "success": true, "message": "成功", "data": { "id": "2070423136842539010", "orderId": "2070038865875230722", - "payeeStaffId": "9000000000000000001", "payeeName": "张司机", - "payeeRole": "GUIDE", "payeeRoleText": "导游", + "payeeStaffId": "9000000000000000002", "payeeName": "孙师傅", + "payeeRole": "DRIVER", "payeeRoleText": "司机", "advanceType": "TICKET", "amount": 100, "purpose": "景区门票预付", "status": "SUBMITTED", "statusText": "待审批", "createdByName": "定制师A", "submittedAt": "2026-06-26 16:25:17", @@ -192,6 +228,13 @@ approve / reject / revoke 仅路径参数 `advanceId`（approve/revoke 无请求 } ``` +### 异常：借款对象不属于本单（#4465） + +请求体 `{ "payeeStaffId": "999999", "advanceType": "TICKET", "amount": 100 }` +```json +{ "code": 585007, "success": false, "message": "借款对象不属于本订单人员", "data": null } +``` + ### 边界：审批通过 请求 `PUT /v3/admin/order/advance/2070423411452010498/approve` @@ -226,7 +269,7 @@ approve / reject / revoke 仅路径参数 `advanceId`（approve/revoke 无请求 - 仅订单状态为「待出发 / 出行中」时可创建预支（#4462）；已完成、已取消、定制中、待付款均返 585001。 - 一个订单可有多笔预支；在途（SUBMITTED + APPROVED）金额之和不得超过订单待收尾款。 -- 报账人取订单主报账人（reporter_rank=PRIMARY）快照，预支记录创建后不随报账人变更而变化。 +- 借款对象（payee）由前端从本单人员候选下拉选定（#4465），创建时快照该人员姓名/角色，预支记录创建后不随人员变更而变化；候选默认选中主报账人。 - 仅 SUBMITTED 可被 approve / reject / 撤回；APPROVED / REJECTED 为终态。 - 撤回为软删，列表不再返回被撤回记录。 @@ -261,6 +304,6 @@ approve / reject / revoke 仅路径参数 `advanceId`（approve/revoke 无请求 ## ⑬ 关联 / 联系人 -- Issue：https://git.1814.love:8443/wx/HL/issues/4429 ｜ https://git.1814.love:8443/wx/HL/issues/4440 ｜ https://git.1814.love:8443/wx/HL/issues/4452 -- PR：https://git.1814.love:8443/wx/HL/pulls/4429 ｜ https://git.1814.love:8443/wx/HL/pulls/4442 ｜ https://git.1814.love:8443/wx/HL/pulls/4453 +- Issue：https://git.1814.love:8443/wx/HL/issues/4429 ｜ /4440 ｜ /4452 ｜ /4462 ｜ /4465 +- PR：https://git.1814.love:8443/wx/HL/pulls/4429 ｜ /4442 ｜ /4453 ｜ /4463 ｜ /4466 - 负责人：yst（腰苏图）