# 编辑订单接口: depositAmount 等值视为未改, 跳过 PENDING_PAY 状态校验

> **服务**: hl-order-service-v2 (端口 8084)
> **PR**: #1827 (已合并 dev, 待部署 prod)
> **Issue**: #1826
> **日期**: 2026-05-07
> **影响范围**: 管理后台「编辑订单 → 出行人信息」tab 添加/修改出行人
> **@ 前端**: mmg

---

## ⚠️ 关键信息（前端无需改动）

后端做了**兼容性放宽**，前端可以**保持现状**继续把整 form 字段（含基本信息 tab 回显的 `depositAmount` 原值）一起 PUT 上来。

**不再需要前端区分「修改了金额」与「没修改金额」** — 后端会自动比较请求值与订单当前值，等值视为未改，跳过订金状态/上下界校验。

---

## 一、背景

后台「订单详情 → 编辑订单」弹窗在「出行人信息」tab 点「添加出行人」并提交时，对**非 PENDING_PAY** 状态订单（已分配定制师 / 已支付订金 / DEPOSIT_PAID 等）报错：

> 仅待支付状态可修改订金金额（errorCode 502101）

用户实际**没修改订金**，只是在添加出行人。根因：前端弹窗一次性 PUT 全 form，把基本信息 tab 中回显的 `depositAmount` 原值带回；后端 `OrderFieldEditService.adminEditOrder` 见 `depositAmount != null` 即强制校验 `PENDING_PAY`，无法区分「未改」vs「传了原值」。

---

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 管理端编辑订单 | PUT | `/admin/order/{orderId}` | **行为放宽（向后兼容）** | depositAmount 与订单当前值相等时跳过校验，业务规则保留 |

---

## 三、新行为定义

| 入参 `depositAmount` | 订单当前 `depositAmount` | 订单状态 | 行为 |
|---|---|---|---|
| `null` 或不传 | 任意 | 任意 | 不进入订金分支，无影响（原行为，未变） |
| 非 null，与当前相等 (`compareTo == 0`) | 非 null | 任意（含非 PENDING_PAY） | ✅ **新**：等值短路，整段订金校验+写入跳过；timeline 不记"订金"变更 |
| 非 null，与当前不等 | 任意 | `!= PENDING_PAY` | ❌ 502101 "仅待支付状态可修改订金金额"（保留） |
| 非 null，与当前不等 | 任意 | `PENDING_PAY` | 走原 3 项上下界校验（>0、≤总价），合法则落库 |
| 非 null | `null`（从未设过订金） | 任意 | 走原校验（不视为"未变"，防初始化场景被绕过） |

`compareTo` 不是 `equals`：`100.00` 与 `100` 视为相等（scale 不同 OK）。

---

## 四、前端建议（可选）

前端**无需改动**，下面只是建议性优化（不做也无影响）：

### 选项 A（推荐继续保持）：整 form PUT
继续把所有字段一起 PUT，后端兼容。

### 选项 B（可选优化）：仅传变更字段
只在用户真的修改 depositAmount 时才把它放进请求 body，其他字段同理。这样请求体更小，但**与本 BUG 修复无关**，纯优化。

---

## 五、数据库行为

只读比较，等值时**不写库**、不记 timeline、不发任何下游事件。

不等时按原逻辑：UPDATE `order_info.deposit_amount` + timeline 写"订金(¥xxx)"。

---

## 六、边界行为

- `depositAmount=null` 不传 → 不进分支，无影响
- `depositAmount` 等于当前值（任意状态） → 跳过校验，正常返回
- `depositAmount` 真改新值 + 非 PENDING_PAY → 仍报 502101
- `depositAmount` 真改新值 + PENDING_PAY + ≤0 → 报 502102
- `depositAmount` 真改新值 + PENDING_PAY + 超总价 → 报 502103
- `depositAmount` 真改新值 + PENDING_PAY + 合法值 → 200 落库

---

## 七、不影响范围

- **仅影响**: `PUT /admin/order/{orderId}` 一个接口的订金分支
- **零影响**:
  - 独立订金更新接口（如有，本次未动）
  - 小程序端订单编辑（不走该 service 方法）
  - 其他字段（联系人、出发日期、人数、备注、出行人等）所有逻辑不变
  - 其他状态校验（EDIT_STATUS_INVALID / EDIT_ORDER_LOCKED）不变
  - 历史数据零变更

---

## 八、测试环境已验证

- 后端单测 71/71 全绿，新增 `adminEditOrder_depositAmountSameValueOnNonPendingPay_shouldNotThrow` 覆盖 PAID + 同值场景
- 反例（PAID + 改新值仍 502101）已被现有 `adminEditOrder_depositAmountOnNonPendingPay_throwsBusinessException` 覆盖
- 测试服客观复现 BUG 现象（orderId `2052213192926392321` status=DEPOSIT_PAID 传 depositAmount=0.01 等值仍 502101）—— 修复部署后该请求应返回 200
- 修复版本 round-trip：本地受 `IpUtils` 类缺失（与本 BUG 无关的基础设施问题）阻塞，待测试服部署 dev 后由管理者补验

---

## 九、相关文档

- 关联 Issue: [wx/HL#1826](https://git.1814.love:8443/wx/HL/issues/1826)
- 关联 PR: [wx/HL#1827](https://git.1814.love:8443/wx/HL/pulls/1827)
