docs: PR #1827 编辑订单 depositAmount 等值跳过校验 (Closes wx/HL#1826)

changelogs/2026-05/07_fix_order_v2_edit_deposit_unchanged_skip_validation.md

@@ -0,0 +1,107 @@
+# 编辑订单接口: 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)