У “живому” проєкті найболючіші баги з’являються не від нових фіч, а від правок, які випадково зняли старі обмеження. Особливо це стосується сторінок контролю, де є фільтри по даті/статусу/юзеру, і де важливо не показати зайве. Якщо ти робиш правку “аби працювало”, дуже легко знести базовий where по доступу, прибрати важливий scope, зламати порядок накладання фільтрів або зіпсувати пагінацію. Тому правило просте: будь-яка зміна має бути “додатковим шаром”, а не заміною існуючого механізму.
Перший принцип акуратної правки — спочатку зафіксувати, що зараз є “контрактом”. Контракт — це очікувана поведінка. Наприклад: автор бачить тільки свої записи; редактор бачить тільки свій ресурс; дата фільтрує по published_at; status працює як select; пагінація зберігає query string; сортировка за замовчуванням — дата desc; гість не бачить нічого. Перед тим як додавати новий фільтр або поле, ти маєш розуміти, що саме не можна зламати. Без цього ти не відрізниш “працює” від “зламали тихо”.
Другий принцип — не чіпати базовий запит видимості, а нарощувати зверху. У правильній структурі завжди є базовий query, який обмежує доступ (scope/query builder). Наприклад visibleTo($user) або “where resource_id in …”. Це ядро. Нові фільтри повинні додаватися після цього ядра як додаткові when(...) або окремі умови, але ядро не переписується. Якщо ти перепишеш ядро, ти майже гарантовано втрачаєш якийсь кейс або створюєш витік.
Третій принцип — “фільтри не розширюють доступ”. Це критично. Фільтр з query string ніколи не повинен робити запит ширшим, ніж базовий доступ. Наприклад, якщо автор може бачити тільки свої, то параметр ?user_id=999 не має дати йому чужі записи, навіть якщо він його підставив. Технічно це означає, що базовий where по доступу завжди залишається, а user_id-фільтр або ігнорується, або працює тільки в рамках доступного набору.
Четвертий принцип — додавати фільтри через when() і “guarded” значення. Тобто ти не робиш “якщо є параметр — ліплю його прямо в query”. Ти спочатку валідуєш/нормалізуєш параметри: дата в форматі, статус — тільки з переліку, user_id — тільки число, і лише потім додаєш умову. Це запобігає хаосу та edge-cases. А ще це дає контроль: якщо параметр невалідний, краще не застосовувати його, ніж ламати запит.
П’ятий принцип — порядок операцій незмінний: доступи → фільтри → сортування → paginate. Дуже часта “тиха” регресія: хтось додає paginate() раніше, або додає get() для підрахунків, або міняє orderBy. Наслідок — сторінка показує не те або починає “стрибати”. Тому при розширеннях порядок не чіпаємо. Якщо потрібно додати новий агрегат (лічильники, групування), робимо окремими запитами з тим самим базовим обмеженням, а не перетворюємо основний список на монстра.
Шостий принцип — зміни мають бути маленькими і локальними. Якщо задача “додати фільтр по статусу”, то ви не переписуєте контролер, не переносите логіку на інший шар, не міняєте структуру route. Ви додаєте одну умову + UI елемент + збереження query string. Якщо ви у процесі “випадково” почали рефакторити все підряд, шанс зламати старе різко зростає. Рефакторинг — окрема задача, окремий PR, окремі тести.
Сьомий принцип — захист від регресій через тести. Мінімум: один feature-тест, який перевіряє, що старе обмеження досі працює. Наприклад: автор не бачить чужих записів у index, навіть із параметром user_id. Або статус-фільтр не показує записи поза доступним набором. Тобто кожне “розширення” додає один тест, який підтверджує, що старе правило не зникло. Це дешевий і дуже ефективний підхід.
Восьмий принцип — UI не має “знімати” фільтри. При додаванні нового фільтра ви часто ламаєте старі, бо форма починає відправляти тільки новий параметр і забуває інші, або пагінація не підхоплює query string. Тому в UI правило просте: всі фільтри — GET, усі поля відображають поточне значення з request(), а пагінація завжди зберігає ці параметри. Якщо це не зробити, користувачі отримають враження “воно живе своїм життям”.
Дев’ятий принцип — backward compatibility для параметрів. Якщо у вас вже є параметр date_from/date_to, не міняйте його на from/to “бо так красивіше” без потреби. Це ламає збережені посилання, закладки, внутрішні інструкції. Якщо дуже треба — підтримуйте обидва варіанти деякий час: новий як основний, старий як alias. Але для навчання і дисципліни — краще взагалі не перейменовувати без причини.
Де найчастіше “тихо ламають” існуючі обмеження. У місцях, де хтось міняє ->where(...) на ->orWhere(...) без групування. Де хтось переносить умови з SQL в PHP-колекції. Де хтось замінює visibleTo($user) на “приблизно те саме”. Де хтось додає join і забуває, що він множить рядки. Де хтось додає eager loading і отримує N+1 або “витягнули зайві поля”. Саме тому “аккуратні правки” — це окремий навик, а не “будь уважним”.
Висновок: акуратна правка — це коли ви не ламаєте контракт, а додаєте шар. Базові фільтри й обмеження видимості не переписуються, порядок побудови запиту не змінюється, фільтри не розширюють доступ, зміни робляться локально, а регресії страхуються хоча б одним тестом на ключове правило. Якщо ви привчите людину працювати так із першого місяця, вона перестане “ремонтувати систему молотком” і почне розвивати її без пожеж.
