datahub/backend/app/Platform/AbstractOrderParse.php

<?php

declare(strict_types=1);

namespace App\Platform;

use App\Entity\Parse\EntityParse;
use InvalidArgumentException;

/**
 * 订单解析器抽象基类
 *
 * 继承 EntityParse 的通用能力，并实现 OrderContract 契约
 * 提供订单解析的通用方法和辅助函数
 */
abstract class AbstractOrderParse extends EntityParse implements OrderContract
{
    /**
     * 从原始数据格式化订单子项（抽象方法，由子类实现）
     * 
     * 每个平台有自己的订单子项数据结构，需要各自实现具体的解析逻辑
     * 
     * @var $platform_orders_id_to_local_db_order_id_map 
     *  - 为 平台订单 id 与 本地父级订单 id 的映射数组
     *  - 用来维护父订单和值订单的关系
     * 
     */
    abstract public function formatOrderItemsFromRaw(array $raw_data, array $platform_orders_id_to_local_db_order_id_map): array;

    /**
     * 获取本地订单状态 ID（抽象方法，由子类实现）
     */
    abstract public function getOrderStatusId(string $platform_order_status): int;

    /**
     * 获取支付方式 ID（抽象方法，由子类实现）
     */
    abstract public function getPaymentMethodId(): int;

    /**
     * 通用辅助方法：验证订单必需字段
     *
     * @param array $orderData 订单原始数据
     * @param array $requiredFields 必需字段列表
     * @throws InvalidArgumentException
     */
    protected function validateOrderFields(array $orderData, array $requiredFields = []): void
    {
    }

    /**
     * 通用辅助方法：格式化货币金额
     *
     * @param float|int|string|null $amount 金额
     * @param int $decimals 小数位数，默认 2 位
     * @return float 格式化后的金额
     */
    protected function formatAmount(float|int|string|null $amount, int $decimals = 2): float
    {
        return round((float)($amount ?? 0), $decimals);
    }


}