812fd5d787
本批变更（测试环境已部署验证）： 1. 后端修复 9 个 BUG（#956/957/958/959/960 + hotfix #965/966/967） 2. BUG 10 产品地图支持高德自动生成（#962） 3. BUG 15 备品组合功能（#963） 4. BUG 20 早鸟优惠改造为 1:N 多方案（#964） 前端待跟进 BUG：1/2/5/6/8/12/19
146 行
5.8 KiB
Markdown
146 行
5.8 KiB
Markdown
# 早鸟优惠改造：产品 1:N 多方案 + 阶梯文案（BUG 20）
|
||
|
||
**日期**：2026-04-20
|
||
**PR**：#964 + hotfix #967
|
||
**影响**：管理端早鸟优惠管理页 + 小程序产品详情页 + 下单报价
|
||
|
||
---
|
||
|
||
## 业务变化
|
||
|
||
### 1. 一个产品可绑定多个早鸟方案
|
||
|
||
**改造前**：产品 1:1 方案。管理端创建第 2 个绑定同一产品的方案报错「以下产品已绑定其他早鸟计划，不能重复绑定」。
|
||
|
||
**改造后**：产品 1:N。可以配阶梯：
|
||
- 2 人打 9 折 (`minPeople=2, maxPeople=2, discountType=PERCENT, discountPercent=90`)
|
||
- 3-5 人打 85 折 (`minPeople=3, maxPeople=5, discountType=PERCENT, discountPercent=85`)
|
||
- 6 人及以上打 8 折 (`minPeople=6, maxPeople=null, discountType=PERCENT, discountPercent=80`)
|
||
|
||
报价时后端按订单人数自动匹配最优方案，落 `order_discount` 表。
|
||
|
||
### 2. 优惠类型扩展（3 种）
|
||
|
||
`discount_type` 字段新增：
|
||
|
||
| 值 | 含义 | 示例 | 需填字段 |
|
||
|---|---|---|---|
|
||
| `AMOUNT_TOTAL`（**默认**） | 整单立减 | 整单减 500 元 | `discountAmount` |
|
||
| `AMOUNT_PER_PERSON` | 每人立减 | 每人减 100 元 | `discountAmount` |
|
||
| `PERCENT` | 按比例打折 | 8 折 | `discountPercent` (0-100) |
|
||
|
||
**⚠️ 重要：老数据默认为 `AMOUNT_TOTAL`**（历史上运营侧约定 `discountAmount=500` 即整单立减 500，所以迁移时存量数据全部回正为 `AMOUNT_TOTAL`）。
|
||
|
||
---
|
||
|
||
## 接口变化
|
||
|
||
### 1. 创建/更新方案（兼容老调用，新字段可选）
|
||
|
||
**`POST /admin/order/early-bird`**
|
||
**`PUT /admin/order/early-bird/{planId}`**
|
||
|
||
`EarlyBirdPlanSaveReqVO` 新增字段：
|
||
|
||
```ts
|
||
{
|
||
"planName": "阶梯档 3-5 人 85 折",
|
||
"startDate": "2026-04-01",
|
||
"endDate": "2026-12-31",
|
||
"enabled": true,
|
||
"productIds": [123456],
|
||
|
||
// 老字段
|
||
"minPeople": 3,
|
||
"discountAmount": 0, // AMOUNT_TOTAL/PER_PERSON 必填；PERCENT 可为 null
|
||
|
||
// 新字段
|
||
"maxPeople": 5, // NEW 最高人数(含)，不传=不限
|
||
"discountType": "PERCENT", // NEW 默认 AMOUNT_TOTAL
|
||
"discountPercent": 85, // NEW PERCENT 时必填 (0<v<100)
|
||
"priority": 0 // NEW 同区间多命中决胜，默认 0
|
||
}
|
||
```
|
||
|
||
### 2. 响应 VO 新增字段
|
||
|
||
`EarlyBirdPlanVO`（列表/详情）新增后端拼好的**文案字段**：
|
||
|
||
```ts
|
||
{
|
||
"peopleRangeText": "3-5 人", // NEW 例："2 人"/"3-5 人"/"6 人及以上"
|
||
"discountText": "85 折", // NEW 例："9 折"/"每人立减 100 元"/"整单立减 500 元"
|
||
// ... 其他 4 个新业务字段（maxPeople/discountType/discountPercent/priority）
|
||
}
|
||
```
|
||
|
||
前端可直接用 `peopleRangeText` 和 `discountText` 做展示，无需自己拼。
|
||
|
||
### 3. 不再校验产品唯一
|
||
|
||
`POST /admin/order/early-bird` 去掉 `以下产品已绑定其他早鸟计划，不能重复绑定` 校验。同一 `productId` 可出现在任意多个方案。
|
||
|
||
### 4. 小程序产品详情页新增字段
|
||
|
||
**`GET /mp/product/item/{id}`** 响应 `MpProductDetailRespVO` 新增：
|
||
|
||
```ts
|
||
{
|
||
"earlyBirdTip": "最低 8 折起（共 3 档早鸟方案）", // 无人数上下文的概览文案，无绑定=null
|
||
"earlyBirdLadder": [ // 早鸟阶梯（按 min_people 升序）
|
||
{
|
||
"planId": "123",
|
||
"peopleRangeText": "2 人",
|
||
"discountText": "9 折",
|
||
"startDate": "2026-04-01",
|
||
"endDate": "2026-12-31"
|
||
},
|
||
{ "planId": "124", "peopleRangeText": "3-5 人", "discountText": "85 折", ... },
|
||
{ "planId": "125", "peopleRangeText": "6 人及以上", "discountText": "8 折", ... }
|
||
]
|
||
}
|
||
```
|
||
|
||
前端可按 ladder 画阶梯图。老字段 `earlyBirdTip` 语义微调为「概览性描述」，不再只拿第 1 个方案。
|
||
|
||
### 5. 小程序下单按人数本地匹配
|
||
|
||
前端可用 `earlyBirdLadder` 按用户选择的人数本地计算匹配档位，展示「您当前 X 人，命中 'Y 人 Z 折'；满 M 人可升级到 'N 折'」提示。
|
||
|
||
---
|
||
|
||
## 前端 TODO
|
||
|
||
### 管理端早鸟优惠管理页
|
||
1. 方案编辑表单加 **4 个新输入项**：
|
||
- 最高人数（数字，可空=不限）
|
||
- 优惠类型（单选：整单立减/每人立减/按比例打折），默认**整单立减**
|
||
- 折扣率（0-100，仅"按比例打折"时启用）
|
||
- 优先级（数字，默认 0）
|
||
2. 原"优惠金额 discountAmount"改为仅在"整单立减/每人立减"时启用
|
||
3. 产品绑定改为**多选 tag**（去掉 1:1 限制，可一个产品绑多个方案）
|
||
4. 建议加"阶梯预览"区块显示该产品当前所有方案的覆盖情况，帮肉眼核对重叠/漏洞
|
||
5. 列表展示：用后端返回的 `peopleRangeText + discountText` 直接显示，不用前端拼
|
||
|
||
### 小程序产品详情页
|
||
1. 读 `earlyBirdLadder` 画阶梯图（3 档示意）
|
||
2. `earlyBirdTip` 作为默认概览展示（如"最低 8 折起"）
|
||
3. 老字段 `earlyBirdText`、`earlyBirdPlanName`、`earlyBirdDiscount` 废弃（值可能为 null 或第 1 档概览），请改读 `earlyBirdLadder[0]`
|
||
|
||
### 小程序下单页
|
||
1. 用户选完人数 + 日期后本地按 `earlyBirdLadder` 匹配：
|
||
```
|
||
match = ladder.find(l => totalPeople >= l.minPeople && (l.maxPeople == null || totalPeople <= l.maxPeople))
|
||
```
|
||
2. 匹配到方案时，提示文案可参考：`"您当前 N 人，命中 '${peopleRangeText} ${discountText}'"`
|
||
3. 可顺带提示"更优档位"：若 `ladder` 里有 `minPeople > totalPeople` 且折扣更大的，提示"满 X 人可享 Y"
|
||
|
||
---
|
||
|
||
## 兼容性
|
||
|
||
- 老数据：全部默认 `discount_type=AMOUNT_TOTAL`，行为不变（整单立减）
|
||
- 老接口：`EarlyBirdPlanSaveReqVO` 新字段全部可选，旧版管理端提交不传也可
|
||
- 老订单：已支付订单不回溯，`order_discount` 持久化的 `discount_amount` 不变
|
||
- 废弃但保留：`earlyBirdText/earlyBirdPlanName/earlyBirdDiscount` 三个老字段继续下发（值按新逻辑计算），下个大版本下架
|