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

docs(order-v3): 预支借款对象改下拉同步——候选接口+payeeStaffId+585007（#4465）

浏览代码 
更新预支管理终态文档:新增 GET /advance/payee-candidates 候选下拉+AdvancePayeeCandidateVO 出参+创建入参 payeeStaffId 必填+585007 错误码+585002 废弃;借款对象语义从强制主报账人改为本单人员下拉选定(默认主报账人)。
这个提交包含在：
yaosutu 2026-06-26 18:42:40 +08:00
父节点 558425c4f8
当前提交 4836fc9229
共有 1 个文件被更改，包括 62 次插入 和 19 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

81
changelogs-v2/2026-06/26_4452_订单预支管理-新增接口-管理后台.md
查看文件

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