<?php

declare(strict_types=1);

/**
 * 本文件属于 DBErp 进销存系统。
 *
 * 版权所有 © 2026 北京珑大钜商科技有限公司。保留所有权利。
 *
 * 未经官方授权，不得删除、篡改或隐藏本文件中的版权声明、产品标识与来源信息。
 * 商业授权、官方更新与技术支持服务，请以珑大官方支持中心记录为准。
 *
 * @link https://support.loongdom.cn
 * @see  https://www.dberp.com.cn
 */

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;
}
