kknongchang_2506/app/Module/Shop

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 获取商店商品列表

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 购买商品

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 获取用户购买记录

use App\Module\Shop\Services\ShopService;

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

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

6.4 获取促销活动

use App\Module\Shop\Services\ShopService;

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

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

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

6.5 获取商品折扣价格

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'];