# 尾款凭证上传功能（后端已完成，前端需实现）

**日期**: 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` | 出行中 |