API Changelog Bot 804317d3a5 docs: 补充尾款凭证上传完整前端实现指南

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

2026-03-23 10:17:17 +08:00

2.6 KiB

原始文件 Blame 文件历史

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

日期: 2026-03-23 页面: 订单详情页类型: 新功能

后端改了什么

定金模式订单，清单确认完成后，订单状态不再直接跳到 PENDING_DEPARTURE（待出行），而是先进入 PENDING_BALANCE（待付尾款），上传凭证/记录尾款后才转为 PENDING_DEPARTURE。

状态流转变化：

旧：CONFIRMED(READY) ──记录尾款──→ PENDING_DEPARTURE
新：CONFIRMED(READY) ──清单确认──→ PENDING_BALANCE ──记录尾款──→ PENDING_DEPARTURE

前端需要实现

1. 显示"上传尾款凭证"按钮

显示条件：

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字

成功响应：

{ "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`	出行中

2.6 KiB 原始文件 Blame 文件历史 Unescape Escape