alien_cloud/alien-store-platform/接口文档/菜品优惠接口文档.md

菜品优惠接口文档

版本：v1
模块：alien-store
前缀：/store/productDiscount

---

统一返回结构

接口返回统一为 R<T>：

• code：200 成功，非 200 失败
• msg：提示信息
• data：业务数据

---

一、优惠规则接口（已实现）

1) 列表

• URL：GET /store/productDiscount/list
• Query 参数

参数	类型	必填	说明
storeId	Integer	是	门店ID
productId	Integer	否	菜品ID筛选
ruleName	String	否	规则名称模糊搜索
status	Integer	否	0关闭，1开启
pageNum	Integer	否	默认1
pageSize	Integer	否	默认10

• 返回 data：IPage<StoreProductDiscountRuleListVo>

字段	类型	说明
id	Integer	规则ID
storeId	Integer	门店ID
productId	Integer	菜品ID
productName	String	菜品名称（当前版本可能为空，见文末说明）
ruleName	String	规则名称
discountType	String	FREE / DISCOUNT
discountRate	BigDecimal	折扣比例（FREE可能为空）
effectiveMode	String	PERMANENT / CUSTOM
dateRange	String	日期范围，如 2026-04-01 ~ 2026-04-30 或 永久生效
slotCount	Integer	时段数量
status	Integer	0关闭，1开启
updatedTime	DateTime	更新时间

---

2) 详情（编辑回显）

• URL：GET /store/productDiscount/detail?id={id}
• Query 参数

参数	类型	必填	说明
id	Integer	是	规则ID

• 返回 data：StoreProductDiscountRuleDetailVo

字段	类型	说明
id	Integer	规则ID
storeId	Integer	门店ID
productId	Integer	菜品ID
productName	String	菜品名称（当前版本可能为空）
ruleName	String	规则名称
discountType	String	FREE / DISCOUNT
discountRate	BigDecimal	折扣比例
effectiveMode	String	PERMANENT / CUSTOM
startDate	String	开始日期 yyyy-MM-dd
endDate	String	结束日期 yyyy-MM-dd
status	Integer	状态
slots	Array	生效时段列表

slots 子项：

字段	类型	说明
weekdayMask	Integer	星期掩码（周一到周日按位）
startTime	String	HH:mm:ss
endTime	String	HH:mm:ss

---

3) 新建优惠

• URL：POST /store/productDiscount/create
• Content-Type：application/json

请求体：StoreProductDiscountRuleSaveDto

字段	类型	必填	说明
storeId	Integer	是	门店ID
productId	Integer	是	菜品ID
ruleName	String	是	规则名称（同店同菜品唯一）
discountType	String	是	FREE / DISCOUNT
discountRate	BigDecimal	DISCOUNT必填	折扣比例（0-100）
effectiveMode	String	是	PERMANENT / CUSTOM
startDate	String	CUSTOM必填	yyyy-MM-dd
endDate	String	CUSTOM必填	yyyy-MM-dd
slots	Array	否	生效时段（FREE/DISCOUNT均可不传）
status	Integer	是	0关闭，1开启

请求示例（折扣）：

{
  "storeId": 1,
  "productId": 10001,
  "ruleName": "周末八折",
  "discountType": "DISCOUNT",
  "discountRate": 80,
  "effectiveMode": "CUSTOM",
  "startDate": "2026-04-01",
  "endDate": "2026-06-30",
  "slots": [
    {
      "weekdayMask": 65,
      "startTime": "10:00:00",
      "endTime": "22:00:00"
    }
  ],
  "status": 1
}

请求示例（免费）：

{
  "storeId": 1,
  "productId": 10001,
  "ruleName": "工作日免费",
  "discountType": "FREE",
  "effectiveMode": "PERMANENT",
  "status": 1
}

---

4) 编辑优惠

• URL：POST /store/productDiscount/update
• Content-Type：application/json
• 请求体同“新建”，且 id 必填

---

5) 删除优惠

• URL：POST /store/productDiscount/delete?id={id}

参数	类型	必填	说明
id	Integer	是	规则ID

---

6) 切换启用状态

• URL：POST /store/productDiscount/switchStatus?id={id}&status={0|1}

参数	类型	必填	说明
id	Integer	是	规则ID
status	Integer	是	0关闭，1开启

---

二、核心校验规则（后端已实现）

1. 名称唯一：同门店同菜品下，ruleName 不可重复
   
2. DISCOUNT 规则：discountRate 必填，且仅支持 effectiveMode=CUSTOM
   
3. CUSTOM 日期：startDate/endDate 必填，且开始不能晚于结束
   
4. 时间格式：startTime/endTime 必须成对出现，且开始早于结束
   
5. 时间冲突校验（同店同菜品，开启状态）：
   • 日期有交集
   • 星期有交集（weekdayMask 按位与 > 0）
   • 时间有交集（start1 < end2 && start2 < end1）
   • 若重叠且类型不同：报“该菜品在该时间段已配置其他类型优惠”
   • 若重叠且类型相同：报“该菜品优惠时间重叠，请调整生效日期/星期/时间”
6. 未配置时段时：按“全星期+全天”参与冲突判断

---

三、常见错误提示

• 门店ID不能为空
• 菜品ID不能为空
• 规则名称不能为空
• 优惠类型不能为空
• 优惠类型不合法
• 折扣比例不能为空
• 折扣优惠仅支持自定义日期
• 自定义日期开始/结束不能为空
• 开始日期不能大于结束日期
• 生效时间需成对出现
• 生效开始时间必须早于结束时间
• 该菜品优惠名称已存在
• 该菜品在该时间段已配置其他类型优惠
• 该菜品优惠时间重叠，请调整生效日期/星期/时间

---

四、联调注意事项

1. 当前代码中 productName 字段映射查询尚未接入真实菜品表查询，返回可能为空；建议联调先以 productId 为主。
   
2. 你提到的“菜品列表（按名称模糊）”接口，目前尚未在本次代码中新增；如需我可补：
   • GET /store/product/list?storeId=1&keyword=鱼&pageNum=1&pageSize=10