add contract for product and refund parse

2026-03-05 10:07:51 +08:00
parent d93fdee203
commit 4c49c2b71c
9 changed files with 122 additions and 38 deletions
@@ -0,0 +1,53 @@
+<?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;
+}