Реализация логирования и отчётов о результатах импорта товаров

Реализация логирования и отчётов о результатах импорта товаров

Без логирования импорт — чёрный ящик. Что-то пошло не так ночью, менеджер с утра видит расхождения в каталоге, но понять причину невозможно. Хорошее логирование фиксирует каждый шаг, а отчёт даёт однозначный ответ: что было, что изменилось, что сломалось.

Что нужно фиксировать

На уровне запуска импорта:

• Время старта и завершения
• Источник данных, тип, URL/путь к файлу
• Итоговые счётчики: создано / обновлено / пропущено / ошибок
• Статус: success / partial / failed
• Пользователь, запустивший импорт (если вручную)

На уровне отдельной строки:

• Номер строки / SKU
• Тип операции: create / update / skip / error
• Поля, которые изменились (diff)
• Сообщение об ошибке (если есть)

Схема БД для логов

CREATE TABLE import_runs (
    id              serial PRIMARY KEY,
    source_id       int REFERENCES import_sources(id),
    status          varchar(20) DEFAULT 'pending',  -- pending | processing | success | partial | failed
    trigger         varchar(20) DEFAULT 'scheduled', -- scheduled | manual | webhook
    triggered_by    int REFERENCES users(id),
    file_name       varchar(500),
    file_size       bigint,
    total_rows      int DEFAULT 0,
    created_count   int DEFAULT 0,
    updated_count   int DEFAULT 0,
    skipped_count   int DEFAULT 0,
    errors_count    int DEFAULT 0,
    started_at      timestamptz,
    completed_at    timestamptz,
    duration_ms     int,
    error_message   text,
    created_at      timestamptz DEFAULT now()
);

CREATE TABLE import_row_logs (
    id          bigserial PRIMARY KEY,
    import_id   int REFERENCES import_runs(id) ON DELETE CASCADE,
    line_number int,
    sku         varchar(100),
    operation   varchar(10),  -- create | update | skip | error
    changed_fields jsonb,     -- {"price": {"old": 100, "new": 120}}
    error_code  varchar(50),
    error_msg   text,
    created_at  timestamptz DEFAULT now()
);

CREATE INDEX import_row_logs_import_id_idx ON import_row_logs (import_id);
CREATE INDEX import_row_logs_sku_idx       ON import_row_logs (sku);

Логгер импорта

class ImportLogger
{
    private ImportRun $run;
    private array     $rowBuffer = [];
    private int       $bufferSize = 500;

    public function start(int $sourceId, string $trigger, ?int $userId): void
    {
        $this->run = ImportRun::create([
            'source_id'    => $sourceId,
            'status'       => 'processing',
            'trigger'      => $trigger,
            'triggered_by' => $userId,
            'started_at'   => now(),
        ]);
    }

    public function logRow(
        int    $line,
        string $sku,
        string $operation,
        array  $changedFields = [],
        ?string $errorMsg = null,
        ?string $errorCode = null
    ): void {
        $this->rowBuffer[] = [
            'import_id'     => $this->run->id,
            'line_number'   => $line,
            'sku'           => $sku,
            'operation'     => $operation,
            'changed_fields'=> $changedFields ? json_encode($changedFields) : null,
            'error_code'    => $errorCode,
            'error_msg'     => $errorMsg,
            'created_at'    => now()->toDateTimeString(),
        ];

        if (count($this->rowBuffer) >= $this->bufferSize) {
            $this->flush();
        }
    }

    public function finish(string $status, ?string $errorMessage = null): void
    {
        $this->flush();

        $counts = DB::table('import_row_logs')
            ->where('import_id', $this->run->id)
            ->selectRaw("
                SUM(CASE WHEN operation = 'create'  THEN 1 ELSE 0 END) AS created,
                SUM(CASE WHEN operation = 'update'  THEN 1 ELSE 0 END) AS updated,
                SUM(CASE WHEN operation = 'skip'    THEN 1 ELSE 0 END) AS skipped,
                SUM(CASE WHEN operation = 'error'   THEN 1 ELSE 0 END) AS errors
            ")
            ->first();

        $this->run->update([
            'status'        => $status,
            'created_count' => $counts->created,
            'updated_count' => $counts->updated,
            'skipped_count' => $counts->skipped,
            'errors_count'  => $counts->errors,
            'completed_at'  => now(),
            'duration_ms'   => now()->diffInMilliseconds($this->run->started_at),
            'error_message' => $errorMessage,
        ]);
    }

    private function flush(): void
    {
        if (!empty($this->rowBuffer)) {
            DB::table('import_row_logs')->insert($this->rowBuffer);
            $this->rowBuffer = [];
        }
    }
}

Буферизация записей по 500 штук — вместо INSERT на каждую строку.

Фиксация diff изменённых полей

private function buildDiff(Product $existing, array $newData): array
{
    $trackFields = ['price', 'qty', 'name', 'description'];
    $diff        = [];

    foreach ($trackFields as $field) {
        $old = $existing->{$field};
        $new = $newData[$field] ?? null;

        if ((string) $old !== (string) $new) {
            $diff[$field] = ['old' => $old, 'new' => $new];
        }
    }

    return $diff;
}

Агрегированный отчёт

class ImportReportBuilder
{
    public function build(ImportRun $run): ImportReport
    {
        $topErrors = DB::table('import_row_logs')
            ->where('import_id', $run->id)
            ->where('operation', 'error')
            ->select('error_code', DB::raw('COUNT(*) as count'), DB::raw('MIN(sku) as example_sku'))
            ->groupBy('error_code')
            ->orderByDesc('count')
            ->limit(10)
            ->get();

        $priceChanges = DB::table('import_row_logs')
            ->where('import_id', $run->id)
            ->where('operation', 'update')
            ->whereRaw("changed_fields ? 'price'")
            ->count();

        return new ImportReport(
            run: $run,
            topErrors: $topErrors,
            priceChangesCount: $priceChanges,
        );
    }
}

Уведомления по результатам

class ImportCompletedNotification extends Notification
{
    public function toMail(mixed $notifiable): MailMessage
    {
        $run = $this->run;
        return (new MailMessage)
            ->subject("Импорт #{$run->id}: {$run->status}")
            ->line("Источник: {$run->source->name}")
            ->line("Создано: {$run->created_count}, обновлено: {$run->updated_count}, ошибок: {$run->errors_count}")
            ->line("Длительность: " . round($run->duration_ms / 1000, 1) . " сек")
            ->when($run->errors_count > 0, fn($m) => $m->action('Просмотреть ошибки', $this->reportUrl()));
    }
}

Уведомление отправляется только если статус не success или количество ошибок превышает порог.

Ротация логов

Построчные логи растут быстро. Политика хранения:

// Artisan-команда в scheduler
$schedule->command('import:cleanup-logs --older-than=30')->weekly();

class CleanupImportLogsCommand extends Command
{
    public function handle(): void
    {
        $cutoff = now()->subDays($this->option('older-than'));

        // Удаляем построчные логи старых успешных импортов
        ImportRowLog::whereHas('run', fn($q) =>
            $q->where('status', 'success')->where('completed_at', '<', $cutoff)
        )->delete();

        // Сводные записи import_runs оставляем навсегда (они маленькие)
    }
}

Сроки реализации

• ImportLogger с буферизацией, таблицы в БД, финальные счётчики — 1 день
• Diff полей, агрегированный отчёт, уведомления — +0.5 дня
• UI просмотра логов в админке, ротация старых записей — +0.5 дня