概述

本文档详细介绍 EBAOZU 系统的商品业务处理流程，涵盖商品主表数据模型、多规格/单规格 SKU 体系、上下架流转、库存扣减与回退机制、商品分类与评价管理。

---

商品服务分层与架构

app/services/product/
├── product/
│   ├── StoreProductServices.php            # 商品核心业务服务
│   ├── StoreProductAttrServices.php        # 商品规格项服务
│   ├── StoreProductAttrValueServices.php   # 商品规格值（SKU）服务
│   ├── StoreProductDescriptionServices.php # 商品图文详情服务
│   ├── StoreProductRelationServices.php    # 商品关联服务（收藏、足迹）
│   └── StoreProductReplyServices.php       # 商品评价服务
├── category/
│   └── StoreCategoryServices.php           # 商品分类服务
├── brand/
│   └── StoreBrandServices.php              # 商品品牌服务
└── shipping/
    └── ShippingTemplatesServices.php       # 运费模板服务

---

商品核心模型与关系

商品主模型 app\model\product\product\StoreProduct：

namespace app\model\product\product;

use crmeb\basic\BaseModel;

class StoreProduct extends BaseModel
{
    protected $name = 'store_product';
    protected $pk = 'id';

    // 关联规格项
    public function attr()
    {
        return $this->hasMany(StoreProductAttr::class, 'product_id', 'id');
    }

    // 关联规格值 (SKU)
    public function attrValue()
    {
        return $this->hasMany(StoreProductAttrValue::class, 'product_id', 'id');
    }

    // 关联详情描述
    public function description()
    {
        return $this->hasOne(StoreProductDescription::class, 'product_id', 'id');
    }
}

---

商品核心生命周期

商品创建与更新 (StoreProductServices)

遵循 Controller → Services → DAO → Model 分层规范，在事务内原子化完成商品主表、规格明细及富文本详情的保存：

public function save(array $data)
{
    return $this->transaction(function() use ($data) {
        // 1. 组装主表数据
        $productData = $this->setProductData($data);
        $product = $this->dao->save($productData);
        $productId = (int)$product->id;

        // 2. 保存规格项与 SKU 列表
        if ($data['spec_type'] == 1) {
            $this->saveProductAttr($productId, $data['items'], $data['attrs']);
        } else {
            $this->saveProductAttrSingle($productId, $data);
        }

        // 3. 保存商品详情描述
        $this->saveDescription($productId, $data['description'] ?? '');

        // 4. 触发商品创建事件
        event('product.create', [$product]);

        return $product;
    });
}

商品上下架与软删除

• 上下架状态 (is_show)：通过 setShow(int $id, int $isShow) 控制，变更时触发 product.status 事件。
• 软删除 (is_del)：删除商品时仅标记 is_del = 1，商品移入回收站；彻底删除需在事务内清理 SKU 与分类关联。

库存管理与扣减

• 下单库存扣减：下单时原子扣减 SKU 表库存与主表总库存，并增加销量。
• 取消与退款回退：订单取消或退款通过事务安全回退对应 SKU 库存，并扣减对应销量。

---

商品相关事件清单

事件名称	说明	参数
product.create	商品创建完成	[$product]
product.update	商品修改完成	[$id, $data]
product.delete	商品移入回收站/删除	[$id]
product.status	商品上下架状态变更	[$id, $isShow]
product.reply	用户评价商品	[$replyData]

---

二开注意事项

1. 严格分层：禁止在 Controller 中直接操作 Model，所有查询和修改必须调用对应 ProductServices 或 ProductDao。
2. 多规格一致性：更新商品规格时，必须保证 unique 标识的稳定性，防止历史订单快照中的 SKU 匹配失效。
3. 缓存维护：商品信息修改后，应及时清理商品详情与列表的 Redis 缓存。