Кастомний пакет Bagisto: де ламається штатна логіка
Штатна збірка Bagisto закриває базовий сценарій магазину, але щойно з'являється нестандартна логіка — власні правила розрахунку знижок, інтеграція зі складом, обмін із зовнішньою системою замовлень — доопрацювання штатної логіки через правку ядра перетворюється на міну сповільненої дії.
Перше ж оновлення платформи перезаписує змінені файли, і магазин або падає, або тихо втрачає частину функціоналу: замовлення проходять, а знижка не застосовується.
Друге вузьке місце — дублювання логіки. Коли той самий розрахунок ціни або умова доставки живе в контролері, шаблоні та обробнику події, будь-яка правка вимагає синхронної зміни в трьох місцях.
Рано чи пізно одне з них забувають — і поведінка магазину розходиться залежно від того, через яку сторінку прийшов покупець.
Третя проблема — відсутність ізоляції модулів. Без чітких меж розширення функціоналу магазину обростає прихованими залежностями: модуль знижок знає про модуль доставки, той — про логи, і вимкнути або замінити один блок без правки решти вже неможливо.
Кастомний пакет Bagisto вирішує це інакше: логіка виноситься в окремий пакет, ядро залишається недоторканим, а оновлення платформи проходять без конфліктів під час оновлення. Розбираємо, як це влаштовано і де саме штатна збірка починає заважати.
Що дає ізольований пакет: ефект у цифрах
Кастомний пакет Bagisto — це окремий модуль із власним простором імен, конфігурацією, міграціями та маршрутами, який підключається до платформи як самостійна одиниця. Логіка магазину не розмазується по ядру та темі: правки живуть в одному репозиторії з власною історією змін. Саме ізоляція коду дає вимірюваний ефект, а не «акуратна архітектура» сама по собі.
Швидкість оновлення платформи зростає кратно. Коли кастомізація не торкається ядра, перехід на нову гілку Bagisto зводиться до оновлення залежності та прогону тестів пакета — замість ручного порівняння сотень змінених файлів.
Оновлення, яке раніше розтягувалося на тижні, вкладається в один-два робочих дні, а вікно простою на проді скорочується до планового релізу.
Зниження регресій — прямий наслідок меж модуля. Зміна в логіці знижок або розрахунку доставки не зачіпає оформлення замовлення, бо зв'язки між частинами описані контрактами, а не неявними залежностями.
Покриття пакета тестами показує, які сценарії зачеплені правкою, і кількість несподіваних поломок на реліз падає в рази.
Передбачуваність підтримки — це коли нова команда або новий інженер входить у проєкт без археології. Структура пакета читається за розділами, точка входу в кожну функцію відома, а відкат до попередньої версії модуля не вимагає торкатися решти системи. Опишіть вашу задачу — повернемося з оцінкою та планом, як це лягає на ваш магазин.
Варіанти реалізації: пакет, тема або правка ядра
Три підходи різняться не «чистотою коду», а тим, що відбувається з вашим магазином при першому ж оновленні платформи. Пакет розширення підключається поверх ядра і не чіпає його файли — оновлення встановлюється штатно, а ваша логіка залишається в окремому шарі.
Правка ядра вирішує завдання найшвидше на старті, але кожне оновлення перетворюється на ручне порівняння змінених файлів: чим більше правок, тим вищий ризик, що черговий реліз затрє доопрацювання або зламає оформлення замовлення.
Кастомна тема закриває лише представлення — верстку, шаблони, оформлення вітрини — і не підходить, коли потрібно змінювати логіку кошика, розрахунку доставки або синхронізації з обліковою системою.
| Варіант | Коли підходить | Обмеження підходу |
|---|---|---|
| Пакет розширення | Потрібна нова логіка: правила цін, інтеграції, нестандартний розрахунок доставки, свої розділи в адмінці | Вимагає проєктування точок підключення; частина завдань впирається у відсутність події в ядрі |
| Правка ядра | Разовий терміновий фікс, який не можна відкласти | Оновлення встановлюються вручну, конфлікти зростають з кожною правкою, відкат утруднений |
| Кастомна тема | Зміна вітрини: верстка, шаблони, оформлення карток і кошика | Не змінює бізнес-логіку; при зміні шаблонів ядра вимагає повторної звірки |
Сумісність з оновленнями
Пакет тримає сумісність передбачувано: оновлення ядра і оновлення пакета — незалежні події, і ми фіксуємо, які точки підключення зачеплені в новій гілці.
Правка ядра такої гарантії не дає — при кожному релізі потрібно перевіряти, чи не перетнувся ваш код зі змінами розробників платформи.
Змішаний сценарій
На практиці найчастіше поєднують: логіку виносимо в пакет, вітрину — в тему, а правки ядра зводимо до нуля або до мінімуму з явною позначкою, щоб їх було видно при оновленні. Такий розклад дає штатні оновлення без простою і зрозумілий відкат на попередню версію.
Етапи впровадження пакета: від аудиту до передачі
Робота над пакетом іде ітераціями, але всередині кожної ітерації порядок етапів фіксований: спочатку розбираємося, як магазин влаштований зараз, потім проєктуємо зміни, тільки потім пишемо код.
Такий порядок знімає головний ризик кастомної розробки — пакет, який конфліктує з уже встановленими розширеннями або ламає оформлення замовлення.
- Аудит магазину. Дивимося поточну конфігурацію, встановлені розширення, кастомізації теми та ядра, точки втручання в оформлення замовлення та каталог. Фіксуємо, що можна розширити штатними засобами, а що потребує перевизначення — це визначає обсяг робіт до початку розробки.
- Схема пакета. Проєктуємо структуру: які сутності та таблиці додаються, які події та спостерігачі використовуємо, як пакет взаємодіє з наявними модулями. Схему узгоджуємо з вами до написання коду — правки на цьому етапі коштують години, після релізу — дні.
- Налаштування інтеграцій. Підключаємо пакет до зовнішніх систем: склад, платежі, доставка, облікові системи. Кожне з'єднання налаштовуємо з обробкою помилок і повторними спробами, щоб збій на стороні сервісу не валив оформлення замовлення.
- Перевірка сценаріїв. Прогоняємо повний шлях покупця — від додавання товару до підтвердження оплати, включно з поверненнями, частковими скасуваннями та роботою з кількома складами. Окремо перевіряємо поведінку при недоступності зовнішнього сервісу.
- Передача документації. Віддаємо опис архітектури пакета, інструкції з оновлення та відкату, схему даних і порядок дій при типових збоях. Ваші інженери можуть супроводжувати пакет самостійно, без залежності від нас.
Етапи йдуть з контрольними точками: після аудиту ви бачите обсяг і план, після схеми — узгоджуєте архітектуру, після перевірки — отримуєте звіт за сценаріями. Опишіть задачу — повернемося з оцінкою термінів і складу робіт.
Артефакти на виході: що отримує команда замовника
Передаємо не «папку з кодом», а комплект, за яким ваша команда зможе супроводжувати пакет без нас. Нижче — що саме фіксується в передачі.
- Конфігурації пакета — файли налаштувань з описом кожного параметра: які значення обов'язкові, які залежать від середовища, що змінюється при підключенні нового каналу або мови. Окремо відзначаємо місця, де правка ламає сумісність з ядром.
- Схеми інтеграцій — як пакет стикується з каталогом, оформленням замовлення, оплатою та складським обліком: які події він слухає, які дані віддає назовні, де проходить межа відповідальності між пакетом і ядром платформи.
- Регламенти оновлення — порядок дій при виході нової гілки ядра: що перевіряємо до оновлення, як відкочуємося, які міграції даних виконуються і в якій послідовності. З правилами, за яких оновлення відкладається.
- Інструкції для команди — розгортання на чистому середовищі, локальний запуск, типові збої та їхні ознаки. Розраховані на розробника, який бачить проєкт уперше.
- Документація модуля — призначення сутностей, точки розширення, публічні методи з прикладами виклику. Плюс журнал рішень: чому обрано таку структуру і які альтернативи відхилено.
- Набір автотестів — покриття ключових сценаріїв: оформлення замовлення, перерахунок кошика, синхронізація залишків. Тести запускаються однією командою і слугують страховкою при доопрацюваннях.
- Список залежностей — зовнішні бібліотеки із зазначенням, які можна оновлювати вільно, а які зав'язані на логіку пакета і потребують перевірки.
Комплект передаємо на дзвінку з розбором: ваші інженери задають питання щодо коду та схем, ми показуємо розгортання на тестовому середовищі. Опишіть задачу — повернемося з оцінкою та планом передачі.
Кейс: як ізольований пакет прибрав регресії
Замовник — мережа роздрібних магазинів на Bagisto з кількома регіональними вітринами. Логіка лояльності, розрахунок доставки та правила промо жили прямо в ядрі й у темі оформлення, тому кожне оновлення платформи перетворювалося на ручне редагування десятків файлів.
Регресії вилазили то в кошику, то в оформленні замовлення, і перед кожним релізом команда тиждень проганяла сценарії вручну.
Що було до
Оновлення займало 3-4 дні: спочатку правки в ядрі, потім звірка з новою версією, потім відкат, якщо щось ламалося. За квартал фіксували 9-12 відмов на проді, з них третина — в оформленні замовлення, тобто із втратою виручки. Тести покривали менше половини користувацьких шляхів, а зміни в темі зачіпали логіку розрахунків.
Що змінили
Винесли всю бізнес-логіку в окремий пакет: свої сервіси, моделі, міграції та події, без правок ядра й теми. Пакет підключається як звичайна залежність, конфігурація — через файл налаштувань, точки розширення — через події та підміну сервісів. Тема залишилася тільки про зовнішній вигляд, ядро — тільки про базовий функціонал.
Що стало
Оновлення платформи скоротилося до кількох годин: правки в пакеті не конфліктують з ядром, відкат — це вимкнення однієї залежності.
Кількість відмов на проді впала з 9-12 до 1-2 за квартал, покриття тестами зросло до більшої частини користувацьких шляхів, а релізи стали виходити вдвічі частіше без нічних правок.
Окремий ефект — передбачуваність: нова вітрина піднімається копіюванням пакета й зміною налаштувань, а не форком усього магазину. Логіка лояльності та доставки тепер одна на всі регіони, розбіжності між вітринами зникли.
Чим відрізняється пакет від прямої правки ядра?
Пряма правка ядра — це коли файл платформи змінюється на місці: у контролері, моделі або шаблоні правиться рядок, і все працює рівно до першого оновлення. Формально завдання вирішено, але рішення живе всередині чужого коду і ніде не зафіксовано окремо.
Під час наступного апдейту платформа перезаписує змінені файли, і правки зникають — або, що гірше, конфліктують з новою версією і ламають уже працюючі сценарії.
Пакет — це окремий модуль, який підключається до платформи і розширює її через штатні точки розширення: сервіс-провайдери, події, перевизначення шаблонів і маршрутів. Ядро залишається недоторканим, а вся логіка лежить в ізольованому каталозі з власним простором імен.
Різниця проявляється саме на підтримці: оновлення платформи не зачіпає код пакета, а якщо нова версія змінює якийсь інтерфейс — правиться одне місце в модулі, а не розшукуються десятки правок по всьому ядру.
Ізоляція дає ще два практичні наслідки. Перший — передбачуваний відкат: пакет вимикається однією командою, і система повертається до початкової поведінки без відновлення з резервної копії.
Другий — переносимість: той самий модуль ставиться на інший проєкт з тією самою платформою, якщо логіка не зав'язана на конкретну тему або набір правок.
Ризик прямої правки ядра не в тому, що вона зламається сьогодні, а в тому, що ціна підтримки зростає з кожним оновленням. Через кілька апдейтів ніхто вже не пам'ятає, які файли чіпали і навіщо, а будь-яке оновлення перетворюється на ручне злиття.
Пакет фіксує зміни в одному місці і робить оновлення рутинною операцією, а не проєктом із непередбачуваним результатом.
Часті технічні сумніви при розробці пакета
Сумніви зазвичай впираються в чотири речі: сумісність версій, міграції даних, тестування та оновлення без простою. Нижче — як ми закриваємо кожен із них на рівні архітектури, а не обіцянок.
Пакет буде працювати з нашою версією Bagisto і не зламається при оновленні?
Кастомний пакет Bagisto ми збираємо як самостійний модуль із явно оголошеними залежностями: діапазон підтримуваних версій ядра фіксується в маніфесті, а не «на словах».
Точки розширення — події та сервіс-провайдери — обираються так, щоб не перевизначати ядро цілком: при апгрейді оновлюється платформа, а логіка пакета залишається недоторканою.
Перед кожним оновленням проганяємо пакет на цільовій гілці в ізольованому середовищі та фіксуємо матрицю сумісності — ви заздалегідь бачите, які версії підтримуються, а які потребують доопрацювання.
Як переносяться дані зі старої системи без втрат?
Міграції ідемпотентні та розбиті на етапи: спочатку структура (таблиці, індекси, зв'язки), потім перенесення даних пакетами з перевіркою контрольних сум, потім звірка кількості та ключових полів. Важкі операції йдемо порціями, щоб не блокувати базу.
На кожному етапі є точка відкату: якщо звірка не сходиться, повертаємося до попереднього стану без ручного правлення таблиць.
Як ви тестуєте пакет і що з оновленням без простою?
Покриваємо автотестами критичні сценарії — оформлення замовлення, розрахунок, синхронізацію, права доступу — і проганяємо їх на кожній збірці.
Оновлення викочуємо за схемою з перемиканням трафіку: нова версія піднімається поруч, перевіряється на бойових даних, і тільки потім на неї йде навантаження. При проблемі трафік повертається на попередню версію за хвилини, без зупинки магазину.
Якщо залишилися сумніви щодо вашого стеку — опишіть задачу, повернемося з оцінкою та планом робіт.
Обговоримо ваше завдання і повернемося з планом
Щоб оцінка була предметною, а не «вилкою від стелі», починаємо з розбору завдання, а не з прайсу. Нам важливо зрозуміти, що саме не закриває штатний функціонал: типи товарів, правила цін і знижок, логіку складу, інтеграції з обліковою системою, вимоги до вітрини. Чим точніше описаний сценарій, тим менше припущень у плані робіт і тим чесніші терміни.
Далі інженер розбирає, що вирішується налаштуванням, а що потребує окремого модуля. Кастомний пакет Bagisto виправданий, коли логіка виходить за рамки типових рішень і її потрібно ізолювати, щоб оновлення платформи не ламали доопрацювання. Ми фіксуємо межі пакета, точки розширення і те, як він співіснуватиме з ядром.
Що відбувається після звернення
- Розбір завдання. Дзвінок з інженером: які процеси мають працювати, хто ними користується, що вже є в системі.
- Аудит поточного рішення. Дивимося встановлену версію, встановлені модулі, доопрацювання ядра та ризики під час оновлення.
- Узгодження обсягу. Розділяємо, що закривається налаштуванням, що — пакетом, а що виносимо за межі проєкту.
- Оцінка термінів і етапів. Розбиваємо роботу на перевірювані кроки з зрозумілим результатом на кожному.
- План робіт. Фіксуємо послідовність, залежності, точки приймання та порядок викату на бойовий контур.
- Узгодження та старт. Після затвердження плану закріплюємо відповідального інженера і починаємо з першого етапу.
Якщо під час розбору з'ясовується, що завдання вирішується без кастомної розробки, ми говоримо про це прямо — це дешевше і швидше для вас. Опишіть завдання у вільній формі: що за магазин, які процеси не закриваються, що вже пробували. Повернемося з оцінкою термінів і планом робіт, за яким можна приймати рішення.
