kknongchang_2506/app/Module/Shop/Docs/商店限购功能优化说明.md

商店限购功能优化说明

概述

本次优化为商店系统添加了更加灵活和强大的限购功能，支持单次购买限制和周期性购买限制，满足不同的业务需求。

新增功能

1. 单次购买限制

• 功能描述：限制用户单次购买的最大数量
• 应用场景：防止用户一次性购买过多商品，保证商品分配的公平性
• 配置方式：在商品编辑页面设置 max_single_buy 字段

2. 周期性购买限制

• 功能描述：在指定周期内限制用户购买的总数量
• 支持周期：
  • 永久限制：商品整个生命周期内的限制
  • 每日限制：每天重置购买计数
  • 每周限制：每周重置购买计数（周一重置）
  • 每月限制：每月重置购买计数（每月1日重置）
  • 每年限制：每年重置购买计数（每年1月1日重置）

3. 灵活的限购配置

• 多规则支持：一个商品可以配置多个限购规则
• 优先级控制：通过排序权重控制多个限购规则的检查顺序
• 状态管理：可以独立启用/禁用每个限购规则

数据库结构

新增表

1. kku_shop_purchase_limits（限购配置表）

字段名	类型	说明
id	int	限购配置ID，主键
shop_item_id	int	商品ID，外键
limit_type	tinyint	限购类型（1:单次购买限制, 2:周期性购买限制）
limit_period	tinyint	限购周期（0:永久, 1:每日, 2:每周, 3:每月, 4:每年）
max_quantity	int	最大购买数量
name	varchar	限购规则名称
description	text	限购规则描述
is_active	tinyint	是否激活
sort_order	int	排序权重

2. kku_shop_user_purchase_counters（用户购买计数表）

字段名	类型	说明
id	int	记录ID，主键
limit_id	int	限购配置ID，外键
user_id	int	用户ID
current_count	int	当前购买计数
last_reset_time	timestamp	上次重置时间

修改表

kku_shop_items（商品表）

新增字段：

• max_single_buy：单次最大购买数量（0表示无限制）

核心类说明

枚举类

1. PURCHASE_LIMIT_PERIOD：限购周期类型枚举
2. PURCHASE_LIMIT_TYPE：限购类型枚举

模型类

1. ShopPurchaseLimit：限购配置模型
2. ShopUserPurchaseCounter：用户购买计数模型

验证逻辑

• ShopBuyLimitValidator：已更新以支持新的限购规则验证
• ShopItem::canUserPurchaseWithLimits()：统一的限购检查方法

使用示例

1. 设置单次购买限制

// 设置商品单次最多购买5个
$shopItem = ShopItem::find(1);
$shopItem->max_single_buy = 5;
$shopItem->save();

2. 创建周期性限购规则

// 创建每日限购规则：每天最多购买3个
ShopPurchaseLimit::create([
    'shop_item_id' => 1,
    'limit_type' => PURCHASE_LIMIT_TYPE::PERIODIC_PURCHASE,
    'limit_period' => PURCHASE_LIMIT_PERIOD::DAILY,
    'max_quantity' => 3,
    'name' => '每日限购',
    'description' => '每天最多购买3个',
    'is_active' => true,
    'sort_order' => 0,
]);

3. 检查购买限制

$shopItem = ShopItem::find(1);
$userId = 123;
$quantity = 2;

list($canPurchase, $errorMessage, $remainingQuantity) = 
    $shopItem->canUserPurchaseWithLimits($userId, $quantity);

if (!$canPurchase) {
    echo "购买失败：" . $errorMessage;
} else {
    echo "可以购买，剩余可购买数量：" . $remainingQuantity;
}

后台管理

1. 商品管理

• 在商品编辑页面可以设置单次购买限制
• 商品列表页面显示总限购和单次限购信息
• 提供"限购配置"按钮快速跳转到限购规则管理

2. 限购配置管理

• 独立的限购配置管理页面
• 支持按商品、限购类型、限购周期筛选
• 支持批量操作和状态切换

性能优化

1. 批量查询优化

• 支持批量获取多个商品的限购配置
• 减少数据库查询次数，提高性能

2. 计数重置机制

• 自动检测并重置过期的购买计数
• 避免手动维护计数数据

兼容性说明

• 保持与现有 max_buy 字段的兼容性
• 新的限购规则与传统限购规则并行工作
• 不影响现有的购买流程和验证逻辑

注意事项

1. 数据库迁移：需要执行相应的SQL脚本创建新表和字段
2. 权限配置：需要为后台用户分配限购配置管理权限
3. 测试验证：建议在测试环境充分验证各种限购场景
4. 性能监控：关注新增的查询和计算对系统性能的影响