feat: 订单费用增加项(surcharge)接口文档

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

changelogs/2026-03/2026-03-20_order_surcharge.md

@@ -0,0 +1,145 @@
+# 订单费用增加项（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` → 显示
+- 其他情况 → 隐藏按钮
+
+---
+
+## 调用示例
+
+### 添加费用增加项
+```json
+POST /admin/order/1234567890/surcharge
+{
+  "surchargeName": "升级房型补差价",
+  "surchargeAmount": 200.00
+}
+```
+
+### 修改费用增加项
+```json
+PUT /admin/order/1234567890/surcharge/9876543210
+{
+  "surchargeName": "升级豪华房型补差价",
+  "surchargeAmount": 300.00
+}
+```
+
+### 删除费用增加项
+```
+DELETE /admin/order/1234567890/surcharge/9876543210
+```
+
+### 错误响应示例（权限不足）
+```json
+{
+  "code": 500,
+  "message": "仅超级管理员或该订单的定制师可操作费用增加项",
+  "data": null
+}
+```