Правила разработки 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-вьюха обязана содержать:

@section('breadcrumb') — хлебные крошки сразу после @section('content_header'):
```
@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)
- Вложенные разделы (напр. значения справочника): добавлять все промежуточные уровни
1. Кнопка "Назад" — в @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
- На страницах-списках кнопка "Назад" не нужна (они сами являются точкой входа)
- На страницах создания/редактирования — всегда ставить кнопку "Назад" к родительскому списку

CLAUDE.md 4.9 KB Historie Surový