<?php

declare(strict_types=1);

namespace App\Entity\Parse;

use App\Model\Company;
use App\Model\Platform;
use App\Model\Store;
use App\Model\Model as Entity;
use Hyperf\Collection\LazyCollection;

/**
 * EntityParseInterface 接口
 *
 * 定义消息解析器的标准接口
 */
interface EntityParseInterface
{
    /**
     * 消息数据验证
     *
     * 验证消息数据是否包含必需字段
     *
     * @param array $data
     * @return bool
     */
    public function messageValidate(array $data): bool;

    /**
     * 公司作用域匹配
     *
     * @param array $metadata
     * @return Company
     */
    public function companyScopeMatch(array $metadata): Company;

    /**
     * 平台作用域匹配
     *
     * @param array $metadata
     * @return Platform
     */
    public function platformScopeMatch(array $metadata): Platform;

    /**
     * 店铺作用域匹配
     *
     * @param array $metadata
     * @return Store
     */
    public function storeScopeMatch(array $metadata): Store;

    /**
     * 实体类型匹配
     *
     * 根据 metadata 返回实体模板实例
     *
     * @param array $metadata
     * @return Entity
     */
    public function entityMatch(array $metadata): Entity;

    /**
     * 实体数据映射
     *
     * 将原始数据转换为可填充到 Model 的数据集合
     *
     * @param array $rawData
     * @return LazyCollection
     */
    public function entityMap(array $rawData): LazyCollection;

    /**
     * 提取实体唯一标识符， 根据字段查找数据库中匹配的唯一实体
     *
     * @param array $metadata
     * @return array 提供给 Model::query()->where() 作为参数使用, 每个数组元素的键值分别作为字段名和值
     * 如果需要多个字段来确认唯一性，则构造多个字段元素
     */
    public function entityUniqueIdentifierExtract(array $metadata): array;

    /**
     * 获取消息数据
     *
     * @return array
     */
    public function getData(): array;

    /**
     * 获取平台对象
     *
     * @return Platform
     */
    public function getPlatform(): Platform;

    /**
     * 获取公司对象
     *
     * @return Company
     */
    public function getCompany(): Company;

    /**
     * 获取店铺对象
     *
     * @return Store
     */
    public function getStore(): Store;
}