From d9bbf174e00e36daf50a326a76adb2c482b548eb Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Sun, 22 Mar 2026 23:32:16 +0800
Subject: [PATCH] =?UTF-8?q?changelog:=20=E5=B0=BE=E6=AC=BE=E5=87=AD?=
 =?UTF-8?q?=E8=AF=81=E4=B8=8A=E4=BC=A0=E5=8A=9F=E8=83=BD=E5=89=8D=E7=AB=AF?=
 =?UTF-8?q?=E7=BC=BA=E5=B0=91=E5=85=A5=E5=8F=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

后端接口已就绪(PUT /admin/order/{id}/record-balance)，前端需添加上传凭证按钮和确认收款操作。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../2026-03-22_balance_proof_upload.md        | 66 +++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 changelogs/2026-03/2026-03-22_balance_proof_upload.md

diff --git a/changelogs/2026-03/2026-03-22_balance_proof_upload.md b/changelogs/2026-03/2026-03-22_balance_proof_upload.md
new file mode 100644
index 0000000..be67a13
--- /dev/null
+++ b/changelogs/2026-03/2026-03-22_balance_proof_upload.md
@@ -0,0 +1,66 @@
+# 尾款凭证上传功能 — 前端缺少入口
+
+**日期**: 2026-03-22
+**页面**: 订单详情
+**类型**: 前端功能缺失
+
+---
+
+## 问题
+
+订单详情页没有"上传尾款凭证"的按钮，管理员无法记录线下收取的尾款。
+
+## 后端接口（已就绪）
+
+### 记录尾款（线下收取）
+```
+PUT /admin/order/{orderId}/record-balance
+```
+
+**请求体**：
+```json
+{
+  "proofUrl": "https://xxx.oss.aliyuncs.com/proof/xxx.jpg",  // 选填：支付凭证图片URL
+  "remark": "客户微信转账"                                      // 选填：备注
+}
+```
+
+**前置条件**：订单状态为 `CONFIRMED`（已确认）或 `PENDING_DEPARTURE`（待出发）
+
+**调用后效果**：
+- 订单状态变为 `PENDING_DEPARTURE`（待出发）
+- `balance_proof_url` 保存凭证图片
+- 时间线记录"管理员确认收到尾款"
+
+### 设置尾款支付方式
+```
+PUT /admin/order/{orderId}/balance-pay-method?balancePayMethod=OFFLINE
+```
+可选值：`ONLINE`（线上支付）/ `OFFLINE`（线下收取）
+
+## 前端实现建议
+
+### 显示时机
+订单状态为 `CONFIRMED`（已确认）且 `paymentMode = DEPOSIT`（定金模式）时，在订单详情页显示"尾款"区域。
+
+### UI 布局
+```
+┌─ 尾款信息 ──────────────────────────────┐
+│ 尾款金额：¥8,950.00（总价 - 已付定金）      │
+│ 支付方式：○ 线上支付  ● 线下收取            │
+│                                         │
+│ [上传凭证]  ← 点击上传图片（调文件服务）     │
+│ 备注：[________________]                  │
+│                                         │
+│              [确认收到尾款]                │
+└─────────────────────────────────────────┘
+```
+
+### 操作流程
+1. 管理员选择"线下收取"
+2. 上传凭证图片（调 `POST /admin/file/upload-token` 获取上传凭证 → 上传到 OSS → 拿到 URL）
+3. 点击"确认收到尾款" → 调 `PUT /admin/order/{orderId}/record-balance`
+4. 刷新订单详情
+
+### 已有凭证回显
+订单详情返回的 `balanceProofUrl` 字段如果有值，显示已上传的凭证图片。