<?php

declare(strict_types=1);

namespace App\Services\Reports\Providers;

use App\Models\ReportJob;

/**
 * Источник данных для отчёта. Один provider на каждый ReportJob.type.
 *
 * Provider возвращает headers + rows; сериализация в csv/xlsx/json/pdf — задача
 * Formatter'а (см. App\Services\Reports\Formatters\ReportFormatter). Это
 * избавляет от дубля 4×4=16 классов под комбинации (type × format) — вместо
 * этого 4 + 4 = 8.
 */
interface ReportDataProvider
{
    /**
     * Названия колонок для шапки таблицы. Используются всеми форматами:
     * CSV — первая строка; XLSX — bold-row 1; JSON — ключи; PDF — th-row.
     *
     * @return array<int, string>
     */
    public function headers(): array;

    /**
     * Строки данных. Каждая строка — массив scalar-значений по индексу
     * соответствующих headers. NULL-значения сериализуются формат-специфично
     * (CSV — пустая строка; JSON — null; XLSX — пустая ячейка).
     *
     * @return array<int, array<int, scalar|null>>
     */
    public function rows(ReportJob $job): array;

    /**
     * Slug для filename части (без расширения). Например "deals" → итоговый
     * файл будет "reports/{tenant_id}/{job_id}.{ext}". Filename также можно
     * использовать в Content-Disposition при скачивании (этап 3).
     */
    public function slug(): string;
}
