Прогрес-бар для фонових завдань на Laravel і React

Чому прогрес-бар для фонових завдань розходиться з реальністю

Завдання йде в чергу завдань, воркер її забирає, а користувач дивиться на смужку. Біда в тому, що відсоток виконання рахується не за самою роботою, а поруч із нею: обробник пише «почав» і «закінчив», і між цими двома записами смуга стоїть на нулі всі двадцять хвилин.

Якщо прогрес усе-таки рухається, він бреше інакше — рахує записи, а не їхню вагу: тисяча дрібних рядків пролітає за секунду, а одна важка операція тримає смугу на 97% стільки ж, скільки й решта пакета.

Друга причина — оновлення статусу живе в окремій транзакції від корисної роботи. Воркер упав через тайм-аут або не вліз у пам'ять — запис залишається в стані «виконується», і відрізнити зависле завдання від просто довгого за інтерфейсом неможливо.

Користувач чекає, оновлює сторінку, запускає повторно — і отримує дублі: той самий лист, той самий рахунок, те саме вивантаження приходять двічі, а черга накопичує зайві завдання.

Ціна такого збою — не крива смужка, а недовіра до будь-якої довгої дії: люди починають смикати кнопку, підтримка розбирає дублі, адміністратор не розуміє, що реально відбувається в черзі.

Нижче розбираємо, як це закривається — від того, де зберігається прогрес і хто його пише, до того, як відрізнити воркер, що впав, від працюючого.

Що дає достовірний індикатор стану тривалих завдань

Достовірність статусу — це контракт між обробником черги Laravel та інтерфейсом, а не елемент оформлення.

Коли прогрес-бар показує реальну частку виконаного, а не нескінченне «завантаження», користувач перестає перезапускати операцію: повторні запуски падають у рази, бо ніхто не смикає кнопку повторно на тридцятій секунді очікування.

Другий ефект — знятий клас відмов «завдання без статусу». Якщо обробник упав, запис висить у стані «у роботі» необмежено довго, і підтримка вручну з'ясовує, що сталося.

Періодична звірка журналу завдання з чергою та переведення завислих процесів у явний статус із причиною закривають цей сценарій: завдання або завершується, або чесно повідомляє про помилку й залишається доступним для повтору.

Навантаження на підтримку падає разом із невизначеністю. Звернення на кшталт «воно ще рахується?» зникають, коли на екрані видно етап і передбачуваний залишок часу, а фахівці займаються справжніми збоями замість уточнення стану.

Час очікування стає передбачуваним: смуга будується за обробленою часткою завдань, а не за усередненою прикидкою, і згладжується, щоб не стрибати. Тривалі операції при цьому можна запускати у фоні та йти зі сторінки — після повернення статус відновлюється зі збереженого прогресу.

Режими відображення прогрес-бару: порівняння підходів

Черга завдань на Laravel та інтерфейс на React — різні процеси: одна сторона рахує кроки, друга про них не знає. Режим передачі стану обирають за двома питаннями: чи можна порахувати обсяг роботи заздалегідь і як швидко клієнту потрібне оновлення. Від цього залежить, показуємо ми чесні відсотки чи невизначений індикатор.

Детермінований лічильник працює, коли завдання розбито на порції й після кожної порції оновлюється запис «оброблено N з M». Тоді шкала відображає реальний хід виконання, а не активність сервера.

Якщо розбити роботу не можна — наприклад, усередині один довгий виклик — коректніше невизначений індикатор: він не обіцяє «залишилося дві хвилини», які нічим підтвердити.

На практиці беруть комбінацію: періодичне опитування для списку завдань, потік подій для картки відкритого завдання. У разі обриву з'єднання інтерфейс повертається до опитування й перезапитує стан — шкала не залипає на останньому значенні.

Зміна режиму не потребує переробки самого завдання: лічильник пишеться у сховище стану, а спосіб доставки в інтерфейс змінюється окремо.

Етапи впровадження: від аудиту черги до передачі регламенту

Прогрес — це не анімація на екрані, а відображення реального стану завдання у сховищі. Тому порядок робіт починається з розбору того, що відбувається на сервері, і закінчується регламентом, за яким команда далі працює сама.

1. Аудит черги. Розбираємо життєвий цикл фонового завдання: які обробники існують, скільки кроків усередині кожного, де завдання може бути перезапущене, скасоване або відкинуте через тайм-аут. Результат — карта переходів, на якій будується все інше.
2. Схема статусів. Проєктуємо скінченний набір станів (у черзі, виконується, крок N з M, готово, помилка) і правила переходу між ними. Окремо фіксуємо поведінку при повторному запуску — інакше користувач побачить два прогреси на одне завдання.
3. Межа кроку. Домовляємося, що вважати кроком: одиницю роботи, яку видно людині. Занадто великий крок дає «завмерлу» смугу, занадто дрібний — зайві записи у сховищі та зростання навантаження на нього.
4. Сховище стану. Обираємо, де живе прогрес: кеш, таблиця в базі або черга повідомлень. Задаємо частоту запису й час життя запису, щоб дані не накопичувалися після завершення завдання.
5. Передача в інтерфейс. Визначаємо канал оновлення — періодичне опитування або потокове з'єднання, — а також відновлення стану при перезавантаженні сторінки та поведінку при втраті зв'язку. Клієнт не повинен бачити нульовий прогрес на вже виконаному завданні.
6. Перевірка під навантаженням. Запускаємо кілька завдань одночасно й дивимося, чи не зростає час відгуку, чи не губляться оновлення й чи збігається фінальний статус із фактичним результатом обробки.
7. Передача регламенту. Віддаємо схему статусів, конфігурацію сховища, правила додавання нових кроків і розбір типових збоїв — з цього моменту команда розширює прогрес без нашої участі.

Перевірка під навантаженням і передача регламенту — не формальність, а точки, де найчастіше спливають розбіжності. Ми закриваємо їх до здачі, тому після запуску прогрес не розходиться з реальністю за першого ж збою обробника.

Конфігурації, схеми та регламенти, які залишаються в команди

Прогрес-бар перестає бути прикрасою, коли за ним стоїть описаний життєвий цикл завдання: хто його поставив, у яку чергу воно пішло, що вважається завершенням і що робити, якщо воно зависло.

Тому до пакета передачі входить не лише робочий код, а й набір артефактів, за якими команда замовника зможе вести такі завдання без нас.

• Конфігурація черг — які черги заведено, які типи завдань у яку потрапляють, скільки обробників на кожну і як налаштовуються пріоритети та повторні спроби.
• Схема життєвого циклу — усі статуси завдання від постановки до результату або помилки, із зазначенням, які переходи допустимі та який статус бачить користувач у прогрес-барі.
• Політики доступу до статусів — хто з ролей може запускати, зупиняти й повторювати завдання, хто бачить лише свій прогрес, а хто — зведення за всіма.
• Інструкція підтримки — типові ситуації: завдання стоїть без руху, обірвалося на середині, відпрацювало двічі; що перевірити в першу чергу і які логи дивитися.
• Порядок відкату — як повернути попередню поведінку обробки, якщо нововведення заважає, і які дані при цьому не втрачаються.
• Регламент повторного запуску — умови, за яких завдання можна перезапустити безпечно, щоб не отримати дублі результатів.
• Спостережуваність — які метрики за довжиною черги та часом обробки знімаються, на яких порогах спрацьовують сповіщення.

Кожен артефакт оформлено так, щоб його можна було прочитати без нас: схема з підписами, інструкція з конкретними кроками, конфігурація з коментарями до неочевидних значень.

Кейс: розбіжність індикатора та черги усунули за два тижні

До: індикатор завмирав, а завдання губилися мовчки

Масове вивантаження звітів на кілька тисяч рядків ішло через чергу, але індикатор на екрані рахував прогрес за лічильником, який оновлювався лише після успішного завершення кожного пакета.

Якщо обробник падав на середині — наприклад, на неочікуваному форматі дати в одному з файлів, — зовні нічого не змінювалося: смуга завмирала на 60–70%, людина чекала, а завдання вже було мертве.

Ми розібрали інциденти за місяць: частина вивантажень не доходила до кінця, і жоден такий збій не давав явної помилки в інтерфейсі.

Після: стан звіряється з фактом, а не з очікуванням

Джерелом правди зробили серверну сторону на Laravel: кожне завдання отримало журнал кроків, смуга прогресу малює реально завершене, зчитуючи стан зі сховища, а не з пам'яті обробника.

Падіння стало подією — невдала спроба фіксується, завдання переводиться в статус збою, залишок перераховується заново, а користувач бачить причину й кнопку повтору.

Звірку стану винесли у фонову перевірку: вона періодично зіставляє чергу, журнал і те, що показано в браузері, та підтягує розбіжності.

Метрики впровадження за два тижні: розбіжностей індикатора з фактом — нуль, мовчазних падінь обробників — нуль, вивантажень, покинутих на середині, — нуль. Час від збою до зрозумілого статусу скоротився з годин очікування до хвилин.

Клас відмов закрито повністю: будь-який збій тепер видно користувачеві й відтворюється в логах, а не перетворюється на мовчки завислий прогрес-бар.

Що робити, якщо індикатор впроваджено і він показує неправильні значення

Розбіжність індикатора майже завжди належить до одного з двох класів причин: неправильна оцінка обсягу роботи або втрата передачі стану між обробником завдання та інтерфейсом.

Розрізнити їх можна за журналом виконання: якщо лічильник зростає рівно, але впирається у верхню межу раніше часу — бреше оцінка; якщо значення стрибають, відкочуються назад або завмирають — рветься передача стану.

Далі вирішується питання обсягу правок. Переписувати чергу повністю не потрібно: достатньо єдиного контракту події прогресу — одна точка публікації та явне правило перерахунку відсотка.

Сумісність із поточною чергою при цьому зберігається, бо змінюється шар звітності, а не постановка й порядок завдань.

Порядок діагностики такий: звіряємо журнал з оцінкою обсягу, перевіряємо агрегацію за завданням, і лише потім чіпаємо схему зберігання стану. Так втручання залишається частковим рефакторингом.

Технічні сумніви: надійність, супровід і повторні запуски

Частина питань виникає до старту: вони про поведінку системи в нештатних умовах, а не про зовнішній вигляд смуги. Нижче — відповіді на ті, що запитують найчастіше.

Що відбувається при збої обробника?

Стан завдання зберігається в журналі завдань, а не в пам'яті процесу. Збій фіксується як зупинка на конкретному пакеті, із записом помилки й контексту. Повторний запуск продовжує з останнього підтвердженого пакета, а не з початку.

Завдання дивляться кілька користувачів одночасно — це заважає?

Кожен клієнт підписаний на канал завдання й отримує лише зміни статусу. Кількість спостерігачів не впливає на швидкість обробки: дивитися вдесятьох — те саме, що дивитися одному.

Чи витримає рішення пікове навантаження?

Підписка на прогрес дешевша за саму обробку: клієнти отримують лише зміни стану. Завдання стають у чергу, обробник бере наступне після звільнення — сплеск не перетворюється на відмову.

Що залишається на супроводі після здачі?

Метрики тривалості етапів, сповіщення про застряглі завдання й журнал збоїв із контекстом. Нові етапи додаються окремими обробниками й не зачіпають уже працюючі.

Обговоримо завдання й повернемося з оцінкою та планом робіт

Щоб повернутися з оцінкою, а не з припущеннями, нам потрібні вихідні дані про те, як влаштована поточна черга завдань та інтерфейс.

Прогрес-бар — це по суті контракт між сервером і клієнтом: стан завдання має переживати перезавантаження сторінки, перезапуск обробника й повторний запуск після збою.

Тому починаємо з інвентаризації того, що вже працює, і лише потім пропонуємо схему статусів і порядок впровадження.

• Як зараз завдання потрапляє в чергу і де зберігається його стан: таблиця в базі, кеш або окрема служба черг.
• Чи розбито тривалий процес на кроки і чи можна заздалегідь порахувати їхню загальну кількість — від цього залежить, буде прогрес-бар чесним чи залишиться «крутилкою».
• Як інтерфейс дізнається про зміни: рідкісне опитування за таймером, потік подій або постійний канал зв'язку.
• Що вважається нормою при закритті вкладки, падінні обробника й повторному запуску — які сценарії допустимі, а які потрібно виключити.
• Скільки завдань іде одночасно і на яку глибину історії статусів розраховувати.
• Вимоги до інтерфейсу: де показується прогрес, чи потрібне скасування і що бачить користувач при помилці.
• Обмеження оточення: доступи до стендів, регламент розгортання, чи можна змінювати схему даних на живій системі.

За цими відповідями ми збираємо схему статусів — від постановки в чергу до завершення, скасування й помилки — і розкладаємо впровадження на етапи зі зрозумілим порядком. Опишіть завдання в тому обсязі, у якому воно є: повернемося з оцінкою, схемою статусів і планом робіт.