From 3c11072d127a69df40d5e0887f5ad4fb33fb8bed Mon Sep 17 00:00:00 2001 From: wx <2636507191@qq.com> Date: Mon, 20 Apr 2026 17:33:13 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E:=20=E5=B0=8F=E7=A8=8B?= =?UTF-8?q?=E5=BA=8F=E4=BA=A7=E5=93=81=E8=AF=A6=E6=83=85=20earlyBirdLadder?= =?UTF-8?q?=20=E5=A4=9A=E6=A1=A3=20+=20=E8=AE=A2=E5=8D=95=E7=BA=A7?= =?UTF-8?q?=E7=AB=8B=E5=87=8F=E8=AF=AD=E4=B9=89=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...-20_early-bird-order-level-multi-ladder.md | 110 ++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 changelogs/2026-04/2026-04-20_early-bird-order-level-multi-ladder.md diff --git a/changelogs/2026-04/2026-04-20_early-bird-order-level-multi-ladder.md b/changelogs/2026-04/2026-04-20_early-bird-order-level-multi-ladder.md new file mode 100644 index 0000000..a092076 --- /dev/null +++ b/changelogs/2026-04/2026-04-20_early-bird-order-level-multi-ladder.md @@ -0,0 +1,110 @@ +# 早鸟优惠多档 + 订单级立减（小程序产品详情） + +**日期**：2026-04-20 +**PR**：无（纯文档更正，代码语义一直是订单立减） +**影响**：小程序产品详情页 早鸟展示 + +--- + +## 核心结论（给前端的一句话） + +`/mp/product/detail` 的 `earlyBirdLadder` 字段**已经支持「一个产品多档早鸟」**，每档的折扣语义是**订单总立减**（不是每人减），可以直接按阶梯画。 + +--- + +## 业务语义（最重要） + +早鸟优惠 = **订单总立减固定金额**，**不是**每人立减。 + +### 举例 + +- 满 3 人订单立减 **300 元**（订单总价减 300，不论 3 人还是 30 人） +- 满 4 人订单立减 **500 元** + +这在 `earlyBirdLadder` 里是**两个 item**，前端按 `minPeople` 升序画阶梯： + +```jsonc +// GET /mp/product/detail?productId=xxx +{ + "earlyBirdTip": "最低订单总价优惠 300 元（共 2 档早鸟方案）", // 概览，首屏标签用 + "earlyBirdLadder": [ + { + "planId": 1001, + "planName": "满3人早鸟", + "minPeople": 3, + "maxPeople": 3, // 档位上限（含），下一档 4 人以上不归它管 + "peopleRangeText": "3 人", + "discountText": "满 3 人订单总价优惠 300 元", // ⭐ 订单级立减 + "startDate": "2026-04-01", + "endDate": "2026-12-31" + }, + { + "planId": 1002, + "planName": "满4人早鸟", + "minPeople": 4, + "maxPeople": null, // null = 不限上限 + "peopleRangeText": "4 人及以上", + "discountText": "满 4 人订单总价优惠 500 元", + "startDate": "2026-04-01", + "endDate": "2026-12-31" + } + ] +} +``` + +## 字段清单 + +| 字段 | 类型 | 说明 | +|---|---|---| +| `earlyBirdTip` | `String` | 概览文案（无人数上下文），无绑定返 `null` | +| `earlyBirdLadder` | `List` | 阶梯数组，按 `minPeople` 升序，无绑定返 `[]` | +| `earlyBirdLadder[].planId` | `Long` | 早鸟计划 ID | +| `earlyBirdLadder[].planName` | `String` | 计划名（管理端命名，展示可选） | +| `earlyBirdLadder[].minPeople` | `Integer` | 最低人数（含）| +| `earlyBirdLadder[].maxPeople` | `Integer\|null` | 最高人数（含），null 表示不限 | +| `earlyBirdLadder[].peopleRangeText` | `String` | 人数区间文案，如 "3-5 人" / "4 人及以上" | +| `earlyBirdLadder[].discountText` | `String` | **订单总立减**文案，如 "满 3 人订单总价优惠 300 元" | +| `earlyBirdLadder[].startDate` | `LocalDate` | 下单日期窗口起 | +| `earlyBirdLadder[].endDate` | `LocalDate` | 下单日期窗口止 | + +## 前端展示建议 + +### 产品详情 —— 早鸟阶梯卡片 + +``` +🐦 早鸟优惠 最低订单总价优惠 300 元 +┌─────────────────────────────────┐ +│ 3 人 -300 元 │ ← earlyBirdLadder[0] +│ 4 人及以上 -500 元 │ ← earlyBirdLadder[1] +└─────────────────────────────────┘ +生效：2026-04-01 至 2026-12-31 +``` + +- 用 `peopleRangeText` + `discountText` 拼行 +- 如果只想展示金额不展示文案，从 `discountText` 里正则抽数字即可，但直接用 `discountText` 最稳（后端拼好的） + +### 下单前匹配 + +- 下单时按选中人数 `n`，在 `earlyBirdLadder` 里找第一个满足 `minPeople ≤ n ≤ (maxPeople ?? ∞)` 的 item +- 展示"预计优惠 X 元"给用户，X 直接取这一档的金额（不再乘人数） +- 最终折扣以后端订单接口返回的 `OrderDiscount` 为准（前端只做预估展示） + +## 不是（防误读） + +- ❌ 不是"每人立减 X 元"—— 之前 Entity 注释里 `"优惠金额（元/人）"` 是过期文档，实际金额计算在 `OrderFinanceService.tryApplyEarlyBirdDiscount` 里**没有乘人数** +- ❌ 不是"订单总价按折扣比例打折"—— 是固定金额直减 +- ❌ 不是"每个人都减 X 元"—— 订单总价减一次 X 元 + +## 单选 / 多档的关系 + +- 一个产品可以绑定**多个**早鸟计划（通过 `product_early_bird_plan` 关联表） +- 每个计划一档，前端合并展示成阶梯 +- 运营侧在管理端配置：每档的 `minPeople` + `discountAmount` + 生效日期 + +## 已知注释问题（后端会修，不影响接口） + +- `EarlyBirdPlan.java:25` 注释 "元/人" 会改成 "订单总立减金额（元）" +- `EarlyBirdPlanDTO.java:25` 注释会明确 "订单优惠金额" +- `EarlyBirdLadderItemDTO.java:31` 示例会从 "每人立减 100 元" 改为 "订单总价优惠 300 元" + +前端**不用等这个 PR**，接口响应结构不变，语义本来就是订单立减。