# Shop模块

Shop模块是游戏中的商店系统，提供商品展示、购买等功能。

## 1. 模块概述

Shop模块负责管理游戏中的商店系统，包括商品分类、商品信息、促销活动、购买记录等。该模块与GameItems模块紧密集成，通过商店系统，玩家可以使用游戏货币购买各种物品，并可以享受促销折扣。

## 2. 目录结构

```
app/Module/Shop/
├── AdminControllers/        # 后台管理控制器
│   ├── Helper/              # 控制器辅助类
│   ├── ShopCategoryController.php  # 商店分类控制器
│   ├── ShopItemController.php      # 商店商品控制器
│   ├── ShopPromotionController.php # 促销活动控制器
│   └── ShopPurchaseLogController.php  # 购买记录控制器
├── Events/                  # 事件类
│   └── ShopItemPurchased.php  # 商品购买事件
├── Logics/                  # 业务逻辑类
│   └── ShopLogic.php        # 商店逻辑类
├── Models/                  # 数据模型
│   ├── ShopCategory.php     # 商店分类模型
│   ├── ShopItem.php         # 商店商品模型
│   ├── ShopPromotion.php    # 促销活动模型
│   ├── ShopPromotionItem.php # 促销商品关联模型
│   └── ShopPurchaseLog.php  # 购买记录模型
├── Providers/               # 服务提供者
│   └── ShopServiceProvider.php  # 商店服务提供者
├── Repositorys/             # 数据仓库
│   ├── ShopCategoryRepository.php  # 商店分类数据仓库
│   ├── ShopItemRepository.php      # 商店商品数据仓库
│   ├── ShopPromotionRepository.php # 促销活动数据仓库
│   └── ShopPurchaseLogRepository.php  # 购买记录数据仓库
├── Services/                # 服务类
│   └── ShopService.php      # 商店服务类
└── README.md                # 模块文档
```

## 3. 核心组件

### 3.1 模型

- **ShopCategory**: 商店分类模型，管理商店中的商品分类
- **ShopItem**: 商店商品模型，管理商店中的商品信息
- **ShopPromotion**: 促销活动模型，管理商店中的促销活动
- **ShopPromotionItem**: 促销商品关联模型，管理促销活动与商品的关联
- **ShopPurchaseLog**: 购买记录模型，记录用户的购买历史

### 3.2 服务

- **ShopService**: 商店服务类，提供商店相关的服务方法，如获取商品列表、购买商品、管理促销活动等

### 3.3 逻辑

- **ShopLogic**: 商店逻辑类，处理商店相关的业务逻辑，如检查购买限制、计算折扣价格等

### 3.4 事件

- **ShopItemPurchased**: 商品购买事件，当用户成功购买商品时触发

## 4. 主要功能

### 4.1 商品管理

- 商品分类管理：创建、编辑、删除商品分类
- 商品信息管理：创建、编辑、删除商品信息
- 商品上下架：设置商品的上架时间和下架时间

### 4.2 促销活动管理

- 促销活动创建：创建固定折扣或百分比折扣的促销活动
- 促销商品管理：为促销活动添加或移除商品
- 自定义折扣：为特定商品设置自定义折扣值
- 促销时间控制：设置促销活动的开始时间和结束时间

### 4.3 商品购买

- 商品购买：用户使用游戏货币购买商品
- 折扣价格：支持促销折扣价格
- 购买限制：设置商品的最大购买数量
- 购买记录：记录用户的购买历史

### 4.4 商店查询

- 商品列表：获取商店中的商品列表
- 分类列表：获取商店中的分类列表
- 促销活动：获取当前有效的促销活动
- 商品详情：获取商品的详细信息，包括折扣价格

## 5. 数据库表结构

### 5.1 shop_categories表

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| id | int | 主键 |
| name | varchar | 分类名称 |
| code | varchar | 分类编码（唯一） |
| icon | varchar | 分类图标 |
| sort_order | int | 排序权重 |
| parent_id | int | 父分类ID |
| is_active | tinyint | 是否激活 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

### 5.2 shop_items表

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| id | int | 主键 |
| name | varchar | 商品名称 |
| description | text | 商品描述 |
| category_id | int | 分类ID |
| category_name | varchar | 分类名称（字符串格式，区别于现有分类机制） |
| consume_group_id | int | 消耗组ID，外键关联kku_game_consume_groups表 |
| reward_group_id | int | 奖励组ID，外键关联kku_game_reward_groups表 |
| max_single_buy | int | 单次最大购买数量（0表示无限制） |
| is_active | tinyint | 是否激活 |
| sort_order | int | 排序权重 |
| display_attributes | json | 展示属性，以JSON格式存储键值对，用于界面展示和描述的属性 |
| start_time | timestamp | 上架时间 |
| end_time | timestamp | 下架时间 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

#### 5.2.1 display_attributes字段说明

display_attributes字段存储商品的展示属性，包含以下属性：

| 属性名 | 类型 | 说明 |
| --- | --- | --- |
| icon | string | 商品图标URL地址 |
| color | string | 商品颜色代码，如 #FF0000 |
| tag | string | 商品标签文字 |
| background | string | 背景图片URL地址 |
| badge | string | 特殊标记文字 |
| quality | int | 品质等级，1-10 |
| is_hot | bool | 是否热门商品 |
| is_new | bool | 是否新品 |
| is_limited | bool | 是否限时商品 |

### 5.3 shop_purchase_logs表

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| id | int | 主键 |
| user_id | int | 用户ID |
| shop_item_id | int | 商品ID |
| item_id | int | 物品ID |
| quantity | int | 购买数量 |
| price | int | 单价 |
| total_price | int | 总价 |
| currency_id | int | 货币类型ID |
| purchase_time | timestamp | 购买时间 |
| ip_address | varchar | 购买IP地址 |
| device_info | varchar | 设备信息 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

### 5.4 shop_promotions表

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| id | int | 主键 |
| name | varchar | 促销名称 |
| description | text | 促销描述 |
| banner | varchar | 促销横幅图片 |
| discount_type | tinyint | 折扣类型（1:固定折扣, 2:百分比折扣） |
| discount_value | int | 折扣值 |
| is_active | tinyint | 是否激活 |
| sort_order | int | 排序权重 |
| start_time | timestamp | 开始时间 |
| end_time | timestamp | 结束时间 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

### 5.5 shop_promotion_items表

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| id | int | 主键 |
| promotion_id | int | 促销ID |
| shop_item_id | int | 商品ID |
| custom_discount_value | int | 自定义折扣值 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

## 6. 使用示例

### 6.1 获取商店商品列表

```php
use App\Module\Shop\Services\ShopService;

// 获取所有商品
$shopItems = ShopService::getShopItems();

// 获取指定分类的商品
$shopItems = ShopService::getShopItems(['category_id' => 1]);

// 获取促销商品
$shopItems = ShopService::getShopItems(['only_promotion' => true]);

// 获取指定促销活动的商品
$shopItems = ShopService::getShopItems(['promotion_id' => 1]);
```

### 6.2 购买商品

```php
use App\Module\Shop\Services\ShopService;

// 购买商品
$result = ShopService::buyShopItem($userId, $shopItemId, $quantity);

if ($result) {
    // 购买成功
    $itemId = $result['item']['id'];
    $itemName = $result['item']['name'];
    $itemQuantity = $result['item']['quantity'];
    $totalPrice = $result['total_price'];
} else {
    // 购买失败
}
```

### 6.3 获取用户购买记录

```php
use App\Module\Shop\Services\ShopService;

// 获取用户所有购买记录
$purchaseLogs = ShopService::getUserPurchaseHistory($userId);

// 获取用户指定商品的购买记录
$purchaseLogs = ShopService::getUserPurchaseHistory($userId, ['shop_item_id' => $shopItemId]);
```

### 6.4 获取促销活动

```php
use App\Module\Shop\Services\ShopService;

// 获取所有促销活动
$promotions = ShopService::getPromotions();

// 获取当前有效的促销活动
$promotions = ShopService::getPromotions(['only_valid' => true]);

// 获取指定分类的促销活动
$promotions = ShopService::getPromotions(['category_id' => 1]);
```

### 6.5 获取商品折扣价格

```php
use App\Module\Shop\Services\ShopService;

// 获取商品价格信息
$priceInfo = ShopService::getItemPriceInfo($shopItemId);

// 价格信息包含原价、折扣价、是否有折扣、折扣百分比、促销信息等
$originalPrice = $priceInfo['original_price'];
$discountedPrice = $priceInfo['discounted_price'];
$hasDiscount = $priceInfo['has_discount'];
$discountPercentage = $priceInfo['discount_percentage'];
$promotion = $priceInfo['promotion'];
```