<?php

declare(strict_types=1);

namespace App\Platform;

/**
 * 退款解析器契约接口
 *
 * 定义所有电商平台退款解析器必须实现的方法
 * 适用于：Shopee、Tmall、JD 等所有电商平台
 */
interface RefundContract
{
    /**
     * 获取退款状态 ID
     *
     * 将平台退款状态映射到本地 RefundStatus 枚举
     *
     * @param string $platform_status 平台退款状态字符串
     * @return int 本地退款状态 ID
     */
    public function getRefundStatusId(string $platform_status): int;

    /**
     * 获取退款类型 ID
     *
     * 根据退款记录判断退款类型（退货退款、仅退款等）
     *
     * @param array $record 单条退款原始数据
     * @return int 本地退款类型 ID
     */
    public function getRefundTypeId(array $record): int;

    /**
     * 是否有父退款
     *
     * 判断平台是否具有父子退款结构
     * Shopee 有父退款（return 包含多个 item），Tmall 没有
     *
     * @return bool
     */
    public function hasParentRefund(): bool;

    /**
     * 从原始数据格式化退款子项
     *
     * @param array $raw_data 原始数据数组
     * @param array|null $platform_refund_id_to_local_refund_id_map 平台退款 ID => 本地数据库退款 ID 映射
     * @return array 解析后的退款子项数据数组
     */
    public function formatRefundItemsFromRaw(array $raw_data, ?array $platform_refund_id_to_local_refund_id_map): array;
}