datahub/backend/app/Entity/Parse/EntityParse.php

<?php

declare(strict_types=1);

namespace App\Entity\Parse;

use App\Model\Model as Entity;
use App\Model\Company;
use App\Model\Platform;
use App\Model\Store;
use App\Entity\Parse\Traits\EntityParseHelper;
use Hyperf\Collection\LazyCollection;
use InvalidArgumentException;

/**
 * EntityParse 抽象类
 *
 * 使用工厂方法模式 + 延迟初始化
 * 提供消息解析的通用框架和默认实现
 *
 * @method static static create(array $data)
 */
abstract class EntityParse implements EntityParseInterface
{
    use EntityParseHelper;

    protected array $data;
    protected ?Platform $platform = null;
    protected ?Company $company = null;
    protected ?Store $store = null;

    /**
     * 禁止直接使用构造函数
     * 使用 create() 工厂方法创建实例
     */
    protected function __construct()
    {
        // 空构造函数，延迟初始化
    }

    /**
     * 工厂方法：创建解析器实例
     *
     * @param array $data
     * @return static
     * @throws InvalidArgumentException
     */
    public static function create(array $data): static
    {
        $instance = new static();
        $instance->data = $data;

        // 在初始化前先验证数据
        if (!$instance->messageValidate($data)) {
            throw new InvalidArgumentException('Message validation failed: required fields missing');
        }

        $instance->initialize();
        return $instance;
    }

    /**
     * 消息数据验证
     *
     * 默认实现：验证必需字段
     * 子类可以覆写以添加自定义验证逻辑
     *
     * @param array $data
     * @return bool
     */
    public function messageValidate(array $data): bool
    {
        // 验证必需字段
        $requiredFields = ['company_id', 'platform_id', 'store_id', 'unique_id', 'raw_data'];

        foreach ($requiredFields as $field) {
            if (!isset($data[$field])) {
                return false;
            }
        }

        return true;
    }

    /**
     * 延迟初始化
     * 在 data 设置后执行作用域匹配和验证
     *
     * @return void
     * @throws InvalidArgumentException
     */
    protected function initialize(): void
    {
        // 提取 metadata
        $metadata = [
            'company_id' => $this->data['company_id'],
            'platform_id' => $this->data['platform_id'],
            'store_id' => $this->data['store_id'],
            'unique_id' => $this->data['unique_id'],
        ];

        $this->platform = $this->platformScopeMatch($metadata);
        $this->company = $this->companyScopeMatch($metadata);
        $this->store = $this->storeScopeMatch($metadata);

        $this->validateScope();
    }

    /**
     * 验证作用域对象是否有效
     *
     * @return void
     * @throws InvalidArgumentException
     */
    protected function validateScope(): void
    {
        if (!$this->platform instanceof Platform || !isset($this->platform->id)) {
            throw new InvalidArgumentException('Platform is undefined or invalid');
        }

        if (!$this->company instanceof Company || !isset($this->company->id)) {
            throw new InvalidArgumentException('Company is undefined or invalid');
        }

        if (!$this->store instanceof Store || !isset($this->store->id)) {
            throw new InvalidArgumentException('Store is undefined or invalid');
        }
    }

    /**
     * 平台作用域匹配 - 提供默认实现
     *
     * 从 metadata 中提取平台信息
     * 子类可以覆盖此方法以实现自定义逻辑
     *
     * @param array $metadata
     * @return Platform
     * @throws InvalidArgumentException
     */
    public function platformScopeMatch(array $metadata): Platform
    {
        return $this->extractPlatformFromMetadata($metadata);
    }

    /**
     * 实体匹配 - 提供默认实现
     *
     * 从 metadata 中提取实体类型
     * 子类可以覆盖此方法以实现自定义逻辑
     *
     * @param array $metadata
     * @return Entity
     * @throws InvalidArgumentException
     */
    public function entityMatch(array $metadata): Entity
    {
        return $this->extractEntityFromMetadata($metadata);
    }

    /**
     * 唯一标识符提取 - 提供默认实现
     *
     * 默认从 metadata 中提取 unique_id
     * 子类可以覆盖此方法以实现自定义逻辑
     *
     * @param array $metadata
     * @return string|int
     * @throws InvalidArgumentException
     */
    public function entityUniqueIdentifierExtract(array $metadata): string|int
    {
        return $metadata['unique_id'] ?? throw new InvalidArgumentException('unique_id not found in metadata');
    }

    /**
     * 公司作用域匹配 - 抽象方法
     *
     * 必须由子类实现，因为不同平台的公司识别逻辑不同
     *
     * @param array $metadata
     * @return Company
     */
    abstract public function companyScopeMatch(array $metadata): Company;

    /**
     * 店铺作用域匹配 - 抽象方法
     *
     * 必须由子类实现，因为不同平台的店铺识别逻辑不同
     *
     * @param array $metadata
     * @return Store
     */
    abstract public function storeScopeMatch(array $metadata): Store;

    /**
     * 实体数据映射 - 抽象方法
     *
     * 必须由子类实现，因为不同平台的数据结构不同
     *
     * @param array $rawData
     * @return LazyCollection
     */
    abstract public function entityMap(array $rawData): LazyCollection;

    // ==================== Getter 方法 ====================

    /**
     * 获取消息数据
     *
     * @return array
     */
    public function getData(): array
    {
        return $this->data;
    }

    /**
     * 获取平台对象
     *
     * @return Platform
     */
    public function getPlatform(): Platform
    {
        return $this->platform;
    }

    /**
     * 获取公司对象
     *
     * @return Company
     */
    public function getCompany(): Company
    {
        return $this->company;
    }

    /**
     * 获取店铺对象
     *
     * @return Store
     */
    public function getStore(): Store
    {
        return $this->store;
    }
}