fastadmin_tailored/docs/折扣活动查询使用说明.md

折扣活动查询功能使用说明

功能概述

基于 shop_activity_sku 表实现的商品折扣查询功能，支持查询当前时间段内参与折扣活动的商品信息，包括折扣价格、折扣力度、活动剩余时间等。

数据库表结构

CREATE TABLE `shop_activity_sku` (
  `id` int(11) unsigned NOT NULL AUTO_INCREMENT COMMENT 'ID',
  `activity_id` int(11) unsigned NOT NULL COMMENT '折扣活动ID',
  `goods_id` int(11) unsigned NOT NULL COMMENT '商品ID',
  `sku_id` int(11) unsigned NOT NULL COMMENT '规格ID，单规格商品填0',
  `discount` decimal(10,1) NOT NULL DEFAULT '9.0' COMMENT '折扣值',
  `discount_price` decimal(10,2) NOT NULL DEFAULT '0.00' COMMENT '折扣后价格',
  `stocks` int(11) DEFAULT '0' COMMENT '参与折扣的库存数量',
  `order_count` int(11) DEFAULT '0' COMMENT '成交订单数',
  `order_amount` decimal(10,2) DEFAULT '0.00' COMMENT '成交金额',
  `refund_amount` decimal(10,2) DEFAULT '0.00' COMMENT '退款金额',
  `sale_quantity` int(11) DEFAULT '0' COMMENT '销售数量',
  `customer_count` int(11) DEFAULT '0' COMMENT '成交人数',
  `status` tinyint(4) NOT NULL DEFAULT '1' COMMENT '状态',
  `createtime` bigint(20) NOT NULL DEFAULT '0' COMMENT '创建时间',
  `updatetime` bigint(20) NOT NULL DEFAULT '0' COMMENT '更新时间',
  `deletetime` bigint(20) NOT NULL DEFAULT '0' COMMENT '删除时间',
  PRIMARY KEY (`id`),
  KEY `idx_goods_spec` (`goods_id`,`sku_id`) COMMENT '商品规格索引'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='活动规格关联表';

API 接口

1. 获取折扣商品列表

接口地址: /api/discount/index

请求方式: GET

请求参数:

• page (可选): 页码，默认1
• pageSize (可选): 每页数量，默认10，最大50
• goods_ids (可选): 指定商品ID，多个用逗号分隔

响应示例:

{
    "code": 1,
    "msg": "获取成功",
    "time": "2024-01-01 12:00:00",
    "data": {
        "list": [
            {
                "goods_id": 1,
                "title": "商品标题",
                "sub_title": "商品副标题",
                "image": "https://example.com/image.jpg",
                "original_price": "99.00",
                "market_price": "129.00",
                "goods_stocks": 100,
                "sales": 50,
                "spec_type": 1,
                "activity_id": 1,
                "activity_name": "新年大促",
                "start_time": 1704067200,
                "end_time": 1704153600,
                "remaining_time": {
                    "days": 5,
                    "hours": 12,
                    "minutes": 30,
                    "seconds": 45
                },
                "discount_info": [
                    {
                        "activity_sku_id": 1,
                        "sku_id": 0,
                        "discount": 8.0,
                        "discount_price": "79.20",
                        "discount_stocks": 50,
                        "sale_quantity": 10
                    }
                ]
            }
        ],
        "total": 1,
        "page": 1,
        "pageSize": 10,
        "totalPages": 1
    }
}

2. 获取指定商品折扣信息

接口地址: /api/discount/goods

请求方式: GET

请求参数:

• goods_id (必需): 商品ID
• sku_id (可选): 规格ID，单规格商品传0或不传

响应示例:

{
    "code": 1,
    "msg": "获取成功",
    "time": "2024-01-01 12:00:00",
    "data": {
        "activity_sku_id": 1,
        "discount": 8.0,
        "discount_price": "79.20",
        "discount_stocks": 50,
        "sale_quantity": 10,
        "activity_id": 1,
        "activity_name": "新年大促",
        "start_time": 1704067200,
        "end_time": 1704153600,
        "remaining_time": {
            "days": 5,
            "hours": 12,
            "minutes": 30,
            "seconds": 45
        }
    }
}

3. 批量获取商品折扣信息

接口地址: /api/discount/batch

请求方式: GET

请求参数:

• goods_ids (必需): 商品ID列表，用逗号分隔

响应示例:

{
    "code": 1,
    "msg": "获取成功",
    "time": "2024-01-01 12:00:00",
    "data": {
        "1": [
            {
                "goods_id": 1,
                "sku_id": 0,
                "activity_sku_id": 1,
                "discount": 8.0,
                "discount_price": "79.20",
                "discount_stocks": 50,
                "sale_quantity": 10,
                "activity_id": 1,
                "activity_name": "新年大促"
            }
        ]
    }
}

服务类使用

DiscountService 类方法

use app\common\Service\DiscountService;

// 1. 获取当前时间段内的折扣商品
$discountGoods = DiscountService::getCurrentDiscountGoods();

// 指定商品ID查询
$discountGoods = DiscountService::getCurrentDiscountGoods([1, 2, 3]);

// 限制返回数量
$discountGoods = DiscountService::getCurrentDiscountGoods([], 20);

// 2. 获取指定商品的折扣信息
$discountInfo = DiscountService::getGoodsDiscountInfo(1, 0); // 商品ID=1，单规格

// 3. 批量获取商品折扣信息
$batchDiscount = DiscountService::getBatchGoodsDiscountInfo([1, 2, 3]);

// 4. 检查商品是否有折扣
$hasDiscount = DiscountService::hasActiveDiscount(1, 0);

// 5. 计算折扣价格
$discountPrice = DiscountService::calculateDiscountPrice(100, 8.0); // 原价100，8折 = 80

// 6. 获取活动剩余时间
$remainingSeconds = DiscountService::getActivityRemainingTime(1704153600);

// 7. 格式化剩余时间
$timeFormat = DiscountService::formatRemainingTime(1704153600);
// 返回: ['days' => 5, 'hours' => 12, 'minutes' => 30, 'seconds' => 45]

商品模型扩展

商品模型现在自动包含折扣信息：

use app\common\model\Goods;

$goods = Goods::get(1);

// 获取折扣信息（自动追加属性）
$discountInfo = $goods->discount_info;

// 检查是否有折扣
$hasDiscount = $goods->hasDiscount(0); // 单规格商品

// 获取最低折扣价格
$minPrice = $goods->getMinDiscountPrice();

// 获取最大折扣力度
$maxDiscount = $goods->getMaxDiscount();

使用场景

1. 商品列表页显示折扣标签

$goodsList = Goods::where('status', 1)->select();

foreach ($goodsList as $goods) {
    if ($goods->hasDiscount()) {
        $minPrice = $goods->getMinDiscountPrice();
        $maxDiscount = $goods->getMaxDiscount();
        echo "商品：{$goods->title}，折扣价：{$minPrice}，最大折扣：{$maxDiscount}折";
    }
}

2. 商品详情页显示折扣信息

$goods = Goods::get($goodsId);
$discountInfo = $goods->discount_info;

if (!empty($discountInfo)) {
    foreach ($discountInfo as $discount) {
        echo "SKU ID: {$discount['sku_id']}, 折扣: {$discount['discount']}折, 
              折扣价: {$discount['discount_price']}, 剩余库存: {$discount['discount_stocks']}";
    }
}

3. 折扣商品专题页

// 获取所有参与折扣的商品
$discountGoods = DiscountService::getCurrentDiscountGoods();

// 按折扣力度排序展示
usort($discountGoods, function($a, $b) {
    $aDiscount = min(array_column($a['discount_info'], 'discount'));
    $bDiscount = min(array_column($b['discount_info'], 'discount'));
    return $aDiscount <=> $bDiscount;
});

注意事项

1. 时间判断: 系统自动根据当前时间判断活动是否进行中
2. 库存检查: 只返回有折扣库存（stocks > 0）的商品
3. 状态过滤: 只查询活动状态为进行中且商品状态正常的数据
4. 缓存优化: 商品模型中使用静态缓存避免重复查询
5. 多规格支持: 单规格商品sku_id填0，多规格商品填具体规格ID
6. 性能考虑: 大量商品查询时建议使用批量接口

扩展建议

1. 可以根据需要添加缓存机制提升查询性能
2. 可以添加更多排序方式（按折扣力度、价格等）
3. 可以添加分类筛选功能
4. 可以添加搜索功能
5. 可以添加活动预告功能（即将开始的活动）