hl-api-changelog/changelogs/2026-03/2026-03-20_order_surcharge.md

订单费用增加项（surcharge）

功能说明

新增"费用增加项"功能，与现有"优惠项"（discount）对称：

• 优惠项：减少尾款（-¥）
• 费用增加项：增加尾款（+¥），如升级房型补差价、加座费等

权限限制

• 优惠项：任意管理员可操作
• 费用增加项：仅该订单的定制师本人或**超级管理员(SUPER_ADMIN)**可操作

金额计算变更（破坏性变更）

• 尾款 = 总价 - 定金 - 优惠总额 + 费用增加总额
• 全款 = 总价 - 优惠总额 + 费用增加总额

---

接口清单

添加费用增加项

• POST /admin/order/{orderId}/surcharge
• 权限：定制师本人 或 SUPER_ADMIN
• 请求体：SurchargeRequest
• 响应：Result<OrderSurcharge>

修改费用增加项

• PUT /admin/order/{orderId}/surcharge/{surchargeId}
• 权限：定制师本人 或 SUPER_ADMIN
• 请求体：SurchargeRequest
• 响应：Result<Void>

删除费用增加项

• DELETE /admin/order/{orderId}/surcharge/{surchargeId}
• 权限：定制师本人 或 SUPER_ADMIN
• 响应：Result<Void>

---

SurchargeRequest 参数

字段	类型	必填	说明
surchargeName	String	是	费用增加项名称，如"升级房型补差价"
surchargeAmount	BigDecimal	是	费用增加金额，必须大于0

OrderSurcharge 响应

字段	类型	说明
surchargeId	String	费用增加项ID
orderId	String	订单ID
surchargeName	String	费用增加项名称
surchargeAmount	BigDecimal	费用增加金额
createTime	DateTime	创建时间

---

订单详情/列表接口变更

OrderDetailVO 新增字段

字段	类型	说明
surchargeAmount	BigDecimal	费用增加总额（缓存汇总值）
surcharges	List<OrderSurcharge>	费用增加项列表

OrderListVO 新增字段

字段	类型	说明
surchargeAmount	BigDecimal	费用增加总额

balanceAmount 计算变更

原来：balanceAmount = totalPrice - depositAmount - discountAmount 现在：balanceAmount = totalPrice - depositAmount - discountAmount + surchargeAmount

---

页面布局建议

订单详情页 — 费用区域

在现有"优惠项"区域下方新增"费用增加项"区域：

优惠项
  ├ 会员折扣 -¥100.00  [编辑] [删除]    ← 任意管理员可操作
  └ [+ 添加优惠项]

费用增加项
  ├ 升级房型补差价 +¥200.00  [编辑] [删除]    ← 仅定制师/超管可操作
  └ [+ 添加费用增加项]                          ← 仅定制师/超管可见

金额汇总
  总价: ¥3000.00
  优惠: -¥100.00
  增加: +¥200.00
  定金: ¥1000.00
  尾款: ¥2100.00  (3000 - 1000 - 100 + 200)

权限判断

前端需要根据当前登录用户判断是否显示"添加/编辑/删除"费用增加项的按钮：

• 当前用户 roleKey === 'SUPER_ADMIN' → 显示
• 当前用户 adminId === order.customizerId → 显示
• 其他情况 → 隐藏按钮

---

调用示例

添加费用增加项

POST /admin/order/1234567890/surcharge
{
  "surchargeName": "升级房型补差价",
  "surchargeAmount": 200.00
}

修改费用增加项

PUT /admin/order/1234567890/surcharge/9876543210
{
  "surchargeName": "升级豪华房型补差价",
  "surchargeAmount": 300.00
}

删除费用增加项

DELETE /admin/order/1234567890/surcharge/9876543210

错误响应示例（权限不足）

{
  "code": 500,
  "message": "仅超级管理员或该订单的定制师可操作费用增加项",
  "data": null
}