docs: 补充尾款凭证上传完整前端实现指南

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

changelogs/2026-03/2026-03-23_balance_proof_button_condition.md

@@ -1,8 +1,8 @@
-# 尾款凭证上传按钮显示条件修正（后端已改）
+# 尾款凭证上传功能（后端已完成，前端需实现）
 
 **日期**: 2026-03-23
-**页面**: 订单详情 → 尾款凭证上传按钮
+**页面**: 订单详情页
-**类型**: 前端修正 + 后端状态流转优化
+**类型**: 新功能
 
 ---
 
@@ -16,35 +16,65 @@
 新：CONFIRMED(READY) ──清单确认──→ PENDING_BALANCE ──记录尾款──→ PENDING_DEPARTURE
 ```
 
-## 前端尾款凭证上传按钮条件（简化了）
+## 前端需要实现
 
+### 1. 显示"上传尾款凭证"按钮
+
+显示条件：
 ```js
-// 尾款凭证上传按钮：定金模式 + 尾款未付 + 允许的状态
 const showBalanceProofBtn =
   order.paymentType === 'DEPOSIT'
   && !order.balanceProofUrl
   && ['PENDING_BALANCE', 'PENDING_DEPARTURE', 'TRAVELLING'].includes(order.status);
 ```
 
-| 条件 | 说明 |
+建议放在订单详情页**金额明细区域**的"尾款"行旁边，或作为顶部操作按钮。
-|------|------|
-| `status === 'PENDING_BALANCE'` | **主条件**：定金模式清单确认后自动进入此状态，等待上传凭证 |
-| `status === 'PENDING_DEPARTURE'` | 已到待出行但凭证未传，允许补传 |
-| `status === 'TRAVELLING'` | 已在出行中但凭证未传，允许补传 |
 
-### 不再需要判断 `processStatus === 'READY'`
+### 2. 点击按钮弹窗
 
-之前需要组合判断 `status + processStatus`，现在 `PENDING_BALANCE` 状态本身就表示"清单已确认、等待付尾款"，条件更简单。
+弹窗内容：
+| UI元素 | 说明 |
+|--------|------|
+| 标题 | "记录尾款收取" |
+| 尾款金额（只读展示） | 从订单详情取 `balanceAmount` 字段，格式 ¥xxxx.xx |
+| 上传凭证（图片上传） | 调用文件上传接口获取 OSS URL，非必填 |
+| 备注（文本框） | 最多500字，非必填 |
+| 确认按钮 | 调用记录尾款接口 |
 
-## 涉及接口
+### 3. 已上传凭证展示
 
-**上传尾款凭证**: `POST /admin/order/{orderId}/balance`
+当 `order.balanceProofUrl` 有值时，在尾款金额旁显示凭证图片（可点击放大查看）。
 
-请求体 (`RecordBalanceRequest`):
+## 接口定义
+
+### 记录尾款
+
+```
+PUT /admin/order/{orderId}/record-balance
+```
+
+请求体（JSON）：
 | 字段 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| proofUrl | String | 否 | 尾款凭证图片URL（OSS地址） |
+| proofUrl | String | 否 | 支付凭证图片URL（先通过文件上传接口上传到OSS，把返回的URL传这里） |
-| remark | String | 否 | 备注 |
+| 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`=线下转账 |
 
 ## 状态中文标签
 
@@ -52,3 +82,4 @@ const showBalanceProofBtn =
 |--------|---------|
 | `PENDING_BALANCE` | 待付尾款 |
 | `PENDING_DEPARTURE` | 待出行 |
+| `TRAVELLING` | 出行中 |