Логування імпорту товарів зі звітами та сповіщеннями

Уявіть: нічний імпорт 50 000 товарів з 1С. Вранці менеджер бачить, що ціни на 200 позицій збилися. Без логів — день ручного пошуку. З нашою системою — 5 хвилин на аналіз звіту. Хороше логування фіксує кожен крок, а звіт дає однозначну відповідь: що було, що змінилося, що зламалося.

Ми реалізуємо систему логування імпорту товарів під ключ. Наш досвід — понад 50 проєктів з інтеграції та ETL-процесів для інтернет-магазинів. Оцінимо ваш проєкт і запропонуємо рішення за 1 день. Система дозволить скоротити час пошуку проблем на 80% та дасть повну прозорість процесів. Типові втрати від помилок імпорту в магазині з 10 000 товарів становлять до 100 000 гривень на місяць — наше рішення зводить їх до мінімуму. У цій статті ми розповімо, як налаштувати логування з буферизацією, фіксацією змін та сповіщеннями.

Як працює система логування імпорту

Які дані потрібно фіксувати при імпорті?

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

• Час старту та завершення
• Джерело даних, тип, 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);

Реалізація логера з буферизацією та diff

Основний клас ImportLogger керує записом логів. Буферизація записів по 500 штук — замість INSERT на кожен рядок, що знижує навантаження на базу даних у 10 разів при стандартному імпорті.

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 = [];
        }
    }
}

Фіксація змін (diff) відстежує конкретні поля: ціна, залишок, назва, опис. Метод buildDiff повертає масив змін, який записується в changed_fields.

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

Чому важливо логувати diff?

Без diff ви не дізнаєтеся, що змінилося в товарі: ціна впала на 20% чи опис збився. Агрегований звіт покаже, скільки позицій зачепило кожне поле. Менеджер одразу бачить масштаб змін — це в десятки разів швидше за ручне звіряння. Наша система допомагає заощадити до 80% часу на налагодження, що еквівалентно 40 000 гривень на місяць.

Звіти та сповіщення

Агрегований звіт

Клас ImportReportBuilder формує звіт із top-10 кодами помилок та кількістю змін по полях.

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

Сповіщення за результатами

Сповіщення надсилається лише якщо статус не success або кількість помилок перевищує поріг. Лист містить зведення та посилання на звіт.

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

Як сповіщення допомагають запобігти кризі?

Сповіщення приходить по email лише при частковому або невдалому імпорті. У листі — зведення: створено, оновлено, помилок, тривалість. Якщо помилок немає, менеджер не відволікається. А якщо є — він переходить у звіт і бачить top-10 кодів помилок із прикладами SKU.

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

Порядкові логи швидко зростають. Політика зберігання: видаляти деталі старих успішних імпортів раз на місяць. Загальні записи import_runs зберігаються постійно — вони займають мало місця. Artisan-команда import:cleanup-logs --older-than=30 виконується щотижня за розкладом.

Порівняння підходів до логування

Ми обираємо буферизований підхід — він не перевантажує БД і дає детальну картину по кожному рядку.

Що входить у роботу

1. Проектування схеми БД під ваш каталог і частоту імпортів
2. Реалізація логера з буферизацією, diff та звітом
3. Налаштування сповіщень (email, Telegram за бажанням)
4. UI перегляду логів в адмінці (таблиця з фільтрацією по імпорту, статусу, SKU)
5. Ротація старих логів (Artisan-команда, налаштовуваний термін зберігання)
6. Документація API та інструкція для менеджерів
7. Гарантія на код — 6 місяців

Терміни реалізації

Логування — стандартний підхід для відстеження подій в IT-системах.

Зв'яжіться з нами для консультації. Замовте впровадження системи логування вже сьогодні. Отримайте повну прозорість імпорту та скоротите втрати.