From f2e29e8c1123c63706ec5af311ae44d6643e6050 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Mon, 23 Mar 2026 09:51:11 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=B0=BE=E6=AC=BE=E5=87=AD=E8=AF=81?=
 =?UTF-8?q?=E4=B8=8A=E4=BC=A0=E6=8C=89=E9=92=AE=E6=98=BE=E7=A4=BA=E6=9D=A1?=
 =?UTF-8?q?=E4=BB=B6=E4=BF=AE=E6=AD=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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

diff --git a/changelogs/2026-03/2026-03-23_balance_proof_button_condition.md b/changelogs/2026-03/2026-03-23_balance_proof_button_condition.md
new file mode 100644
index 0000000..0385989
--- /dev/null
+++ b/changelogs/2026-03/2026-03-23_balance_proof_button_condition.md
@@ -0,0 +1,47 @@
+# 尾款凭证上传按钮显示条件修正
+
+**日期**: 2026-03-23
+**页面**: 订单详情 → 尾款凭证上传按钮
+**类型**: 前端修正
+
+---
+
+## 问题
+
+当前前端尾款凭证上传按钮的显示条件不准确，需要与后端逻辑对齐。
+
+## 正确的显示条件
+
+```js
+// 尾款凭证上传按钮显示条件
+const showBalanceProofBtn =
+  order.paymentType === 'DEPOSIT'
+  && (
+    (order.status === 'CONFIRMED' && order.processStatus === 'READY')
+    || order.status === 'PENDING_DEPARTURE'
+  );
+```
+
+### 条件说明
+
+| 条件 | 说明 |
+|------|------|
+| `paymentType === 'DEPOSIT'` | 必须是定金模式（定金+尾款） |
+| `status === 'CONFIRMED' && processStatus === 'READY'` | 已确认 + 内部流程全部完成（清单确认后进入就绪） |
+| `status === 'PENDING_DEPARTURE'` | 待出行状态（允许补传凭证） |
+
+### 注意
+
+- **不需要判断 `PENDING_BALANCE` 状态** — 后端不校验此状态
+- `CONFIRMED` 状态必须同时判断 `processStatus === 'READY'`，确保清单确认已完成后才能上传
+- 上传成功后，如果原状态是 `CONFIRMED`，后端会自动将订单状态转为 `PENDING_DEPARTURE`（待出行）
+
+## 涉及接口
+
+**上传尾款凭证**: `POST /admin/order/{orderId}/balance`
+
+请求体 (`RecordBalanceRequest`):
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| proofUrl | String | 否 | 尾款凭证图片URL（OSS地址） |
+| remark | String | 否 | 备注 |