# 商店限购功能优化

## 任务概述

根据用户需求，对商店系统的限购功能进行全面优化，实现：
- 单次购买限制
- 周期性购买数量限购（周/月/年/永久）
- 灵活的限购配置管理

## 实现内容

### 1. 枚举类创建

#### PURCHASE_LIMIT_PERIOD（限购周期枚举）
- **文件位置**：`app/Module/Shop/Enums/PURCHASE_LIMIT_PERIOD.php`
- **支持周期**：永久、每日、每周、每月、每年
- **核心功能**：
  - 获取下次重置时间
  - 检查是否需要重置计数
  - 周期类型名称获取

#### PURCHASE_LIMIT_TYPE（限购类型枚举）
- **文件位置**：`app/Module/Shop/Enums/PURCHASE_LIMIT_TYPE.php`
- **支持类型**：单次购买限制、周期性购买限制
- **功能描述**：提供限购类型的标准化定义

### 2. 模型层扩展

#### ShopPurchaseLimit（限购配置模型）
- **文件位置**：`app/Module/Shop/Models/ShopPurchaseLimit.php`
- **核心功能**：
  - 管理限购规则配置
  - 用户购买计数查询
  - 限购验证逻辑
  - 计数增加和重置

#### ShopUserPurchaseCounter（用户购买计数模型）
- **文件位置**：`app/Module/Shop/Models/ShopUserPurchaseCounter.php`
- **核心功能**：
  - 记录用户购买计数
  - 自动重置过期计数
  - 限制达成检查

#### ShopItem模型扩展
- **新增字段**：`max_single_buy`（单次购买限制）
- **移除字段**：`max_buy`（已被新限购系统完全替代）
- **新增关联**：`purchaseLimits`、`activePurchaseLimits`
- **新增方法**：
  - `canUserPurchaseWithLimits()`：统一限购检查
  - `updatePurchaseLimitCounters()`：更新限购计数

### 3. 数据库结构

#### 新增表

**kku_shop_purchase_limits（限购配置表）**
```sql
CREATE TABLE `kku_shop_purchase_limits` (
  `id` int unsigned NOT NULL AUTO_INCREMENT,
  `shop_item_id` int unsigned NOT NULL,
  `limit_type` tinyint NOT NULL,
  `limit_period` tinyint NOT NULL DEFAULT '0',
  `max_quantity` int NOT NULL,
  `name` varchar(100) NOT NULL,
  `description` text,
  `is_active` tinyint(1) NOT NULL DEFAULT '1',
  `sort_order` int NOT NULL DEFAULT '0',
  `created_at` timestamp NULL DEFAULT NULL,
  `updated_at` timestamp NULL DEFAULT NULL,
  PRIMARY KEY (`id`),
  KEY `shop_purchase_limits_shop_item_id_index` (`shop_item_id`),
  CONSTRAINT `shop_purchase_limits_shop_item_id_foreign` FOREIGN KEY (`shop_item_id`) REFERENCES `kku_shop_items` (`id`) ON DELETE CASCADE
);
```

**kku_shop_user_purchase_counters（用户购买计数表）**
```sql
CREATE TABLE `kku_shop_user_purchase_counters` (
  `id` int unsigned NOT NULL AUTO_INCREMENT,
  `limit_id` int unsigned NOT NULL,
  `user_id` int unsigned NOT NULL,
  `current_count` int NOT NULL DEFAULT '0',
  `last_reset_time` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `created_at` timestamp NULL DEFAULT NULL,
  `updated_at` timestamp NULL DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `shop_user_purchase_counters_limit_user_unique` (`limit_id`, `user_id`),
  CONSTRAINT `shop_user_purchase_counters_limit_id_foreign` FOREIGN KEY (`limit_id`) REFERENCES `kku_shop_purchase_limits` (`id`) ON DELETE CASCADE
);
```

#### 修改表

**kku_shop_items表字段变更**
```sql
-- 新增字段（如果表中还没有）
ALTER TABLE `kku_shop_items`
ADD COLUMN `max_single_buy` int NOT NULL DEFAULT '0' COMMENT '单次最大购买数量（0表示无限制）';

-- 移除已被替代的字段
ALTER TABLE `kku_shop_items`
DROP COLUMN `max_buy`;
```

### 4. 验证逻辑优化

#### ShopBuyLimitValidator更新
- **文件位置**：`app/Module/Shop/Validators/ShopBuyLimitValidator.php`
- **优化内容**：
  - 使用新的统一限购检查方法
  - 简化验证逻辑
  - 提供更准确的错误信息

#### BuyHandler更新
- **文件位置**：`app/Module/AppGame/Handler/Shop/BuyHandler.php`
- **新增功能**：
  - 购买成功后更新限购计数
  - 支持多种限购规则的计数更新

### 5. 后台管理功能

#### ShopPurchaseLimitRepository（数据仓库）
- **文件位置**：`app/Module/Shop/Repositorys/ShopPurchaseLimitRepository.php`
- **核心功能**：
  - 限购配置的CRUD操作
  - 批量查询优化
  - 状态切换管理

#### ShopPurchaseLimitController（控制器）
- **文件位置**：`app/Module/Shop/Controllers/ShopPurchaseLimitController.php`
- **管理功能**：
  - 限购配置管理
  - 批量状态切换
  - 配置复制功能

#### ShopItemRepository更新
- **文件位置**：`app/Module/Shop/Repositorys/ShopItemRepository.php`
- **新增功能**：
  - 商品选择选项获取
  - 支持限购配置快速跳转

### 6. 文档和说明

#### 功能说明文档
- **文件位置**：`app/Module/Shop/Docs/商店限购功能优化说明.md`
- **内容包含**：
  - 功能概述和使用说明
  - 数据库结构说明
  - 代码示例和最佳实践
  - 性能优化建议

## 核心特性

### 1. 灵活的限购配置
- 支持多种限购类型和周期
- 可为单个商品配置多个限购规则
- 支持规则优先级和状态管理

### 2. 自动计数管理
- 自动检测和重置过期计数
- 支持不同周期的计数重置
- 高效的批量查询优化

### 3. 向后兼容
- 保持与现有`max_buy`字段的兼容
- 不影响现有购买流程
- 渐进式功能升级

### 4. 性能优化
- 批量查询减少数据库访问
- 智能计数重置机制
- 索引优化提升查询效率

## 使用示例

### 设置单次购买限制
```php
$shopItem = ShopItem::find(1);
$shopItem->max_single_buy = 5; // 单次最多购买5个
$shopItem->save();
```

### 创建周期性限购
```php
ShopPurchaseLimit::create([
    'shop_item_id' => 1,
    'limit_type' => PURCHASE_LIMIT_TYPE::PERIODIC_PURCHASE,
    'limit_period' => PURCHASE_LIMIT_PERIOD::DAILY,
    'max_quantity' => 3,
    'name' => '每日限购',
    'is_active' => true,
]);
```

### 检查购买限制
```php
list($canPurchase, $errorMessage, $remainingQuantity) = 
    $shopItem->canUserPurchaseWithLimits($userId, $quantity);
```

## 部署说明

### 1. 数据库迁移
执行以下SQL文件：
- `app/Module/Shop/Databases/GenerateSql/modify_shop_items_add_single_buy_limit.sql`
- `app/Module/Shop/Databases/GenerateSql/shop_purchase_limits.sql`
- `app/Module/Shop/Databases/GenerateSql/shop_user_purchase_counters.sql`

### 2. 后台路由配置
需要添加限购配置管理的路由和菜单项。

### 3. 权限配置
为相关用户分配限购配置管理权限。

## 后台管理功能

### 1. 商品管理增强

#### ShopItemController更新
- **文件位置**：`app/Module/Shop/AdminControllers/ShopItemController.php`
- **新增功能**：
  - 商品列表显示"总限购"和"单次限购"列
  - 商品编辑表单新增"单次购买限制"字段
  - 每个商品行添加"限购配置"按钮
  - 商品详情页显示限购信息

#### 表格列更新
```php
$grid->column('max_buy', '总限购')->display(function ($maxBuy) {
    return $maxBuy > 0 ? $maxBuy : '无限制';
});
$grid->column('max_single_buy', '单次限购')->display(function ($maxSingleBuy) {
    return $maxSingleBuy > 0 ? $maxSingleBuy : '无限制';
});
```

#### 操作按钮
```php
$grid->actions(function (Grid\Displayers\Actions $actions) {
    $actions->append('<a href="' . admin_url('shop/purchase-limits?shop_item_id=' . $actions->getKey()) . '" class="btn btn-sm btn-outline-primary" title="限购配置">
        <i class="fa fa-cog"></i> 限购配置
    </a>');
});
```

### 2. 限购配置管理

#### ShopPurchaseLimitController
- **文件位置**：`app/Module/Shop/AdminControllers/ShopPurchaseLimitController.php`
- **路由注解**：`#[Resource('shop/purchase-limits', names: 'dcat.admin.shop.purchase-limits')]`
- **核心功能**：
  - 完整的CRUD操作界面
  - 支持商品搜索选择
  - 限购类型和周期配置
  - 表单验证和状态管理

#### 表格配置
```php
$grid->column('limit_type', '限购类型')->using(PURCHASE_LIMIT_TYPE::getAll());
$grid->column('limit_period', '限购周期')->using(PURCHASE_LIMIT_PERIOD::getAll());
$grid->column('is_active', '状态')->switch();
```

#### 表单验证
```php
$form->saving(function (Form $form) {
    if ($form->limit_type == PURCHASE_LIMIT_TYPE::SINGLE_PURCHASE->value
        && $form->limit_period != PURCHASE_LIMIT_PERIOD::PERMANENT->value) {
        return $form->response()->error('单次购买限制只能使用永久周期');
    }
});
```



### 4. 路由配置

#### ShopServiceProvider更新
- **文件位置**：`app/Module/Shop/Providers/ShopServiceProvider.php`
- **新增路由**：
```php
// 商店限购配置路由
$router->resource('shop/purchase-limits', \App\Module\Shop\AdminControllers\ShopPurchaseLimitController::class);
```

### 5. 菜单管理

#### 菜单添加命令
- **文件位置**：`app/Console/Commands/InsertShopPurchaseLimitMenu.php`
- **命令**：`php artisan admin:insert-shop-purchase-limit-menu`
- **菜单结构**：
  - 商店管理
    - 商店分类
    - 商店商品
    - 促销活动
    - 购买记录
    - **限购配置** ← 新增

### 6. 示例数据

#### 数据种子文件
- **文件位置**：`database/seeders/ShopPurchaseLimitSeeder.php`
- **命令**：`php artisan db:seed --class=ShopPurchaseLimitSeeder`
- **示例配置**：
  - 单次购买限制示例
  - 每日限购示例
  - 多重限购规则示例

### 7. 部署文档

#### 完整部署说明
- **文件位置**：`app/Module/Shop/Docs/后台管理部署说明.md`
- **包含内容**：
  - 数据库迁移步骤
  - 菜单配置命令
  - 权限设置说明
  - 使用指南
  - 故障排除

## 部署清单

### 数据库迁移
- [x] `shop_purchase_limits.sql` - 创建限购配置表
- [x] `shop_user_purchase_counters.sql` - 创建用户购买计数表
- [x] `remove_shop_items_max_buy_field.sql` - 移除已被替代的max_buy字段

### 后台控制器
- [x] `ShopItemController` - 商品管理增强（移除max_buy相关功能）
- [x] `ShopPurchaseLimitController` - 限购配置管理

### 路由配置
- [x] 限购配置资源路由

### 菜单和权限
- [x] 限购配置菜单
- [x] 菜单添加命令
- [x] 权限配置说明

### 文档和示例
- [x] 后台管理部署说明
- [x] 示例数据种子文件
- [x] 使用指南

## 总结

本次优化成功实现了商店系统的高级限购功能，提供了灵活、强大且易于管理的限购解决方案。新功能完全向后兼容，不影响现有业务流程，同时为未来的业务需求提供了良好的扩展性。

通过合理的数据库设计、优化的查询逻辑和完善的管理界面，新的限购系统能够满足各种复杂的业务场景需求。

### 核心亮点

1. **完整的后台管理界面**：提供直观易用的限购配置管理
2. **灵活的配置选项**：支持多种限购类型和周期组合
3. **智能表单验证**：确保配置的合理性和一致性
4. **完全替代传统限购**：移除了max_buy字段，使用更强大的新限购系统
5. **详细的部署文档**：确保功能能够顺利部署和使用