86 行
2.6 KiB
Markdown
86 行
2.6 KiB
Markdown
# 尾款凭证上传功能（后端已完成，前端需实现）
|
||
|
||
**日期**: 2026-03-23
|
||
**页面**: 订单详情页
|
||
**类型**: 新功能
|
||
|
||
---
|
||
|
||
## 后端改了什么
|
||
|
||
定金模式订单，清单确认完成后，订单状态不再直接跳到 `PENDING_DEPARTURE`（待出行），而是先进入 **`PENDING_BALANCE`（待付尾款）**，上传凭证/记录尾款后才转为 `PENDING_DEPARTURE`。
|
||
|
||
状态流转变化：
|
||
```
|
||
旧：CONFIRMED(READY) ──记录尾款──→ PENDING_DEPARTURE
|
||
新：CONFIRMED(READY) ──清单确认──→ PENDING_BALANCE ──记录尾款──→ PENDING_DEPARTURE
|
||
```
|
||
|
||
## 前端需要实现
|
||
|
||
### 1. 显示"上传尾款凭证"按钮
|
||
|
||
显示条件：
|
||
```js
|
||
const showBalanceProofBtn =
|
||
order.paymentType === 'DEPOSIT'
|
||
&& !order.balanceProofUrl
|
||
&& ['PENDING_BALANCE', 'PENDING_DEPARTURE', 'TRAVELLING'].includes(order.status);
|
||
```
|
||
|
||
建议放在订单详情页**金额明细区域**的"尾款"行旁边，或作为顶部操作按钮。
|
||
|
||
### 2. 点击按钮弹窗
|
||
|
||
弹窗内容：
|
||
| UI元素 | 说明 |
|
||
|--------|------|
|
||
| 标题 | "记录尾款收取" |
|
||
| 尾款金额（只读展示） | 从订单详情取 `balanceAmount` 字段，格式 ¥xxxx.xx |
|
||
| 上传凭证（图片上传） | 调用文件上传接口获取 OSS URL，非必填 |
|
||
| 备注（文本框） | 最多500字，非必填 |
|
||
| 确认按钮 | 调用记录尾款接口 |
|
||
|
||
### 3. 已上传凭证展示
|
||
|
||
当 `order.balanceProofUrl` 有值时，在尾款金额旁显示凭证图片（可点击放大查看）。
|
||
|
||
## 接口定义
|
||
|
||
### 记录尾款
|
||
|
||
```
|
||
PUT /admin/order/{orderId}/record-balance
|
||
```
|
||
|
||
请求体（JSON）：
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| proofUrl | String | 否 | 支付凭证图片URL（先通过文件上传接口上传到OSS，把返回的URL传这里） |
|
||
| remark | String | 否 | 备注，最多500字 |
|
||
|
||
成功响应：
|
||
```json
|
||
{ "code": 200, "message": "success", "data": null }
|
||
```
|
||
|
||
调用成功后刷新订单详情（状态会从 `PENDING_BALANCE` 变为 `PENDING_DEPARTURE`）。
|
||
|
||
### 订单详情中相关字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| status | String | 订单状态，`PENDING_BALANCE` = 待付尾款 |
|
||
| paymentType | String | 支付模式，`DEPOSIT` = 定金+尾款 |
|
||
| balanceProofUrl | String | 尾款凭证URL，null表示未上传 |
|
||
| balanceAmount | BigDecimal | 尾款金额（后端已计算好） |
|
||
| balancePayMethod | String | 尾款支付方式：`ONLINE`=线上微信支付，`OFFLINE`=线下转账 |
|
||
|
||
## 状态中文标签
|
||
|
||
| status | 中文标签 |
|
||
|--------|---------|
|
||
| `PENDING_BALANCE` | 待付尾款 |
|
||
| `PENDING_DEPARTURE` | 待出行 |
|
||
| `TRAVELLING` | 出行中 |
|