diff --git a/changelogs/2026-03/2026-03-20_order_surcharge.md b/changelogs/2026-03/2026-03-20_order_surcharge.md new file mode 100644 index 0000000..9df00da --- /dev/null +++ b/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` + +### 修改费用增加项 +- **PUT** `/admin/order/{orderId}/surcharge/{surchargeId}` +- **权限**:定制师本人 或 SUPER_ADMIN +- **请求体**:`SurchargeRequest` +- **响应**:`Result` + +### 删除费用增加项 +- **DELETE** `/admin/order/{orderId}/surcharge/{surchargeId}` +- **权限**:定制师本人 或 SUPER_ADMIN +- **响应**:`Result` + +--- + +## SurchargeRequest 参数 + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| surchargeName | String | 是 | 费用增加项名称,如"升级房型补差价" | +| surchargeAmount | BigDecimal | 是 | 费用增加金额,必须大于0 | + +## OrderSurcharge 响应 + +| 字段 | 类型 | 说明 | +|------|------|------| +| surchargeId | String | 费用增加项ID | +| orderId | String | 订单ID | +| surchargeName | String | 费用增加项名称 | +| surchargeAmount | BigDecimal | 费用增加金额 | +| createTime | DateTime | 创建时间 | + +--- + +## 订单详情/列表接口变更 + +### OrderDetailVO 新增字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| surchargeAmount | BigDecimal | 费用增加总额(缓存汇总值) | +| surcharges | List\ | 费用增加项列表 | + +### 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 +} +```