| 1 | # Laravel Playbook v1 |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | Операционный контракт для приложений на **Laravel** (ориентир **10.x / 11.x / 12.x**; точная версия — из `composer.lock`). Сочетать с `playbook-php-v1.md` для вопросов чистого PHP/Composer. **Полный контур по версиям и смежным темам:** `index-knowledge-laravel-cluster-v1.md` → целевые `kb-laravel-*` (не грузить все сразу). |
| 6 | |
| 7 | ## Scope |
| 8 | |
| 9 | - Маршруты, middleware, контроллеры — границы ответственности |
| 10 | - Конфиг/кеш/окружение |
| 11 | - Очереди и scheduler |
| 12 | - Тесты и миграции схемы |
| 13 | |
| 14 | ## Evidence-Based Working Format |
| 15 | |
| 16 | - **Fact:** версии `laravel/framework` и PHP из `composer.lock` / `php artisan --version`. |
| 17 | - **Hypothesis:** ожидаемый эффект изменения (latency, корректность, side effects в очередях). |
| 18 | - **Check:** `php artisan test`, smoke на критичных маршрутах; для очередей — прогон worker в dev/stage. |
| 19 | - **Decision criterion:** тесты + отсутствие регрессий в логах при типовой нагрузке. |
| 20 | - **Confidence mark:** явно. |
| 21 | |
| 22 | ## Core Contracts |
| 23 | |
| 24 | - **Convention over configuration:** сначала искать «как принято в Laravel», затем кастом. |
| 25 | - Новые HTTP-фичи: явно определить auth, validation, authorization policy, rate limiting где уместно. |
| 26 | - Долгие операции — в **queue**, не в синхронном запросе без веской причины. |
| 27 | |
| 28 | ## Config & Deploy Contracts |
| 29 | |
| 30 | - После изменения `.env` или `config/*` в проде — `config:cache` в пайплайне или осознанный отказ с обоснованием. |
| 31 | - Документировать обязательные переменные окружения. |
| 32 | |
| 33 | ## Data Contracts |
| 34 | |
| 35 | - Изменения схемы — только через **миграции**; откат плана миграции описывать. |
| 36 | - Подозрение на N+1 — профилировать запросы (Telescope/debugbar на stage, лог запросов). |
| 37 | |
| 38 | ## Queue & Schedule Contracts |
| 39 | |
| 40 | - У каждого job: retries, timeout, idempotency note. |
| 41 | - Scheduler: проверить cron на всех репликах приложения (не дублировать `schedule:run` без координации). |
| 42 | |
| 43 | ## Testing Contracts |
| 44 | |
| 45 | - Минимальный набор feature-тестов на аутентификацию и критичные API. |
| 46 | - Использовать фабрики вместо ручного создания больших графов объектов в тестах. |
| 47 | |
| 48 | ## Metrics |
| 49 | |
| 50 | - Failed jobs count; latency p95 основных маршрутов; ошибки 5xx после деплоя. |
| 51 | |
| 52 | ## Revisit Triggers |
| 53 | |
| 54 | - Upgrade Laravel мажора — читать **Upgrade Guide** ветки docs (`kb-laravel-versions-upgrades-v1.md`). |
| 55 | - Включение Octane/Horizon/Reverb — `kb-laravel-async-realtime-deployment-v1.md` (память, restart воркеров, channel auth). |
| 56 | - Новый UI-стек (Livewire/Filament/Inertia) — `kb-laravel-frontend-stacks-v1.md`. |
| 57 | |
| 58 | ## Full Laravel pass (по явному запросу) |
| 59 | |
| 60 | 1. `kb-laravel-fundamentals-v1.md` |
| 61 | 2. `kb-laravel-versions-upgrades-v1.md` (если вопрос версий/миграции) |
| 62 | 3. Далее **один** тематический kb из кластера: пакеты, security, Symfony, async/realtime, frontend — см. таблицу в `index-knowledge-laravel-cluster-v1.md`. |
| 63 | |
| 64 | ## Layer (memory-architecture) |
| 65 | |
| 66 | - **L1:** этот playbook после status и при необходимости `playbook-php-v1.md`. |
| 67 | - **Deep:** фундамент — `kb-laravel-fundamentals-v1.md`; углубление — `kb-laravel-*` по кластеру `index-knowledge-laravel-cluster-v1.md`. |
| 68 | |