<?php

declare(strict_types=1);

namespace App\Platform;

/**
 * 订单解析器契约接口
 *
 * 定义所有电商平台订单解析器必须实现的方法
 * 适用于：Shopee、Tmall、JD 等所有电商平台
 */
interface OrderContract
{
    /**
     * 从原始数据格式化订单子项
     *
     * @param array $raw_data 原始数据数组
     * @param array $platform_orders_id_to_local_db_order_id_map 平台订单 ID => 本地数据库订单 ID 映射
     * @return array 解析后的订单子项数据数组，每个元素包含：
     *     - company_id, platform_id, store_id
     *     - platform_order_id, sub_order_id
     *     - product_id, platform_product_id
     *     - unit_price, quantity, discount, total
     *     等字段
     */
    public function formatOrderItemsFromRaw(array $raw_data, array $platform_orders_id_to_local_db_order_id_map): array;

    /**
     * 获取本地订单状态 ID
     *
     * @param string $platform_order_status 平台订单状态字符串
     * @return int 本地订单状态 ID
     */
    public function getOrderStatusId(string $platform_order_status): int;

    /**
     * 获取支付方式 ID
     *
     * @return int 支付方式 ID
     */
    public function getPaymentMethodId(): int;
}