<?php

declare(strict_types=1);

namespace App\Business\Integration\Contracts;

use App\Business\Integration\DTOs\SyncContext;

/**
 * 外部渠道同步适配入口（占位）。
 *
 * 真实同步任务、重试与补偿应在 Integration 域实现；禁止在 Filament 页面内写同步逻辑。
 */
interface ChannelSyncAdapterInterface
{
    /**
     * @return list<string> 人类可读的能力说明（占位阶段用于自检与文档化）
     */
    public function describeCapabilities(): array;

    /**
     * @return list<array<string, mixed>>
     */
    public function pullProducts(array $filters = []): array;

    /**
     * @return list<array<string, mixed>>
     */
    public function pullCustomers(array $filters = []): array;

    /**
     * @return list<array<string, mixed>>
     */
    public function pullOrders(array $filters = []): array;

    /**
     * @param  array<string, mixed>  $payload
     * @return array<string, mixed>
     */
    public function pushInventory(array $payload, SyncContext $context): array;
}
