From 037b82eaaa1c442a3c67a47226d79258c87cd14c Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Fri, 26 Jun 2026 16:40:18 +0800 Subject: [PATCH] =?UTF-8?q?docs(order-v3):=20=E8=AE=A2=E5=8D=95=E9=A2=84?= =?UTF-8?q?=E6=94=AF=E7=AE=A1=E7=90=86=E6=9C=80=E7=BB=88=E6=80=81=E6=8E=A5?= =?UTF-8?q?=E5=8F=A3=E5=A5=91=E7=BA=A6=EF=BC=88=E5=88=9B=E5=BB=BA=E5=8D=B3?= =?UTF-8?q?=E5=BE=85=E5=AE=A1=E6=89=B9+=E5=8E=BB=E8=8D=89=E7=A8=BF?= =?UTF-8?q?=EF=BC=8C#4452=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 合并 #4429/#4440/#4452 为单一自包含文档：5 端点（创建即SUBMITTED/审批/驳回/撤回/列表）+借款类型字典+错误码585000-585006；声明 submit 端点已删 404。 --- .../26_4452_订单预支管理-新增接口-管理后台.md | 265 ++++++++++++++++++ 1 file changed, 265 insertions(+) create mode 100644 changelogs-v2/2026-06/26_4452_订单预支管理-新增接口-管理后台.md diff --git a/changelogs-v2/2026-06/26_4452_订单预支管理-新增接口-管理后台.md b/changelogs-v2/2026-06/26_4452_订单预支管理-新增接口-管理后台.md new file mode 100644 index 0000000..7c1c5f0 --- /dev/null +++ b/changelogs-v2/2026-06/26_4452_订单预支管理-新增接口-管理后台.md @@ -0,0 +1,265 @@ +# 订单预支管理（创建/审批/驳回/撤回/列表） + +- 端类型：管理后台 +- 变更类型：新增接口 +- 关联：Issue #4429 / #4440 / #4452 ｜ PR #4429 / #4442 / #4453 +- 服务：hl-order-service-v3 +- 日期：2026-06-26 + +> 本文为「订单预支借款」功能的最终态契约（合并 #4429 落地 + #4440 借款类型字典 + #4452 去草稿态），前端按本文对接即可，无需翻历史版本。 + +--- + +## ① 接口背景 + +常规订单详情提供「预支借款」能力：定制师为订单的**主报账人**（司机/导游等）申请一笔预支款，财务审批通过/驳回。预支金额受订单待收尾款上限约束，借款类型走数据字典。 + +**流程（去草稿后，#4452）**：创建即进「待审批」→ 财务通过（APPROVED，触发后置事件）/ 驳回（REJECTED）。财务审批前申请人可撤回。 + +--- + +## ② 变更清单 + +| # | 方法 | 路径 | 说明 | +|---|---|---|---| +| 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` | 分页查询本单预支列表 | + +**⚠️ 已删除端点（#4452，旧路径调用返回 code=404「接口不存在」）**： + +| 方法 | 旧路径 | 处理 | +|---|---|---| +| PUT | `/v3/admin/order/advance/{advanceId}/submit` | 已删除。去草稿后创建即待审批，无需单独提交动作 | + +--- + +## ③ 接口详情 + +统一响应包：`{ code, message, data, success }`，`code=200` 成功；业务异常 `code` 为对应错误码（见 ⑦），HTTP 状态恒 200。 + +### 1. 创建预支 — POST `/v3/admin/order/{orderId}/advance` + +入口门槛（不满足抛对应错误码）： +- 订单状态 ∈ {待出发 PENDING_DEPARTURE / 出行中 TRAVELLING / 已完成 COMPLETED}，否则 585001 +- 订单结算状态 ≠ 已结算完成，否则 585001 +- 订单须已配置主报账人（reporter_rank=PRIMARY），否则 585002 +- 借款类型须为字典 `advance_type` 内的值，否则 585006 +- 预支金额 0 < amount ≤ 可用上限（可用上限 = 待收尾款 − 本单在途预支之和），否则 585003 / 585004 + +报账人（payee）不入参，后端强制取该订单主报账人快照写入。创建成功状态直接为 `SUBMITTED`。 + +### 2. 审批通过 — PUT `/v3/admin/order/advance/{advanceId}/approve` + +仅 `SUBMITTED` 可通过，否则 585005。写 `approvedBy`/`approvedAt`，状态置 `APPROVED`，触发后置事件（出账逻辑后续补充）。 + +### 3. 审批驳回 — PUT `/v3/admin/order/advance/{advanceId}/reject` + +仅 `SUBMITTED` 可驳回，否则 585005。须填驳回原因，状态置 `REJECTED`。 + +### 4. 撤回待审批 — DELETE `/v3/admin/order/advance/{advanceId}` + +仅 `SUBMITTED` 可撤回（软删），财务已审批（APPROVED/REJECTED）不可撤回，否则 585005。 + +### 5. 分页查询 — GET `/v3/admin/order/{orderId}/advances` + +按 create_time 倒序返回本单预支列表，分页参数 `page`/`pageSize`。 + +--- + +## ④ 入参 + +### 创建预支 请求体 CreateAdvanceReqVO + +| 字段 | 类型 | 必填 | 说明 | +|---|---|---|---| +| advanceType | String | 是 | 借款类型，取字典 `advance_type` 的 dictValue（见 ⑥） | +| amount | BigDecimal | 是 | 预支金额，须 > 0（≥ 0.01） | +| purpose | String | 否 | 用途说明 | +| voucherUrl | String | 否 | 凭证文件 URL | + +> payeeStaffId 不入参，后端取订单主报账人。 + +### 驳回 请求体 RejectAdvanceReqVO + +| 字段 | 类型 | 必填 | 说明 | +|---|---|---|---| +| reason | String | 是 | 驳回原因 | + +### 分页查询 query + +| 字段 | 类型 | 必填 | 默认 | 说明 | +|---|---|---|---|---| +| page | int | 否 | 1 | 页码 | +| pageSize | int | 否 | 20 | 每页条数 | + +approve / reject / revoke 仅路径参数 `advanceId`（approve/revoke 无请求体）。 + +--- + +## ⑤ 出参 + +创建/审批/驳回 返回 `data` 为单个 OrderAdvanceRespVO；分页查询 `data` 为 `PageResult`（`records / total / page / pageSize`）。 + +### OrderAdvanceRespVO + +| 字段 | 类型 | 说明 | +|---|---|---| +| id | String | 预支 ID（雪花，字符串） | +| orderId | String | 订单 ID（字符串） | +| payeeStaffId | String | 报账人 staff 分配 ID（快照） | +| payeeName | String | 报账人姓名 | +| payeeRole | String | 报账人角色代码（DRIVER/LEADER/PHOTOGRAPHER/OTHER 等） | +| payeeRoleText | String | 报账人角色文案（DRIVER→司机/LEADER→导游/PHOTOGRAPHER→摄影师/OTHER→其他） | +| advanceType | String | 借款类型代码（字典 advance_type dictValue） | +| amount | BigDecimal | 预支金额 | +| purpose | String | 用途说明 | +| voucherUrl | String | 凭证文件 URL | +| status | String | 状态代码（SUBMITTED/APPROVED/REJECTED） | +| statusText | String | 状态文案（待审批/已通过/已驳回） | +| rejectReason | String | 驳回原因（仅 REJECTED 有值） | +| createdByName | String | 创建人姓名 | +| createTime | DateTime | 创建时间 | +| submittedAt | DateTime | 提交审批时间（创建即填充） | +| approvedAt | DateTime | 审批时间（通过/驳回时填充） | +| approvedBy | String | 审批人姓名 | + +--- + +## ⑥ 枚举 / 数据字典 + +### 状态 status（#4452 去 DRAFT，3 态） + +| code | 文案 statusText | 说明 | +|---|---|---| +| SUBMITTED | 待审批 | 创建后初始态，财务未审批前可撤回 | +| APPROVED | 已通过 | 财务审批通过（终态，触发后置事件） | +| REJECTED | 已驳回 | 财务审批驳回，含 rejectReason（终态） | + +> 旧 `DRAFT`（草稿）状态已删除，出参不再出现。 + +### 借款类型 advanceType（数据字典 `advance_type`，#4440） + +| dictValue | dictLabel | +|---|---| +| ACCOMMODATION_DEPOSIT | 住宿押金 | +| TICKET | 门票 | +| CATERING | 餐饮 | +| TRANSPORT | 交通用车 | + +> 字典项可后台维护，前端建议通过字典接口 `GET /admin/dict/data/advance_type` 动态取值，不要硬编码。 + +--- + +## ⑦ 错误码 + +| code | 含义 | +|---|---| +| 585000 | 预支记录不存在 | +| 585001 | 订单当前状态不可创建预支 | +| 585002 | 订单尚未配置主报账人，无法创建预支 | +| 585003 | 预支金额必须大于 0 | +| 585004 | 预支金额超过可用余额上限 | +| 585005 | 预支当前状态不允许此操作（如撤回/审批一条非 SUBMITTED 的记录） | +| 585006 | 借款类型非法（须为字典 advance_type 内的值） | +| 400 | 参数校验失败（如 advanceType 未填「借款类型必填」、amount 为空/≤0、reason 未填） | + +--- + +## ⑧ 示例 + +### 典型：创建预支 + +请求 `POST /v3/admin/order/2070038865875230722/advance` +```json +{ "advanceType": "TICKET", "amount": 100, "purpose": "景区门票预付" } +``` +响应 +```json +{ + "code": 200, "success": true, "message": "成功", + "data": { + "id": "2070423136842539010", "orderId": "2070038865875230722", + "payeeStaffId": "9000000000000000001", "payeeName": "张司机", + "payeeRole": "GUIDE", "payeeRoleText": "导游", + "advanceType": "TICKET", "amount": 100, "purpose": "景区门票预付", + "status": "SUBMITTED", "statusText": "待审批", + "createdByName": "定制师A", "submittedAt": "2026-06-26 16:25:17", + "approvedAt": null, "approvedBy": null, "rejectReason": null + } +} +``` + +### 边界：审批通过 + +请求 `PUT /v3/admin/order/advance/2070423411452010498/approve` +```json +{ "code": 200, "success": true, "data": { "status": "APPROVED", "statusText": "已通过", "approvedBy": "admin", "approvedAt": "2026-06-26 16:25:40" } } +``` + +### 异常：撤回一条已审批的预支 + +请求 `DELETE /v3/admin/order/advance/2070423411452010498` +```json +{ "code": 585005, "success": false, "message": "预支当前状态不允许此操作", "data": null } +``` + +### 异常：调用已删除的 submit 端点 + +请求 `PUT /v3/admin/order/advance/{advanceId}/submit` +```json +{ "code": 404, "success": false, "message": "接口不存在: PUT /v3/admin/order/advance/{advanceId}/submit", "data": null } +``` + +### 异常：借款类型非法 + +请求体 `{ "advanceType": "FOO", "amount": 100 }` +```json +{ "code": 585006, "success": false, "message": "借款类型非法（须为字典 advance_type 内的值）", "data": null } +``` + +--- + +## ⑨ 业务边界 + +- 一个订单可有多笔预支；在途（SUBMITTED + APPROVED）金额之和不得超过订单待收尾款。 +- 报账人取订单主报账人（reporter_rank=PRIMARY）快照，预支记录创建后不随报账人变更而变化。 +- 仅 SUBMITTED 可被 approve / reject / 撤回；APPROVED / REJECTED 为终态。 +- 撤回为软删，列表不再返回被撤回记录。 + +--- + +## ⑩ 修改前后对比（#4452 去草稿） + +| 维度 | 旧（#4429 初版） | 新（#4452） | +|---|---|---| +| 流程 | 草稿 DRAFT → 提交 SUBMITTED → 审批 | 创建即 SUBMITTED → 审批 | +| 创建后状态 | DRAFT（草稿） | SUBMITTED（待审批） | +| 提交端点 | PUT `.../submit` | 已删除（404） | +| DELETE 语义 | 删除草稿（仅 DRAFT） | 撤回待审批（仅 SUBMITTED） | +| status 取值 | DRAFT/SUBMITTED/APPROVED/REJECTED | SUBMITTED/APPROVED/REJECTED | + +--- + +## ⑪ 影响评估 / 回滚 + +- 前端：去掉「保存草稿 / 提交」两步交互，改为「创建即提交审批」；删除按钮语义改为「撤回」（仅待审批可点）；状态枚举去掉草稿。 +- 后端：去草稿态随 PR #4453 上线，Flyway V20260626_005 已执行（status 默认值 SUBMITTED + 历史 DRAFT 行迁移）。 + +--- + +## ⑫ 注意事项 + +- 所有 ID 字段（id/orderId/payeeStaffId）为字符串，避免 JS 精度丢失。 +- 借款类型务必从字典接口取值，字典可后台扩展。 +- 金额上限由后端依据订单待收尾款实时计算，前端提交后以后端校验为准。 + +--- + +## ⑬ 关联 / 联系人 + +- 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 +- 负责人：yst（腰苏图）