# 多店铺阶梯满减活动系统设计方案

> **版本**: v1.2.1  
> **日期**: 2026-06-23  
> **作者**: 系统架构组  
> **适用范围**: ylrz_his_scrm 电商系统（基于若依框架 + Spring Boot + Vue2/Element UI + uni-app APP/小程序）  
> **修订说明**: v1.2.1 管理端后台 CRUD 已实现；v1.2 新增 APP/小程序方案；v1.1 对齐 hisStore 商城模块

---

## 实现进度追踪（v1.2.1）

| 模块 | 状态 | 路径 / 说明 |
|------|:----:|-------------|
| SQL 建表 + 订单字段 + 菜单 | ✅ 脚本已提供 | `docs/sql/fs_store_promotion_init.sql`（需 DBA 执行；菜单 `parent_id` 需调整） |
| 活动 Domain / DTO / VO | ✅ 已完成 | `fs-service/.../hisStore/domain|dto|vo/` |
| 活动 Mapper + XML | ✅ 已完成 | `fs-service/.../mapper/hisStore/FsStorePromotion*.xml` |
| 管理端 Service | ✅ 已完成 | `IFsStorePromotionService` / `FsStorePromotionServiceImpl` |
| 管理端 Controller | ✅ 已完成 | `fs-admin/.../FsStorePromotionController.java` |
| 管理端 API | ✅ 已完成 | `src/api/hisStore/storePromotion.js` |
| 管理端列表 + 新增/编辑/详情 | ✅ 已完成 | `src/views/hisStore/storePromotion/index.vue`（Dialog 模式） |
| 用户端 settlement 查询接口 | ⬜ 未做 | `POST /store/app/storeOrder/promotion/list` 等（见 5.2.1） |
| 订单 computed/create 满减 | ⬜ 未做 | `FsStoreOrderScrmServiceImpl` |
| APP / 小程序结算页 | ⬜ 未做 | 见 1.4 节 |
| usage 支付联动 / 定时 Job / Redis 缓存 | ⬜ 未做 | 见第 6 章 |

**图例**：✅ 已完成　⬜ 未做

---

## 0. 评审结论与实施计划

### 0.1 文档评审结论（v1.0 → v1.1 优化点）

| 类别 | 原方案问题 | 优化方向 |
|------|-----------|---------|
| 表名/关联 | 使用了 `fs_his_store`、`fs_store_order` 等不存在或不准确的表名 | 统一为 `fs_store_scrm`、`fs_store_order_scrm`、`fs_store_product_scrm`、`fs_store_product_category_scrm` |
| 用户端接口 | 新增 `/api/store/promotion/compute`、`/api/store/order/submit` | **扩展现有** `FsStoreOrderScrmServiceImpl.computedOrder/createOrder`，路径沿用 `/store/app/storeOrder/computed`、`/create` |
| 多店铺 | 未覆盖多店铺结算 | 同步扩展 `computedMultiStore` / `createMultiStore`，按 `storeId` 维度匹配活动 |
| 优惠计算基数 | 未说明按整单还是按适用商品 | 阶梯门槛按**活动适用商品小计**计算，非适用商品不计入门槛 |
| 参与次数 | 下单即写入 usage，未区分支付状态 | usage 增加 `usage_status`，仅**支付成功**计次；未支付取消/超时回滚 |
| 状态字段 | `status` + `manual_status` 混用，前端草稿判断有逻辑错误 | 明确「展示态」由后端统一计算；草稿以 `manual_status IS NULL` 为准 |
| 时间边界 | 文档前后 `>=` / `<` 描述不一致 | 统一：**开始含、结束含**，SQL 使用 `start_time <= NOW() AND end_time >= NOW()` |
| 活动冲突 | 仅按店铺+时间冲突 | 增加**适用范围重叠**判断（同店铺、时间重叠、scope 有交集才冲突） |
| 缓存工具 | 示例使用 `RedisTemplate` | 与现有代码一致，使用项目内 `redisCache`（`RedisCache`）+ 可选 Redisson 锁 |
| 店铺下拉 | 新增 `/store/storePromotion/storeList` | 复用现有 `/store/his/store/listOption`（前端 `@/api/hisStore/store.js`） |

### 0.2 分步实施计划（仅方案，不含代码）

| 步骤 | 内容 | 模块 | 产出 |
|:--:|------|------|------|
| 1 | 执行 DDL：4 张活动表 + `fs_store_order_scrm` 扩展字段 | DBA / SQL 脚本 | ✅ 脚本见 `docs/sql/fs_store_promotion_init.sql` |
| 2 | 创建 Domain / Mapper / XML / Service | `fs-service` | ✅ 已完成 |
| 3 | 管理端 Controller + 权限标识 | `fs-admin` | ✅ `FsStorePromotionController` |
| 4 | 管理端前端（列表 + Dialog 新增编辑 + 详情） | `ylrz_his_scrm_adminUI` | ✅ `views/hisStore/storePromotion/index.vue` |
| 5 | 扩展订单计算 DTO/Param | `fs-service` | `FsStoreOrderComputedParam`、`FsStoreOrderComputeDTO`、`FsStoreOrderCreateParam` 增加满减字段 |
| 6 | 接入 `computedOrder` / `createOrder` | `fs-service` | 在积分之后、优惠券之前追加满减计算与校验 |
| 7 | 接入多店铺计算/下单 | `fs-service` | `computedOrderMultiStore` / `createOrderMultiStore` 按店铺独立匹配活动 |
| 8 | **新增结算活动查询接口** | `fs-user-app` | `StoreOrderScrmController` 增加 `/promotion/list`、`/promotion/listMultiStore` |
| 9 | **APP / 小程序结算页改造** | 用户端工程（uni-app 等） | 活动列表展示、选中/切换、与 computed/create 联动 |
| 10 | 参与记录与订单取消联动 | `fs-service` | 支付成功确认 usage；取消/超时订单释放次数 |
| 11 | 定时兜底任务 | `fs-quartz` 或 `@Scheduled` | 每分钟批量将过期活动 `status` 置为 3 |
| 12 | 菜单 / 路由 / 字典配置 | adminUI + 系统管理 | ✅ SQL 脚本含菜单；路由 component=`hisStore/storePromotion/index` |
| 13 | 联调与边界测试 | QA | 时间临界点、叠加优惠券、多店铺、限次、手动关停、结算页选活动 |

### 0.3 与现有商城链路集成要点

```
购物车确认 → confirmOrder / confirmOrderMultiStore
     ↓  返回 orderKey、carts、address
结算页进入 → POST /store/app/storeOrder/promotion/list（或 listMultiStore）★新增
     ↓  返回当前店铺可参与的满减活动列表 + 推荐活动 + 档位说明
     ↓  用户选择活动（或采用推荐活动；可不选=不参与满减）
结算页计算 → POST /store/app/storeOrder/computed（或 computedMultiStore）
     ↓  传 promotionActivityId + 现有 couponUserId / useIntegral
     ↓  查即验证 → 计算满减 → 返回 payPrice、promotionDiscountAmount 等
提交订单 → POST /store/app/storeOrder/create（或 createMultiStore）
     ↓  服务端重算 → 写 fs_store_order_scrm.promotion_* → usage 待支付
```

**优惠叠加顺序（建议，与现有积分/券逻辑一致）**：

1. 商品原价合计 → 2. 积分抵扣 → 3. 阶梯满减 → 4. 优惠券（若 `is_stackable=1` 且券可用）

---

## 目录

0. [评审结论与实施计划](#0-评审结论与实施计划)
1. [管理后台页面设计（重点）](#1-管理后台页面设计)
1.4. [用户端结算页设计（APP / 小程序）](#14-用户端结算页设计app--小程序)
2. [活动时效性生效与失效方案（重点）](#2-活动时效性生效与失效方案)
3. [数据库设计](#3-数据库设计)
4. [核心业务逻辑](#4-核心业务逻辑)
5. [接口设计](#5-接口设计)
6. [非功能性设计](#6-非功能性设计)

---

## 1. 管理后台页面设计

> 管理后台模块路径：`D:\hdProject\ylrz_his_scrm_java\fs-admin`  
> 前端代码路径：`D:\web\cs\ylrz_his_scrm_adminUI\src\views\hisStore\storePromotion\`

### 1.1 活动列表页

页面路由：`/hisStore/storePromotion/index`

#### 1.1.1 页面布局

采用若依框架标准 CRUD 页面布局（与现有 `storeCoupon` 模块一致）：
- 顶部：查询条件区域（可折叠 `showSearch`）
- 中部：功能按钮栏 + 表格
- 底部：分页组件

#### 1.1.2 筛选条件

| 筛选字段 | 控件类型 | 说明 |
|---------|---------|------|
| 活动名称 | `el-input` | 支持模糊搜索 |
| 店铺 | `el-select` | 下拉选择，默认全部（当前登录用户有权限的店铺） |
| 活动状态 | `el-select` | 选项：全部/未开始/进行中/已结束/手动关闭/草稿 |
| 生效时间范围 | `el-date-picker` (daterange) | 按 `start_time ~ end_time` 范围筛选 |

#### 1.1.3 列表展示字段

| 字段 | 宽度 | 说明 |
|-----|------|------|
| 活动ID | 80 | 主键 |
| 活动名称 | 200 | 活动标题，点击可跳转详情 |
| 店铺名称 | 120 | `store_name` |
| 活动时间 | 240 | 格式：`2026-06-01 00:00 ~ 2026-07-01 23:59` |
| 阶梯档数 | 80 | 如"3档" |
| 上不封顶 | 80 | 显示"是/否" Tag |
| 可叠加优惠券 | 100 | 显示"是/否" Tag |
| 适用范围 | 120 | 全场通用 / 指定分类(N) / 指定商品(N) |
| 每人限次 | 80 | 如"1次" / "不限" |
| 活动状态 | 100 | 见状态 Tag 颜色说明 |
| 操作 | 240 | 编辑 / 启用/停用 / 删除 / 查看详情 |

#### 1.1.4 状态 Tag 颜色规范

| 状态值 | 显示文字 | Tag 颜色 | 说明 |
|-------|---------|----------|------|
| 0 | 草稿 | `info`（灰） | 刚创建，尚未手动启用 |
| 1 | 未开始 | `warning`（橙） | 已启用但未到开始时间 |
| 2 | 进行中 | `success`（绿） | 当前时间在 [start, end] 内且是启用态 |
| 3 | 已结束 | `info`（灰） | 已过结束时间 |
| 4 | 已关闭 | `danger`（红） | 被手动关闭 |

#### 1.1.5 操作按钮逻辑

| 按钮 | 草稿(0) | 未开始(1) | 进行中(2) | 已结束(3) | 已关闭(4) | 
|------|---------|-----------|-----------|-----------|-----------|
| 编辑 | 显示 | 显示 | 显示（仅修改部分字段） | 隐藏 | 隐藏 |
| 启用 | 显示 | 隐藏 | 隐藏 | 隐藏 | 显示 |
| 停用 | 隐藏 | 显示 | 显示 | 隐藏 | 隐藏 |
| 删除 | 显示 | 隐藏 | 隐藏 | 显示 | 显示 |
| 查看详情 | 显示 | 显示 | 显示 | 显示 | 显示 |

- **编辑按钮限制**：当状态为"进行中"时，可编辑但限制只能修改"活动名称"、"结束时间"（仅可延后）、"上不封顶"、"可叠加优惠券"、"每人限次"等不会引起歧义的字段。阶梯档位、适用范围不可修改。
- **删除按钮**：仅草稿/已结束/已关闭状态可删除，且使用逻辑删除（`is_del = 1`）。

#### 1.1.6 前端状态判断逻辑（核心）

```javascript
// 前端计算展示状态的函数（需前后端双重保障）
function computeDisplayStatus(record) {
  const now = Date.now();
  const startTime = new Date(record.startTime).getTime();
  const endTime = new Date(record.endTime).getTime();
  
  if (record.manualStatus === 0) {
    // 手动关闭优先
    return { status: 4, label: '已关闭', tag: 'danger' };
  }
  
  if (record.manualStatus === null || record.manualStatus === undefined) {
    // 从未被手动操作过（刚创建）
    return { status: 0, label: '草稿', tag: 'info' };
  }
  
  if (now < startTime) {
    return { status: 1, label: '未开始', tag: 'warning' };
  }
  
  if (now >= startTime && now <= endTime) {
    return { status: 2, label: '进行中', tag: 'success' };
  }
  
  if (now > endTime) {
    return { status: 3, label: '已结束', tag: 'info' };
  }
}
```

---

### 1.2 新增/编辑活动页

页面路由：`/hisStore/storePromotion/add`、`/hisStore/storePromotion/edit/:id`

#### 1.2.1 表单布局（总览）

采用 Element UI 的 `el-form` 组件，分三个卡片区域（`el-card`）：

```
┌──────────────────────────────────────────┐
│  【基本信息】                              │
│  活动名称: [____________]                  │
│  所属店铺: [下拉选择]     活动状态: 草稿    │
│  开始时间: [日期时间选择器]                  │
│  结束时间: [日期时间选择器]                  │
├──────────────────────────────────────────┤
│  【满减阶梯档位】           [+ 添加一档]     │
│  ┌─────────────────────────────────────┐ │
│  │ 第1档 │ 满___元 │ 减___元 │  [删除]   │ │
│  │ 第2档 │ 满___元 │ 减___元 │  [删除]   │ │
│  │ 第3档 │ 满___元 │ 减___元 │  [删除]   │ │
│  └─────────────────────────────────────┘ │
│  上不封顶: [Switch 开关]                    │
├──────────────────────────────────────────┤
│  【适用范围 & 规则】                        │
│  适用类型: [全场通用 / 指定商品分类 / 指定商品] │
│  指定分类: [级联选择器]（仅在"指定商品分类"显示）│
│  指定商品: [商品选择弹窗]（仅在"指定商品"显示）  │
│  可叠加优惠券: [Switch 开关]                 │
│  每人限参与次数: [数字输入框] 次（0=不限）     │
└──────────────────────────────────────────┘
```

#### 1.2.2 详细字段说明

| 字段名 | 控件类型 | 必填 | 校验规则 | 说明 |
|--------|---------|------|---------|------|
| 活动名称 | `el-input` | 是 | 1~50字符 | 活动标题 |
| 所属店铺 | `el-select` | 是 | 下拉必选 | 复用 `/store/his/store/listOption`（`@/api/hisStore/store.js`） |
| 开始时间 | `el-date-picker` (datetime) | 是 | 不能早于当前时间 | 精确到秒 |
| 结束时间 | `el-date-picker` (datetime) | 是 | 必须 > 开始时间 | 精确到秒 |
| 阶梯档位 | 动态表格 | 是 | 至少1档，最多10档 | 见下方详细交互说明 |
| 上不封顶 | `el-switch` | — | 默认为否 | 开启后最高档之上继续按最后一档比例减 |
| 适用类型 | `el-radio-group` | 是 | — | 1-全场通用, 2-指定分类, 3-指定商品 |
| 指定分类ID列表 | `el-cascader` | 条件必填 | 适用类型=2时必填 | 多选，拉取商品分类树 |
| 指定商品ID列表 | 自定义商品选择器 | 条件必填 | 适用类型=3时必填 | 多选，弹窗选择商品 |
| 可叠加优惠券 | `el-switch` | — | 默认为是 | 是否可与优惠券同时使用 |
| 每人限参与次数 | `el-input-number` | — | `min=0`, 0=不限 | 同一用户最多参与次数 |

#### 1.2.3 阶梯档位交互设计

**添加一档**：
- 点击"添加一档"按钮，在档位列表末尾插入一个新的空档位行
- 新行的"门槛金额"默认值为上一档门槛金额 + 100（若为第一档则默认100）
- 添加时前端先做即时校验：当前已有档位数量 < 10

**删除一档**：
- 每行右侧有"删除"按钮
- 删除时校验：删除后至少保留1档，否则给出提示"至少保留一档"
- 删除不需要二次确认

**前端即时校验规则**：
```javascript
const tierRules = {
  // 1. 门槛金额必须递增
  thresholdAscending: (tiers) => {
    for (let i = 1; i < tiers.length; i++) {
      if (tiers[i].thresholdAmount <= tiers[i-1].thresholdAmount) {
        return `第${i+1}档门槛金额必须大于第${i}档`;
      }
    }
    return true;
  },
  // 2. 减扣金额必须递增（满减逻辑：门槛越高优惠越多）
  discountAscending: (tiers) => {
    for (let i = 1; i < tiers.length; i++) {
      if (tiers[i].discountAmount <= tiers[i-1].discountAmount) {
        return `第${i+1}档减扣金额必须大于第${i}档`;
      }
    }
    return true;
  },
  // 3. 减扣金额不能大于门槛金额（防止负数支付）
  discountLessThanThreshold: (tiers) => {
    for (let i = 0; i < tiers.length; i++) {
      if (tiers[i].discountAmount >= tiers[i].thresholdAmount) {
        return `第${i+1}档减扣金额不能大于等于门槛金额`;
      }
    }
    return true;
  }
};
```

#### 1.2.4 提交前完整校验清单

| 序号 | 校验点 | 规则 |
|------|-------|------|
| 1 | 活动名称 | 非空，1~50字符 |
| 2 | 店铺 | 必选 |
| 3 | 开始时间 | 必填，编辑时若已生效则不可修改 |
| 4 | 结束时间 | 必填，必须 > 开始时间 |
| 5 | 档位数量 | 1~10档 |
| 6 | 门槛递增 | 每档门槛 > 前一档 |
| 7 | 优惠递增 | 每档减扣 >= 前一档 |
| 8 | 优惠 < 门槛 | 每档减扣 < 对应门槛 |
| 9 | 适用类型 | 必选，选2/3时必须选具体分类/商品 |
| 10 | 限次 | >= 0 整数 |

---

### 1.3 状态展示与操作逻辑

#### 1.3.1 状态定义

| 状态值 | 状态名称 | 定义 | 数据库中 `status` + `manual_status` 组合 |
|--------|---------|------|------------------------------------------|
| 0 | 草稿 | 创建后从未手动启用 | `status = 0, manual_status = NULL` |
| 1 | 未开始 | 已启用，未到开始时间 | `manual_status = 1` 且 `now < start_time` |
| 2 | 进行中 | 已启用且在有效期内 | `manual_status = 1` 且 `start_time <= now <= end_time` |
| 3 | 已结束 | 已过结束时间 | `manual_status = 1` 且 `now > end_time`，或 `status = 3`（定时/查即验证写入） |
| 4 | 已关闭 | 被手动关闭 | `manual_status = 0`（`status` 保持原值，展示态优先于时间） |

> **说明**：列表/详情展示的 5 种状态均为**计算态**（displayStatus），数据库仅持久化 `status`（0草稿/1启用/3已结束）与 `manual_status`（NULL/0/1），避免前后端状态不一致。

#### 1.3.2 启用/停用操作逻辑

**点击"启用"按钮**（状态为草稿或已关闭时显示）：

```
用户点击"启用"
  ↓
前端校验：是否在活动时间范围内？
  ├─ 在范围内 → 调用后端启用接口 → manual_status=1, status=1 → 状态变为"进行中"
  ├─ 未到开始时间 → 调用后端启用接口 → manual_status=1, status=1 → 状态变为"未开始"
  └─ 已过结束时间 → 阻止操作，提示"活动已过期，无法启用"
```

**点击"停用"按钮**（状态为未开始或进行中时显示）：

```
用户点击"停用"
  ↓
弹窗二次确认："确认停用该活动？停用后用户将无法参与该活动。"
  ↓ 确认
调用后端停用接口 → manual_status=0 → 状态变为"已关闭"
```

#### 1.3.3 后端状态接口

> 在现有 Controller 基础上新增两个方法，详见第5节接口设计。

---

### 1.4 用户端结算页设计（APP / 小程序）

> **后端模块**：`D:\hdProject\ylrz_his_scrm_java\fs-user-app\src\main\java\com\fs\app\controller\store\StoreOrderScrmController`  
> **前端模块**：用户端 uni-app 工程（APP 与小程序共用结算页，页面路径以各项目为准，常见如 `pages/store/order/confirm`）

#### 1.4.1 改造范围

| 页面 | 改造内容 |
|------|---------|
| 单店铺结算页 | 新增「满减活动」区块：活动列表、档位说明、选中态、优惠金额预览 |
| 多店铺结算页 | 按店铺 Tab/卡片分组展示各自可用活动，每店独立 `promotionActivityId` |
| 金额明细区 | 增加一行「满减优惠 -¥XX.XX」，置于积分与优惠券之间 |
| 提交订单 | `create` / `createMultiStore` 携带 `promotionActivityId`、`promotionTierId` |

**不在本次改造**：商品详情页活动标签（可选二期）、购物车页（仍走 confirm → 结算页查活动）。

#### 1.4.2 页面布局（单店铺）

```
┌─────────────────────────────────────┐
│  收货地址                            │
├─────────────────────────────────────┤
│  商品列表（现有）                     │
├─────────────────────────────────────┤
│  【满减活动】              查看规则 > │  ← 新增区块
│  ○ 不参与满减                        │
│  ● 618年中大促  已满399减80           │  ← 默认选中推荐活动
│     再购 XX 元可减 YY 元（下一档提示）  │
│  ○ 品类专享满减  满199减30（不可用灰显）│
│     原因：未达门槛 / 已达参与上限       │
├─────────────────────────────────────┤
│  优惠券（现有）                       │
│  积分抵扣（现有）                     │
├─────────────────────────────────────┤
│  商品金额    ¥498.00                 │
│  运费        ¥0.00                   │
│  积分抵扣    -¥0.00                  │
│  满减优惠    -¥80.00    ← 新增       │
│  优惠券      -¥0.00                  │
│  ─────────────────                   │
│  实付        ¥418.00                 │
└─────────────────────────────────────┘
        [ 提交订单 ]
```

#### 1.4.3 交互流程

```
onLoad（携带 confirm 返回的 orderKey）
  ↓
调用 POST /store/app/storeOrder/promotion/list
  ↓ 展示活动列表，默认选中 recommendedActivityId（优惠最大且可用）
用户切换活动 / 选「不参与满减」
  ↓
调用 POST /store/app/storeOrder/computed（带 promotionActivityId，null=不参与）
  ↓ 刷新金额明细（payPrice、promotionDiscountAmount）
用户改地址 / 优惠券 / 积分
  ↓ 重新 computed（保持当前 promotionActivityId）
  ↓ 若 is_stackable=0 且已选券 → 提示互斥，禁用活动或清券（与后端一致）
点击提交订单
  ↓
POST /store/app/storeOrder/create（带 promotionActivityId + promotionTierId）
```

**多店铺**：进入页后调用 `promotion/listMultiStore`，每个 `storeId` 渲染一组活动单选；`computedMultiStore` / `createMultiStore` 按店传不同 `promotionActivityId`（扩展 group 参数，见 5.2.4）。

#### 1.4.4 前端状态与校验

| 场景 | 处理 |
|------|------|
| 无可用活动 | 隐藏满减区块或展示「暂无满减活动」 |
| 活动不可用（`enabled=false`） | 灰显 + 展示 `disabledReason` |
| 切换活动 | 防抖 300ms 后调 `computed` |
| 活动列表为空但 computed 有推荐 | 以 list 接口为准，不前端臆造活动 |
| orderKey 过期 | 与现有逻辑一致，提示返回购物车 |

#### 1.4.5 前端数据结构（页面 data）

```javascript
data() {
  return {
    orderKey: '',
    storeId: null,
    promotionList: [],           // list 接口返回
    selectedPromotionId: null,   // null = 不参与
    recommendedPromotionId: null,
    promotionDiscountAmount: 0,
    promotionTitle: '',
    promotionRemainCount: null,
    computeLoading: false
  }
}
```

#### 1.4.6 APP 与小程序差异

| 项 | APP | 小程序 |
|----|-----|--------|
| 网络请求 | 同一套 API 封装 | 同一套 API 封装 |
| 活动规则弹窗 | 可用原生 Modal / 底部 Sheet | 建议 `uni-popup` 展示档位表 |
| 登录 | `@Login` Token | `@Login` Token |
| 多店铺 | 与 APP 一致 | 与 APP 一致 |

---

## 2. 活动时效性生效与失效方案

### 2.1 活动生命周期状态机

```
                    ┌──────────┐
          创建       │   草稿    │
       ───────────▶  │ (status=0, │
                     │ manual=NULL)│
                    └─────┬─────┘
                          │ 管理员点击"启用"
                          ▼
              ┌───────────────────────┐
              │      是否在时间范围内？    │
              └───────┬───────┬───────┘
                      │       │
           now < start│       │ now >= start && now <= end
                      ▼       ▼
              ┌─────────┐  ┌───────────┐
              │ 未开始    │  │  进行中    │
              │(status=1,│  │(status=1, │
              │manual=1) │  │manual=1)  │
              └────┬────┘  └──┬──┬───┬─┘
                   │           │  │   │
     时间到 start_time 自动    │  │   │ 时间到 end_time 自动
                   │           │  │   │
                   ▼           │  │   ▼
              ┌───────────┐    │  │ ┌──────────┐
              │  进行中    │◀───┘  │ │ 已结束    │
              └───────────┘       │ │(status=3,│
                                  │ │manual=1) │
                                  │ └──────────┘
                                  │
                          管理员点击"停用"
                                  │
                                  ▼
                          ┌────────────┐
                          │  已关闭     │
                          │(status=1,  │
                          │manual=0)   │
                          └──────┬─────┘
                                 │
                         管理员点击"启用"
                         且时间仍在有效范围内
                                 │
                                 ▼
                          ┌───────────┐
                          │  进行中    │
                          └───────────┘
```

**状态流转说明**：

| 当前状态 | 触发事件 | 目标状态 | 条件 |
|---------|---------|---------|------|
| 草稿 | 管理员启用 | 未开始/进行中 | 根据当前时间判断 |
| 未开始 | 时间到达 start_time | 进行中 | `manual_status=1` |
| 进行中 | 时间超过 end_time | 已结束 | `manual_status=1` |
| 进行中 | 管理员停用 | 已关闭 | — |
| 未开始 | 管理员停用 | 已关闭 | — |
| 已关闭 | 管理员启用 | 未开始/进行中 | 必须在 [start_time, end_time] 内或之前 |
| 已结束 | (终态) | — | 不可再操作 |

---

### 2.2 自动生效/失效触发机制（方案对比与推荐）

#### 方案一：定时任务轮询扫描（如 Spring `@Scheduled` 或 XXL-JOB）

**机制**：每分钟执行一次定时任务，扫描 `status=1 AND manual_status=1` 的活动，根据时间更新状态。

**优点**：
- 实现简单，与现有 `fs-quartz` 模块可直接集成
- 不依赖额外中间件特性
- 可批量处理，适合大批量活动

**缺点**：
- 有延迟（最小粒度为分钟级），无法做到秒级精确
- 无活动时也执行，浪费资源
- 高并发时可能存在竞争（需加锁）

#### 方案二：基于 Redis 过期事件 + Keyspace Notifications

**机制**：活动启用时，计算 `end_time - now` 秒数，设置 Redis key 的过期时间。当 key 过期时，通过 Redis 的 `__keyevent@*__:expired` 通知，触发状态更新。

**优点**：
- 秒级精度
- 无需轮询，资源消耗小
- 天然分布式友好

**缺点**：
- 依赖 Redis Keyspace Notifications（需开启 `notify-keyspace-events Ex`）
- Redis 过期事件可能丢失（Redis 重启、主从切换时）
- 部署复杂度较高

#### 方案三（推荐）：**查即验证 + 定时兜底** — 实时惰性校验

**机制**：

1. **前置拦截（核心）**：每次用户请求（浏览活动详情 / 下单计算优惠 / 提交订单）时，在 Service 层通过 AOP 或工具方法执行**时间窗口校验**，若当前时间已超过结束时间，**即时更新活动状态**为已结束，并返回无效。

2. **缓存标记**：下发到用户端的活动数据中，始终携带 `start_time` 和 `end_time`。前端在发起下单请求前，本地先做时间校验，早于到达后端就拦截。

3. **定时兜底（每分钟）**：通过 XXL-JOB / `@Scheduled` 定时任务全量扫描，处理那些长期无人访问的"僵尸活动"，确保管理端列表准时刷新状态。

**方案对比表**：

| 维度 | 方案一 纯定时任务 | 方案二 Redis过期事件 | 方案三 查即验证+定时兜底 |
|------|:--:|:--:|:--:|
| 实时性 | 分钟级 | 秒级 | **秒级**（请求触发） |
| 可靠性 | 高 | 中（事件可能丢失） | **高**（双重保障） |
| 实现复杂度 | 低 | 高 | **中** |
| 资源消耗 | 持续扫描 | 低 | **低** |
| 部署依赖 | 无 | Redis Keyspace | **Redis（通用缓存）** |

**推荐结论**：采用 **方案三（查即验证 + 定时兜底）**，核心原因：
- 用户明确要求"购买或查看详情时过期就立即更新状态"——该方案天然满足
- 不依赖 Redis 过期事件，降低基础设施要求
- 双重机制保障可靠性和实时性

---

### 2.3 时间边界准确性保障

#### 下单瞬间的防纠纷机制

**问题**：用户在 `end_time = 2026-06-23 23:59:59` 的 23:59:58 秒下单，后端处理时已经过了 23:59:59，活动已结束，用户看到的价格和实际扣款不一致。

**解决方案——数据库乐观锁 + 二次时间校验**：

```
下单流程中的关键步骤：
1. 用户点击"提交订单"
2. 后端查询当前适用活动列表（调用 computeActivity 接口）
   → 此时记录活动的 start_time / end_time
3. 后端计算优惠金额，返回给前端确认
4. 用户确认支付，后端创建订单
   → 扣减库存前，再次校验活动时间：
     SELECT * FROM fs_store_promotion_activity 
     WHERE id = #{activityId} 
       AND manual_status = 1 
       AND start_time <= NOW() 
       AND end_time >= NOW()
     → 若查不到记录，说明活动已失效
     → 若查到记录，使用版本号(version)做乐观锁更新参与次数
     
5. 若活动失效 → 回滚订单创建，提示用户"活动已结束，请重新下单"
6. 若活动有效 → 正常完成订单
```

**时间比较精度**：统一使用 MySQL `NOW()` 或 Java `LocalDateTime.now()`，精度为**秒级**。**开始时间含边界**（`start_time <= NOW()`），**结束时间含边界**（`end_time >= NOW()`），与现有优惠券、订单超时逻辑保持一致。

---

### 2.4 手动"启用/关闭"与时间范围的关系

#### 规则矩阵

| `manual_status` | 时间条件 | 最终生效状态 | 说明 |
|:--:|------|:--:|------|
| `NULL` | 任意 | **草稿** | 从未操作过 |
| `1` | `now < start_time` | **未开始** | 等待生效 |
| `1` | `start_time <= now <= end_time` | **进行中** | 正常生效 |
| `1` | `now > end_time` | **已结束** | 自动失效 |
| `0` | 任意 | **已关闭** | 手动关闭优先，时间条件无效 |

#### 核心原则

1. **手动关闭优先级最高**：`manual_status = 0` 时，无论时间是否在有效期内，活动均不生效。
2. **手动开启必须在时间范围内**：`manual_status = 1` 且 `now <= end_time` 才有效；若 `now > end_time`，即使 `manual_status = 1` 也视为已结束。
3. **启用/停用操作应校验时间冲突**：
   - 启用时如果已超过结束时间 → 拒绝操作
   - 停用时不需校验时间，直接关闭生效

#### 后端校验代码示例逻辑

```java
// 启用活动接口伪代码
public void enableActivity(Long activityId) {
    FsStorePromotionActivity activity = getById(activityId);
    
    // 校验：已超过结束时间的活动不允许启用
    if (activity.getEndTime().isBefore(LocalDateTime.now())) {
        throw new ServiceException("活动已过期，无法启用");
    }
    
    // 校验：同一店铺+同一时间不允许有多个启用状态且范围重叠的活动
    checkTimeConflict(activity);
    
    activity.setManualStatus(1);
    // status 由查询时动态计算，此处可不设置
    updateById(activity);
    
    // 缓存失效（如有）
    redisTemplate.delete("promotion:store:" + activity.getStoreId());
}
```

---

### 2.5 数据库层时效控制关键设计

#### 关键字段

| 字段 | 类型 | 作用 |
|------|------|------|
| `start_time` | `datetime` | 活动生效开始时间 |
| `end_time` | `datetime` | 活动生效结束时间 |
| `status` | `tinyint` | 存储态状态（0草稿/1启用/3已结束），辅助查询 |
| `manual_status` | `tinyint` | 手动开关（NULL未操作/1启用/0关闭） |
| `version` | `int` | 乐观锁版本号，用于并发控制 |

#### 状态查询 SQL（核心）

```sql
-- 查询当前时刻生效的活动（供用户端使用）
SELECT * FROM fs_store_promotion_activity
WHERE is_del = 0
  AND manual_status = 1          -- 手动启用
  AND status IN (1, 3)           -- 仅启用和已结束（已结束由时间二次过滤）
  AND start_time <= NOW()        -- 已到开始时间
  AND end_time >= NOW()          -- 未到结束时间
  AND store_id = #{storeId};
```

#### 状态更新策略

1. **定时任务**（每分钟）：
```sql
UPDATE fs_store_promotion_activity 
SET status = 3, update_time = NOW() 
WHERE status = 1 AND manual_status = 1 AND end_time < NOW();
```

2. **请求触发更新**（查即验证）：
```sql
-- 查询单个活动时，附带时间校验
SELECT * FROM fs_store_promotion_activity WHERE id = #{id};
-- 若 end_time < NOW() 且 status != 3，则执行：
UPDATE fs_store_promotion_activity SET status = 3, update_time = NOW() WHERE id = #{id} AND status = 1;
```

---

## 3. 数据库设计

### 3.1 活动主表 `fs_store_promotion_activity`

```sql
CREATE TABLE `fs_store_promotion_activity` (
  `id` BIGINT(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `title` VARCHAR(100) NOT NULL COMMENT '活动名称',
  `store_id` BIGINT(20) NOT NULL COMMENT '店铺ID',
  `start_time` DATETIME NOT NULL COMMENT '活动开始时间',
  `end_time` DATETIME NOT NULL COMMENT '活动结束时间',
  `scope_type` TINYINT(2) NOT NULL DEFAULT 1 COMMENT '适用范围类型：1全场通用 2指定分类 3指定商品',
  `is_stackable` TINYINT(1) NOT NULL DEFAULT 1 COMMENT '是否可叠加优惠券：0否 1是',
  `is_capped` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否上不封顶：0否(仅命中最高档) 1是(超出最高档按最后一档循环减)',
  `limit_per_user` INT(11) NOT NULL DEFAULT 0 COMMENT '每人限参与次数，0=不限',
  `status` TINYINT(2) NOT NULL DEFAULT 0 COMMENT '状态：0草稿 1启用 3已结束（★时效关键字段）',
  `manual_status` TINYINT(1) DEFAULT NULL COMMENT '手动开关：NULL从未操作 1启用 0关闭（★时效关键字段，优先级最高）',
  `version` INT(11) NOT NULL DEFAULT 0 COMMENT '乐观锁版本号（★并发控制字段）',
  `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
  `is_del` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '逻辑删除：0正常 1删除',
  `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建者',
  `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新者',
  `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  KEY `idx_store_id` (`store_id`),
  KEY `idx_status_time` (`status`, `manual_status`, `start_time`, `end_time`),
  KEY `idx_store_status` (`store_id`, `status`, `manual_status`, `is_del`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='店铺阶梯满减活动主表';
```

**时效/状态相关字段标注**：
- `start_time`、`end_time`：时间核心字段
- `status`：辅助状态存储，加速列表查询
- `manual_status`：手动开关，决定性字段
- `version`：并发控制

### 3.2 满减档位表 `fs_store_promotion_tier`

```sql
CREATE TABLE `fs_store_promotion_tier` (
  `id` BIGINT(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `activity_id` BIGINT(20) NOT NULL COMMENT '活动ID，关联fs_store_promotion_activity.id',
  `sort_order` INT(11) NOT NULL DEFAULT 1 COMMENT '档位序号：1,2,3...',
  `threshold_amount` DECIMAL(10,2) NOT NULL COMMENT '门槛金额（元）',
  `discount_amount` DECIMAL(10,2) NOT NULL COMMENT '减扣金额（元）',
  `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  KEY `idx_activity_id` (`activity_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='阶梯满减档位表';
```

### 3.3 适用范围表 `fs_store_promotion_scope`

```sql
CREATE TABLE `fs_store_promotion_scope` (
  `id` BIGINT(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `activity_id` BIGINT(20) NOT NULL COMMENT '活动ID',
  `scope_type` TINYINT(2) NOT NULL COMMENT '范围类型：2商品分类 3指定商品（与主表scope_type对应）',
  `target_id` BIGINT(20) NOT NULL COMMENT '目标ID（分类ID或商品ID）',
  `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  PRIMARY KEY (`id`),
  KEY `idx_activity_id` (`activity_id`),
  KEY `idx_target` (`scope_type`, `target_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='活动适用范围明细表';
```

**说明**：
- 当 `scope_type = 1`（全场通用）时，此表无记录
- 当 `scope_type = 2`（指定分类）时，`target_id` 存储分类ID
- 当 `scope_type = 3`（指定商品）时，`target_id` 存储商品ID

### 3.4 用户参与记录表 `fs_store_promotion_usage`

```sql
CREATE TABLE `fs_store_promotion_usage` (
  `id` BIGINT(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `activity_id` BIGINT(20) NOT NULL COMMENT '活动ID',
  `user_id` BIGINT(20) NOT NULL COMMENT '用户ID',
  `order_id` BIGINT(20) NOT NULL COMMENT '关联订单ID',
  `order_amount` DECIMAL(10,2) NOT NULL COMMENT '订单原金额',
  `discount_amount` DECIMAL(10,2) NOT NULL COMMENT '本次优惠金额',
  `tier_id` BIGINT(20) DEFAULT NULL COMMENT '命中的档位ID',
  `usage_status` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '记录状态：0待支付 1已生效 2已回滚（★与限次统计相关）',
  `usage_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '参与时间（下单时间）',
  `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  PRIMARY KEY (`id`),
  KEY `idx_activity_user` (`activity_id`, `user_id`),
  KEY `idx_order_id` (`order_id`),
  KEY `idx_usage_time` (`usage_time`),
  UNIQUE KEY `uk_activity_order` (`activity_id`, `order_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户活动参与记录表';
```

**限次统计规则**：`limit_per_user` 仅统计 `usage_status = 1`（已支付生效）的记录；待支付（0）不占额度，订单取消/超时后将记录置为 2（已回滚）。

### 3.5 索引优化说明

| 索引 | 所在表 | 优化目的 |
|------|-------|---------|
| `idx_status_time` | 主表 | 支持"查询当前生效活动"的高频查询（范围扫描） |
| `idx_store_status` | 主表 | 支持按店铺筛选活动列表（管理端列表页） |
| `idx_activity_id` | 档位表 | JOIN 查询档位信息 |
| `idx_target` | 范围表 | 反查"某商品/分类参与哪些活动" |
| `idx_activity_user` | 参与表 | 校验"用户已参与次数"（聚合查询） |

### 3.6 与现有系统表的关联

| 本表字段 | 关联现有表 | 实际表名 | 说明 |
|---------|-----------|---------|------|
| `store_id` | 店铺 | `fs_store_scrm` | 多店铺主表，`FsStoreScrm.storeId` |
| `target_id`（分类） | 商品分类 | `fs_store_product_category_scrm` | 级联选择分类树 |
| `target_id`（商品） | 商品 | `fs_store_product_scrm` | 商品选择器数据源 |
| `order_id` | 订单 | `fs_store_order_scrm` | 实体 `FsStoreOrderScrm` |
| `user_id` | 会员 | `fs_user` | 下单用户 |

### 3.7 订单表扩展（`fs_store_order_scrm`）

现有订单实体已含 `discountMoney`（总优惠）、`couponPrice`、`userCouponId`，本次新增：

```sql
ALTER TABLE `fs_store_order_scrm`
  ADD COLUMN `promotion_activity_id` BIGINT(20) DEFAULT NULL COMMENT '阶梯满减活动ID' AFTER `user_coupon_id`,
  ADD COLUMN `promotion_tier_id` BIGINT(20) DEFAULT NULL COMMENT '命中档位ID' AFTER `promotion_activity_id`,
  ADD COLUMN `promotion_discount_amount` DECIMAL(10,2) DEFAULT NULL COMMENT '满减优惠金额' AFTER `promotion_tier_id`;
```

> 字段命名与 Java 实体 `FsStoreOrderScrm` 驼峰属性一致，Mapper XML 使用下划线映射。

---

## 4. 核心业务逻辑

### 4.1 用户端查询适用活动（高效过滤）

#### 查询流程

```
用户进入结算页
    ↓
后端接收请求：用户ID、店铺ID、商品列表
    ↓
【第1步】缓存查询：从 Redis 获取该店铺当前生效的活动列表
    ├─ 命中 → 直接返回缓存
    └─ 未命中 → 查询 DB 并写入 Redis
    ↓
【第2步】范围匹配 + 金额基数
    ├─ 从 Redis orderKey 读取购物车（与 computedOrder 一致）
    ├─ 按 storeId 过滤当前店铺商品
    ├─ scope_type=1 → 店铺内商品全额计入
    ├─ scope_type=2 → 仅商品所属分类（含父级）在 scope 表中的 SKU 计入
    └─ scope_type=3 → 仅 productId 在 scope 表中的 SKU 计入
    → 得到 eligibleAmount（活动适用商品小计，不含运费/服务费）
    ↓
【第3步】用户参与校验：usage 表 count(user_id) WHERE usage_status=1
    ↓
【第4步】阶梯计算：按 eligibleAmount 匹配档位（非整单 totalPrice）
    ├─ 选出满足门槛的最高档位
    ├─ 若 is_capped=1（上不封顶），继续按最后一档比例叠加
    └─ 返回优惠后金额
    ↓
返回适用活动列表 + 优惠计算结果
```

#### Service 层核心方法签名

```java
/**
 * 查询结算页适用活动及优惠计算
 * @param storeId 店铺ID
 * @param userId 用户ID
 * @param orderItems 订单商品列表（含价格、分类ID）
 * @return 活动列表及优惠计算结果
 */
List<PromotionComputeResult> computeApplicablePromotions(
    Long storeId, Long userId, List<OrderItemParam> orderItems);
```

#### 档位匹配算法

```java
// 输入：订单总金额 totalAmount，档位列表 tiers（已按 sort_order ASC 排序）
// 输出：命中的最优档位
PromotionTier matchTier(BigDecimal totalAmount, List<PromotionTier> tiers) {
    PromotionTier matched = null;
    for (PromotionTier tier : tiers) {
        if (totalAmount.compareTo(tier.getThresholdAmount()) >= 0) {
            matched = tier;  // 持续覆盖，最后保留匹配的最高档
        }
    }
    return matched;
}

// 上不封顶计算（is_capped=1）：
// 例：档位 满599减150；eligibleAmount=1198
//   基础优惠 = 150（命中最高档）
//   超出部分 = 1198 - 599 = 599
//   额外优惠 = floor(599 / 599) * 150 = 150
//   总优惠 = 300
// 公式：extra = floor((eligibleAmount - lastThreshold) / lastThreshold) * lastDiscount
//       totalDiscount = lastDiscount + extra（eligibleAmount >= lastThreshold 时）
```

**多活动命中策略**：同一店铺同一时间若存在多个适用范围重叠的活动（管理端应禁止启用冲突活动），用户端默认取**优惠金额最大**的一条；实现时在 Service 层遍历候选活动后 `maxBy(discountAmount)`。

### 4.2 下单后端校验流程

```
POST /api/store/promotion/order/submit
    ↓
1. 【参数校验】校验请求参数完整性
    ↓
2. 【活动时间校验】
   SELECT * FROM fs_store_promotion_activity 
   WHERE id = #{activityId} AND manual_status = 1
     AND start_time <= NOW() AND end_time >= NOW()
   → 无结果则抛出 "活动已结束，请重新下单"
   → 若有结果但 end_time < NOW()，更新 status=3，然后抛异常
    ↓
3. 【参与次数校验】
   SELECT COUNT(1) FROM fs_store_promotion_usage 
   WHERE activity_id = #{activityId} AND user_id = #{userId} AND usage_status = 1
   → count >= limit_per_user (且 limit_per_user != 0)
   → 抛出 "您已超过该活动参与次数限制"
    ↓
4. 【叠加规则校验】
   → 若 is_stackable = 0 且该订单使用了优惠券
   → 抛出 "该活动不可与优惠券叠加使用"
    ↓
5. 【优惠金额重算校验】
   → 服务端重新计算优惠金额（基于DB最新时间）
   → 对比客户端传来的优惠金额
   → 不一致则抛出 "优惠信息已变更，请刷新后重试"
    ↓
6. 【创建订单 + 写入参与记录】
   → 事务开始
   → 创建 fs_store_order_scrm（写入 promotion_* 字段）
   → 插入 usage（usage_status=0 待支付）
   → 事务提交
    ↓
7. 【支付成功回调】→ 将 usage.usage_status 更新为 1（计次生效）
    ↓
8. 【返回订单创建成功】
```

#### 乐观锁伪代码

```java
@Transactional
public void deductUsage(Long activityId, Long userId, Long orderId, 
                        BigDecimal orderAmount, BigDecimal discountAmount, Long tierId) {
    // 1. 先查询已使用次数（在事务内，SELECT FOR UPDATE 精确到活动+用户维度）
    //    或者使用 version 乐观锁
    
    FsStorePromotionActivity activity = activityMapper.selectById(activityId);
    int usageCount = usageMapper.countByActivityIdAndUserId(activityId, userId);
    
    if (activity.getLimitPerUser() > 0 && usageCount >= activity.getLimitPerUser()) {
        throw new ServiceException("参与次数已达上限");
    }
    
    // 2. 乐观锁更新：通过 version 保证不会重复扣减
    int updated = usageMapper.insertWithVersion(usage);
    if (updated == 0) {
        throw new ServiceException("活动繁忙，请重试");
    }
}
```

### 4.3 管理端保存/修改后端校验

```java
/**
 * 保存或修改活动时的后端校验流程
 */
public void saveOrUpdateActivity(FsStorePromotionActivityDTO dto) {
    // 1. 基本校验
    if (dto.getStartTime().isAfter(dto.getEndTime())) {
        throw new ServiceException("开始时间不能晚于结束时间");
    }
    
    // 2. 编辑时状态校验
    if (dto.getId() != null) {
        FsStorePromotionActivity exist = getById(dto.getId());
        
        // 进行中的活动不允许修改时间和档位
        if (isActive(exist)) {
            if (isFieldChanged(dto.getStartTime(), exist.getStartTime())
                || isFieldChanged(dto.getEndTime(), exist.getEndTime())
                || isFieldChanged(dto.getScopeType(), exist.getScopeType())) {
                throw new ServiceException("进行中的活动不可修改时间和适用范围");
            }
            // 允许修改结束时间（仅可延后）
            if (dto.getEndTime().isBefore(exist.getEndTime())) {
                throw new ServiceException("只能延后结束时间，不能提前");
            }
        }
    }
    
    // 3. 时间+范围冲突检测：同一店铺、时间重叠、且 scope 有交集的「已启用」活动不可并存
    int conflictCount = activityMapper.countConflictActivity(
        dto.getStoreId(), dto.getStartTime(), dto.getEndTime(),
        dto.getScopeType(), dto.getScopeIds(), dto.getId()
    );
    if (conflictCount > 0) {
        throw new ServiceException("该时间段内已存在适用范围重叠的满减活动，请调整时间或范围");
    }
    
    // 4. 档位校验
    List<PromotionTierDTO> tiers = dto.getTiers();
    if (tiers == null || tiers.size() < 1) {
        throw new ServiceException("至少设置一档满减规则");
    }
    for (int i = 1; i < tiers.size(); i++) {
        if (tiers.get(i).getThresholdAmount().compareTo(tiers.get(i-1).getThresholdAmount()) <= 0) {
            throw new ServiceException("第" + (i+1) + "档门槛金额必须大于第" + i + "档");
        }
        if (tiers.get(i).getDiscountAmount().compareTo(tiers.get(i-1).getDiscountAmount()) < 0) {
            throw new ServiceException("第" + (i+1) + "档优惠金额不能小于第" + i + "档");
        }
    }
    
    // 5. 适用范围校验
    if (dto.getScopeType() == 2 && (dto.getScopeIds() == null || dto.getScopeIds().isEmpty())) {
        throw new ServiceException("选择指定分类时，请至少选择一个分类");
    }
    if (dto.getScopeType() == 3 && (dto.getScopeIds() == null || dto.getScopeIds().isEmpty())) {
        throw new ServiceException("选择指定商品时，请至少选择一个商品");
    }
}
```

---

## 5. 接口设计

### 5.1 管理端接口

> 基于现有 Controller 模式：`@RestController + @RequestMapping + @PreAuthorize`  
> 模块路径：`D:\hdProject\ylrz_his_scrm_java\fs-admin\src\main\java\com\fs\hisStore\controller\`

#### 5.1.1 活动列表查询

```
GET /store/storePromotion/list
```

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| title | String | 否 | 活动名称（模糊搜索） |
| storeId | Long | 否 | 店铺ID |
| status | Integer | 否 | 活动状态：0草稿 1未开始 2进行中 3已结束 4已关闭 |
| startTime | Date | 否 | 开始时间（范围起） |
| endTime | Date | 否 | 结束时间（范围止） |
| pageNum | Integer | 是 | 页码 |
| pageSize | Integer | 是 | 每页条数 |

**响应示例**：

```json
{
  "code": 200,
  "rows": [
    {
      "id": 1,
      "title": "618年中大促",
      "storeId": 100,
      "storeName": "旗舰店",
      "startTime": "2026-06-01 00:00:00",
      "endTime": "2026-06-30 23:59:59",
      "scopeType": 1,
      "scopeTypeLabel": "全场通用",
      "isStackable": 1,
      "isCapped": 0,
      "limitPerUser": 3,
      "displayStatus": 2,
      "displayStatusLabel": "进行中",
      "tierCount": 3,
      "createTime": "2026-05-20 10:00:00"
    }
  ],
  "total": 1
}
```

**后端注意**：`displayStatus` 为 SQL 查询时动态计算字段，使用 `CASE WHEN` 根据 `manual_status` + 时间范围实时计算：

```sql
-- display_status 动态计算（列表 SELECT 子句）
SELECT 
  a.*,
  CASE 
    WHEN a.manual_status IS NULL THEN 0
    WHEN a.manual_status = 0 THEN 4
    WHEN a.manual_status = 1 AND NOW() < a.start_time THEN 1
    WHEN a.manual_status = 1 AND NOW() >= a.start_time AND NOW() <= a.end_time THEN 2
    WHEN a.manual_status = 1 AND NOW() > a.end_time THEN 3
    ELSE 0
  END AS display_status
FROM fs_store_promotion_activity a
WHERE a.is_del = 0
-- 按 display_status 筛选时使用相同 CASE 表达式或 HAVING display_status = #{status}
```

#### 5.1.2 新增活动

```
POST /store/storePromotion
```

**请求体**：

```json
{
  "title": "618年中大促",
  "storeId": 100,
  "startTime": "2026-06-01 00:00:00",
  "endTime": "2026-06-30 23:59:59",
  "scopeType": 2,
  "scopeIds": [10, 20, 30],
  "isStackable": 1,
  "isCapped": 0,
  "limitPerUser": 3,
  "tiers": [
    {"sortOrder": 1, "thresholdAmount": 199.00, "discountAmount": 30.00},
    {"sortOrder": 2, "thresholdAmount": 399.00, "discountAmount": 80.00},
    {"sortOrder": 3, "thresholdAmount": 599.00, "discountAmount": 150.00}
  ],
  "remark": ""
}
```

**响应**：

```json
{"code": 200, "msg": "操作成功"}
```

#### 5.1.3 编辑活动

```
PUT /store/storePromotion
```

请求体同上，增加 `"id": 1`。

#### 5.1.4 查询活动详情

```
GET /store/storePromotion/{activityId}
```

**响应**：返回活动完整信息，含档位列表、适用范围明细。

#### 5.1.5 删除活动

```
DELETE /store/storePromotion/{activityIds}
```

逻辑删除（`is_del = 1`），仅草稿/已结束/已关闭状态可删。

#### 5.1.6 启用活动

```
PUT /store/storePromotion/{activityId}/enable
```

**前置校验**：`end_time >= NOW()`，否则返回错误。

**响应**：

```json
{"code": 200, "msg": "操作成功", "data": {"newDisplayStatus": 2}}
```

#### 5.1.7 停用活动

```
PUT /store/storePromotion/{activityId}/disable
```

**前置校验**：仅未开始/进行中状态可停用。

**响应**：

```json
{"code": 200, "msg": "操作成功", "data": {"newDisplayStatus": 4}}
```

#### 5.1.8 店铺列表（下拉选项）

复用现有店铺接口，**无需新增**：

```
GET /store/his/store/listOption
```

前端引用：`@/api/hisStore/store.js` → `listOption()`。

---

### 5.2 用户端接口（结算活动查询 + 订单链路扩展）

> **Controller**：`fs-user-app` → `StoreOrderScrmController`，基础路径 `/store/app/storeOrder`  
> **Service**：`fs-service` → 新增 `IFsStorePromotionComputeService`（或并入 `FsStoreOrderScrmServiceImpl`），供 list/computed/create 共用  
> 购物车数据仍通过 Redis `orderKey` / `orderCarts:{orderKey}` 读取（与 `confirmOrder`、`computedOrder` 一致）

#### 5.2.1 结算页查询可用满减活动（★新增）

**单店铺**

```
POST /store/app/storeOrder/promotion/list
```

| 属性 | 说明 |
|------|------|
| 鉴权 | `@Login`，与 `/computed` 相同 |
| 用途 | 结算页进入时拉取当前订单可参与的活动列表，供用户选择 |

**请求体** `FsStorePromotionListParam`：

| 字段 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| orderKey | String | 是 | confirm 返回的订单缓存 key |
| storeId | Long | 否 | 单店购物车可不传，由 carts 推断 |
| couponUserId | Long | 否 | 已选优惠券 ID，用于标记 `stackableConflict` |

**响应** `FsStorePromotionListVO`：

```json
{
  "code": 200,
  "data": {
    "storeId": 100,
    "storeName": "旗舰店",
    "eligibleAmount": 498.00,
    "recommendedActivityId": 1,
    "activities": [
      {
        "activityId": 1,
        "title": "618年中大促",
        "scopeType": 1,
        "scopeTypeLabel": "全场通用",
        "isStackable": true,
        "isCapped": false,
        "limitPerUser": 3,
        "userUsedCount": 1,
        "userRemainCount": 2,
        "enabled": true,
        "disabledReason": null,
        "matchedTier": {
          "tierId": 2,
          "thresholdAmount": 399.00,
          "discountAmount": 80.00
        },
        "nextTierTip": "再购101元可减150元",
        "estimatedDiscount": 80.00,
        "tiers": [
          {"sortOrder": 1, "thresholdAmount": 199.00, "discountAmount": 30.00},
          {"sortOrder": 2, "thresholdAmount": 399.00, "discountAmount": 80.00},
          {"sortOrder": 3, "thresholdAmount": 599.00, "discountAmount": 150.00}
        ]
      },
      {
        "activityId": 2,
        "title": "指定品类满减",
        "enabled": false,
        "disabledReason": "适用商品金额未达最低门槛",
        "estimatedDiscount": 0
      }
    ]
  }
}
```

**后端逻辑**：

1. 从 Redis 读 `orderCarts:{orderKey}`，校验未过期
2. 按 `storeId` 查生效活动（查即验证 + 缓存）
3. 逐活动计算 `eligibleAmount`、匹配档位、`estimatedDiscount`
4. `recommendedActivityId` = `enabled=true` 中 `estimatedDiscount` 最大者
5. 校验用户 `usage_status=1` 次数 → 填充 `userRemainCount`

**多店铺**

```
POST /store/app/storeOrder/promotion/listMultiStore
```

**请求体** `FsStorePromotionListMultiStoreParam`：

| 字段 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| orderKeys | List\<String\> | 是 | 与 `computedMultiStore` 一致，每店一个 orderKey |
| couponUserId | Long | 否 | 全局优惠券（若业务按店分券则扩展为 Map） |

**响应**：`List<FsStorePromotionListVO>`，每个元素对应一个店铺的活动列表。

**Controller 伪代码**：

```java
@Login
@ApiOperation("结算页-查询可用满减活动")
@PostMapping("/promotion/list")
public R promotionList(@Validated @RequestBody FsStorePromotionListParam param) {
    Long userId = Long.parseLong(getUserId());
    return R.ok().put("data", promotionComputeService.listApplicablePromotions(userId, param));
}

@Login
@ApiOperation("结算页-多店铺查询可用满减活动")
@PostMapping("/promotion/listMultiStore")
public R promotionListMultiStore(@Validated @RequestBody FsStorePromotionListMultiStoreParam param) {
    Long userId = Long.parseLong(getUserId());
    return R.ok().put("data", promotionComputeService.listApplicablePromotionsMultiStore(userId, param));
}
```

#### 5.2.2 结算页查询活动详情（可选）

用于「查看规则 >」弹窗，避免 list 重复传完整 tiers：

```
GET /store/app/storeOrder/promotion/{activityId}
```

**Query**：`orderKey`（校验该活动对当前购物车是否适用）

**响应**：活动规则 + 全部档位 + 当前匹配结果。

#### 5.2.3 扩展 Param / DTO 字段

**FsStoreOrderComputedParam** 新增：

| 字段 | 类型 | 说明 |
|------|------|------|
| promotionActivityId | Long | 用户选中的满减活动 ID；**null = 不参与满减** |
| storeId | Long | 单店铺计算时指定店铺 |

**FsStoreOrderComputedGroupStoreParam** 扩展（多店铺）：

| 字段 | 类型 | 说明 |
|------|------|------|
| promotionActivityIds | List\<PromotionStoreActivityParam\> | 每店选中活动，`[{storeId, promotionActivityId}]` |

**FsStoreOrderComputeDTO** 新增：

| 字段 | 类型 | 说明 |
|------|------|------|
| promotionActivityId | Long | 命中的活动 ID |
| promotionTierId | Long | 命中档位 ID |
| promotionDiscountAmount | BigDecimal | 满减金额 |
| promotionTitle | String | 活动名称 |
| promotionRemainCount | Integer | 剩余可参与次数（null=不限） |

**FsStoreOrderCreateParam** / **FsStoreOrderCreateGroupStoreParam** 同步增加上述字段。

**fs-service 新增类**（附录 A 补充）：

- `param/FsStorePromotionListParam.java`
- `param/FsStorePromotionListMultiStoreParam.java`
- `param/PromotionStoreActivityParam.java`
- `vo/FsStorePromotionListVO.java`
- `vo/FsStorePromotionActivityItemVO.java`

#### 5.2.4 计算订单金额（现有接口扩展）

```
POST /store/app/storeOrder/computed
POST /store/app/storeOrder/computedMultiStore
```

**请求体扩展示例**：

```json
{
  "orderKey": "abc123",
  "addressId": 1,
  "couponUserId": null,
  "useIntegral": 0,
  "promotionActivityId": 1
}
```

**响应扩展示例**：

```json
{
  "code": 200,
  "data": {
    "totalPrice": 498.00,
    "payPrice": 418.00,
    "payPostage": 0,
    "deductionPrice": 0,
    "promotionActivityId": 1,
    "promotionTierId": 2,
    "promotionDiscountAmount": 80.00,
    "promotionTitle": "618年中大促",
    "promotionRemainCount": 2
  }
}
```

**Service 内处理要点**：

1. 与 `promotion/list` 共用 `computeEligibleAmount`、`matchTier` 方法
2. `promotionActivityId` 非空时：`validateAndExpire` → 重算满减 → 扣减 `payPrice`
3. `is_stackable=0` 且已选优惠券 → 抛错「不可与优惠券叠加」
4. 满减在积分之后、优惠券之前（见 0.3 节）

#### 5.2.5 创建订单（现有接口扩展）

```
POST /store/app/storeOrder/create
POST /store/app/storeOrder/createMultiStore
```

**请求体扩展**：`promotionActivityId`、`promotionTierId`（金额以服务端重算为准）。

**处理流程**：`createOrder` 内再次执行满减逻辑 → 写 `fs_store_order_scrm.promotion_*` → 写 usage（待支付）。

**错误响应**：

```json
{"code": 500, "msg": "活动已结束，请重新下单"}
{"code": 500, "msg": "您已超过该活动参与次数限制"}
{"code": 500, "msg": "该活动不可与优惠券叠加使用"}
{"code": 500, "msg": "优惠信息已变更，请刷新后重试"}
```

#### 5.2.6 用户端 API 封装示例（uni-app）

```javascript
// api/store/order.js（用户端工程，路径以实际项目为准）

/** 结算页-查询可用满减活动（单店） */
export function listSettlementPromotions(data) {
  return request({ url: '/store/app/storeOrder/promotion/list', method: 'post', data })
}

/** 结算页-查询可用满减活动（多店） */
export function listSettlementPromotionsMultiStore(data) {
  return request({ url: '/store/app/storeOrder/promotion/listMultiStore', method: 'post', data })
}

/** 计算金额（扩展 promotionActivityId） */
export function computedOrder(data) {
  return request({ url: '/store/app/storeOrder/computed', method: 'post', data })
}
```

---

## 6. 非功能性设计

### 6.1 缓存策略与更新机制

#### 6.1.1 缓存架构

```
                 用户请求
                    │
                    ▼
              Redis 缓存层
            (店铺维度Key)
                    │
              ┌─ 命中 ───▶ 返回
              │
              └─ 未命中
                    │
                    ▼
              MySQL 查询
              (当前生效活动)
                    │
                    ▼
              写入 Redis
              (TTL = 5分钟)
                    │
                    ▼
              返回结果
```

#### 6.1.2 Redis Key 设计

| Key 模式 | 说明 | TTL |
|----------|------|-----|
| `promotion:store:{storeId}` | 店铺当前生效的活动列表（含档位） | 5 分钟 |
| `promotion:detail:{activityId}` | 单个活动详情（含档位+范围） | 10 分钟 |
| `promotion:usage:{activityId}:{userId}` | 用户当前已参与次数 | 与 DB 同步，30 秒 |

#### 6.1.3 缓存更新策略

| 触发场景 | 更新操作 |
|---------|---------|
| 管理端新增/编辑活动 | 删除 `promotion:store:{storeId}`，下次请求时懒加载 |
| 管理端启用/停用活动 | 同上 |
| 用户下单使用活动 | 更新 `promotion:usage:{activityId}:{userId}`（INCR） |
| 定时任务检测到活动过期 | 删除 `promotion:store:{storeId}` |
| 缓存自然过期 | 自动失效，下次请求重新加载 |

#### 6.1.4 缓存穿透/雪崩防护

- **缓存穿透**：启用活动时，同时将 NULL 活动标记存到 Redis（TTL 30秒），避免不存在店铺的请求穿透到 DB
- **缓存雪崩**：各 Key 的 TTL 加随机偏移量（±60秒），避免同时过期
- **热点缓存**：针对大促期间的爆款店铺活动，使用本地缓存（Caffeine）作为二级缓存，TTL 1分钟

```java
@Service
public class PromotionCacheService {
    
    @Autowired
    private RedisCache redisCache;  // 与 FsStoreOrderScrmServiceImpl 一致
    
    /**
     * 获取店铺当前生效活动（查即验证 + 缓存）
     * Key: promotion:store:{storeId}
     */
    public List<PromotionActivityVO> getActivePromotions(Long storeId) {
        String redisKey = "promotion:store:" + storeId;
        List<PromotionActivityVO> cached = redisCache.getCacheObject(redisKey);
        if (cached != null) {
            return cached;
        }
        cached = loadFromDBAndExpireCheck(storeId);
        redisCache.setCacheObject(redisKey, cached, 5, TimeUnit.MINUTES);
        return cached;
    }
    
    /** 管理端变更后主动失效 */
    public void evictStorePromotion(Long storeId) {
        redisCache.deleteObject("promotion:store:" + storeId);
    }
}
```

---

### 6.2 并发控制——防超卖与重复使用

#### 6.2.1 核心机制：MySQL 乐观锁 + Redis 预占

| 并发场景 | 机制 | 说明 |
|---------|------|------|
| 同一用户并发下单同一活动 | 乐观锁 + 唯一约束 | 通过 `version` 字段避免参与次数超限 |
| 多用户并发抢同一活动 | 无库存概念 | 阶梯满减无固定库存，不需限制总量 |
| 时间临界点并发 | `SELECT FOR UPDATE` + 时间二次校验 | 下单事务中严格校验时间边界 |

#### 6.2.2 参与次数并发控制实现

```java
@Transactional(rollbackFor = Exception.class)
public void recordPromotionUsage(Long activityId, Long userId, 
                                  Long orderId, BigDecimal discountAmount, Long tierId) {
    // 1. 悲观锁锁定活动行，防止并发修改
    FsStorePromotionActivity activity = activityMapper.selectForUpdate(activityId);
    
    // 2. 时间二次校验
    LocalDateTime now = LocalDateTime.now();
    if (activity.getManualStatus() != 1 
        || now.isBefore(activity.getStartTime()) 
        || now.isAfter(activity.getEndTime())) {
        throw new ServiceException("活动已失效");
    }
    
    // 3. 查询当前使用次数
    Integer usageCount = usageMapper.countByActivityAndUser(activityId, userId);
    
    // 4. 次数校验
    if (activity.getLimitPerUser() > 0 && usageCount >= activity.getLimitPerUser()) {
        throw new ServiceException("参与次数已达上限");
    }
    
    // 5. 插入记录（带唯一索引防重）
    try {
        usageMapper.insert(new FsStorePromotionUsage()
            .setActivityId(activityId)
            .setUserId(userId)
            .setOrderId(orderId)
            .setDiscountAmount(discountAmount)
            .setTierId(tierId));
    } catch (DuplicateKeyException e) {
        throw new ServiceException("请勿重复提交");
    }
}
```

**建议**：`fs_store_promotion_usage` 表唯一索引（已纳入 3.4 建表语句）：

```sql
UNIQUE KEY `uk_activity_order` (`activity_id`, `order_id`)
```

#### 6.2.3 Redis 分布式锁（可选增强）

对于高并发场景，在下单入口增加 Redis 分布式锁（Redisson），锁粒度为 `promotion:lock:{activityId}:{userId}`，超时时间 10 秒。保证同一用户同一活动串行处理。

---

### 6.3 异常情况处理

#### 6.3.1 手动关停时，已下单但未支付订单处理

| 订单状态 | 处理策略 | 实现方式 |
|---------|---------|---------|
| 已支付 | 不受影响，活动优惠保留 | 订单快照字段 `promotion_discount_amount` 已写入 |
| 未支付 - 超时未付 | 订单自动取消，usage 置为已回滚 | 现有订单超时任务中 `UPDATE usage SET usage_status=2` |
| 未支付 - 用户主动取消 | 同上 | 取消订单接口同步回滚 usage |
| 未支付 - 用户继续支付 | **允许支付**，以订单创建时快照为准 | 支付回调不重复校验活动时效 |

**设计理由**：
- 下单时 `fs_store_order` 表中已有 `discount_amount`（折扣金额）字段，订单是活动优惠的快照
- 关停活动不应影响已创建的合法订单，否则引起大量客诉
- 取消订单时回滚 usage 记录，归还参与次数

#### 6.3.2 支付时活动已结束的处理

```
支付回调 → 仅校验支付金额与订单金额一致 → 完成支付
（不再次校验活动状态，以订单创建时的计算结果为准）
```

`fs_store_order_scrm` 表已有字段：
- `discountMoney`（BigDecimal）：订单优惠总金额（可与满减+券合计或分项存储，需与财务口径对齐）
- `couponPrice`（BigDecimal）：优惠券金额
- `userCouponId`（Long）：使用的用户优惠券 ID

本次新增字段见 [3.7 订单表扩展](#37-订单表扩展fs_store_order_scrm)。

#### 6.3.3 其他异常场景

| 异常场景 | 处理策略 |
|---------|---------|
| Redis 不可用 | 降级为直接查 DB，活动查询不受影响 |
| 定时任务未执行 | 查即验证兜底，用户请求时触发状态更新 |
| 数据库主从延迟 | 下单时使用主库读写；查询时若读从库允许短暂延迟 |
| 活动修改并发冲突 | `version` 乐观锁，后提交者收到冲突提示 |
| 订单部分退款 | 不退优惠金额（满减优惠为整单优惠），按商品实付金额比例退款 |

---

## 附录

### A. 文件目录规划

**后端 Java 文件**（模块：`fs-admin` + `fs-service`，Domain 均在 `fs-service`）：

```
fs-admin/src/main/java/com/fs/hisStore/controller/
└── FsStorePromotionController.java              ← 管理端 CRUD / 启用停用

fs-service/src/main/java/com/fs/hisStore/
├── domain/ ...（同前）
├── param/
│   ├── FsStorePromotionListParam.java           ← 结算页 list 入参
│   ├── FsStorePromotionListMultiStoreParam.java
│   └── PromotionStoreActivityParam.java         ← 多店选中活动
├── vo/
│   ├── FsStorePromotionListVO.java
│   └── FsStorePromotionActivityItemVO.java
├── service/
│   ├── IFsStorePromotionComputeService.java     ← list + 计算共用
│   └── impl/FsStorePromotionComputeServiceImpl.java
└── ...

fs-service/.../FsStoreOrderScrmServiceImpl.java  ← computedOrder / createOrder 调用 ComputeService

fs-user-app/.../StoreOrderScrmController.java    ← 新增 promotion/list、listMultiStore；扩展 computed/create
```

**用户端 uni-app（APP / 小程序，工程路径以各环境仓库为准）**：

```
pages/store/order/confirm.vue          ← 单店结算页（或项目内等价路径）
pages/store/order/confirmMulti.vue     ← 多店结算页
api/store/order.js                     ← listSettlementPromotions / computed / create
```

**前端 Vue 文件**（`D:\web\cs\ylrz_his_scrm_adminUI\src`）：

```
src/
├── api/hisStore/
│   └── storePromotion.js                        ← API 接口封装
├── views/hisStore/storePromotion/
│   ├── index.vue                                ← 活动列表页
│   ├── add.vue                                  ← 新增活动页
│   ├── edit.vue                                 ← 编辑活动页
│   └── detail.vue                               ← 活动详情页
```

### B. 档位枚举与常量定义

```java
// PromotionScopeTypeEnum.java
public enum PromotionScopeTypeEnum {
    ALL(1, "全场通用"),
    CATEGORY(2, "指定分类"),
    PRODUCT(3, "指定商品");
    
    private final Integer code;
    private final String desc;
}

// PromotionDisplayStatusEnum.java
public enum PromotionDisplayStatusEnum {
    DRAFT(0, "草稿"),
    NOT_STARTED(1, "未开始"),
    ACTIVE(2, "进行中"),
    ENDED(3, "已结束"),
    CLOSED(4, "已关闭");
    
    private final Integer code;
    private final String desc;
}
```

### C. 现有系统集成注意事项

1. **权限控制**：管理端 `@PreAuthorize("@ss.hasPermi('store:storePromotion:list')")` 等，命名对齐 `store:storeCoupon:*`
2. **操作日志**：`@Log(title = "阶梯满减", businessType = BusinessType.xxx)`
3. **BaseEntity**：活动主表实体继承 `BaseEntity`，档位/范围/usage 表仅保留必要时间字段
4. **事务**：`@Transactional(rollbackFor = Exception.class)`，与 `FsStoreOrderScrmServiceImpl.createOrder` 一致
5. **订单扩展**：见 3.7 节，Java 实体 `FsStoreOrderScrm` 同步增加属性
6. **优惠券模块参考**：UI/交互可对齐 `views/hisStore/storeCoupon/index.vue`；Controller 对齐 `FsStoreCouponScrmController`（`/store/storeCoupon`）
7. **管理端路由前缀**：`/store/storePromotion`，与 `/store/storeCoupon` 并列
8. **菜单 SQL**：在 `sys_menu` 新增「阶梯满减」菜单，父级挂在现有 hisStore 商城菜单下
9. **多店铺下单**：必须测试 `promotion/listMultiStore`、`computedMultiStore`、`createMultiStore`
10. **查即验证**：在 `promotion/list`、`computedOrder`、`createOrder`、管理端详情接口调用统一 `validateAndExpire`
11. **结算页改造**：APP 与小程序共用 uni-app 结算页，进入页先调 `promotion/list`，切换活动再调 `computed`（见 1.4 节）
12. **接口顺序**：`confirm` → `promotion/list` → `computed`（可多次）→ `create`，不可跳过 list 直接写死 activityId

---

> **文档结束** — v1.2.1 管理端后台已实现；用户端与下单链路见「实现进度追踪」待办项。