# Правила разработки tocha_app

## Обязательная документация (главное правило)

**В каждом нестандартном файле (созданном или изменённом) обязательно должны быть русские комментарии:**

- **PHP-файл**: блок `/* ... */` в начале файла — что это, когда создано, маршруты/зависимости;
  `//` или `/** */` перед каждым методом — что делает и откуда берёт данные
- **Blade-шаблон**: `{{-- ... --}}` в самом начале — контроллер, переменные, логика
- **Миграция**: блок `/* ... */` — что создаёт, индексы, FK, причина создания
- **Сидер**: блок `/* ... */` — что заполняет, идемпотентность, запуск

**Это правило применяется к каждому файлу при каждом редактировании.**

---

## Стек и инструменты

- PHP 8.3+, Laravel 13, MySQL (`tocha_app` DB, root, нет пароля, localhost:3306)
- `jeroennoten/laravel-adminlte` — UI панели; всегда использовать `@extends('adminlte::page')`
- Vite + TailwindCSS v4 для фронтенда
- PHPUnit v12 (НЕ Pest) для тестов
- Laravel Pint — форматирование кода (запускать после PHP-правок: `./vendor/bin/pint`)

## Лимит размера файла

**Максимум 300 строк на файл** — правило без исключений для всех наших файлов:

- Если файл вырос за 300 строк — обязательно разбить до коммита
- **PHP-контроллеры** → вынести методы в отдельные Action-классы или трейты
- **Blade-шаблоны** → вынести секции в `partials/` через `@include`
- **PHP-классы** → разнести логику по трейтам (`app/Support/Traits/`)
- **Данные-массивы** (сидеры) → вынести в отдельный PHP-файл через `require`
- **Исключение**: системные конфиги пакетов (`config/adminlte.php` и подобные) — не трогать
- Проверка: `find . -name "*.php" -o -name "*.blade.php" | xargs wc -l | sort -rn | awk '$1>300'`

---

## Конвенции

- После каждого PHP-файла запускать `./vendor/bin/pint путь/к/файлу`
- Использовать `php artisan make:` команды для создания моделей/контроллеров/миграций
- Все маршруты в `routes/web.php`, группа `/admin/*` защищена middleware `admin`
- Для форм: единая вьюха `form.blade.php` для create и edit (проверка `isset($car)`)
- Спрашивать пользователя перед деструктивными операциями (reset, drop, force push)

## Хлебные крошки и кнопка "Назад" в admin-вьюхах

**Каждая admin blade-вьюха обязана содержать:**

1. **`@section('breadcrumb')`** — хлебные крошки сразу после `@section('content_header')`:
   ```blade
   @section('breadcrumb')
       <li class="breadcrumb-item"><a href="{{ route('admin.dashboard') }}">Главная</a></li>
       <li class="breadcrumb-item"><a href="{{ route('admin.раздел.index') }}">Раздел</a></li>
       <li class="breadcrumb-item active">Текущая страница</li>
   @stop
   ```
   - Страница-список: `Главная > Название раздела (active)`
   - Форма создания/редактирования: `Главная > Раздел > Добавить/Редактировать (active)`
   - Вложенные разделы (напр. значения справочника): добавлять все промежуточные уровни

2. **Кнопка "Назад"** — в `@section('content_header')` у страниц создания/редактирования:
   ```blade
   @section('content_header')
       <div class="d-flex justify-content-between align-items-center">
           <h1 class="m-0">Заголовок</h1>
           <a href="{{ route('admin.раздел.index') }}" class="btn btn-default btn-sm">
               <i class="fas fa-arrow-left"></i> Назад
           </a>
       </div>
   @stop
   ```
   - На страницах-списках кнопка "Назад" не нужна (они сами являются точкой входа)
   - На страницах создания/редактирования — всегда ставить кнопку "Назад" к родительскому списку