October CMS · REST

Как бэкенду работать с этим API

Репозиторий отдаёт JSON четырём витринам. Тема CMS — заглушка. Ломать форму ответа нельзя.

Sandbox.Restapi api.corp.sotrans.ru

Что это за проект

October CMS 3 / Laravel 9, но продукт — не страницы CMS, а плагин Sandbox.Restapi. Фронты mz, truckland, bereit и piterbus ходят сюда за каталогом, меню, новостями, страницами и формами.

Прод: https://api.corp.sotrans.ru, админка /admin. Установка с нуля — в корневом SETUP.md.

Стек

PHP 8.0+, Laravel 9, October CMS 3.
Плагин API: plugins/sandbox/restapi (PSR-4: Http/, Services/, Console/).
Контент: Tutorial (страницы/блоки), Shopaholic (каталог), Indikator News, Vacancy, Employees, City.Map, Polikarpova.Seo.
Формы уходят в Битрикс (BitrixService, FormService).

Локальный запуск

База — как в .env (DB_DATABASE=api_corp_sot). Удобно накатить прод-дамп, чтобы судить о данных.
composer install, права на storage/ и bootstrap/cache/.
Сервер: php artisan serve --host=192.168.11.129 --port=8888. С 127.0.0.1 в этой сети часто не достучаться.
Проверка: GET /api/mz/catalog и главная /.

Тема demo Это заглушка лендинга API, не витрина. Четыре сайта её не рендерят. ACTIVE_THEME=demo в .env не меняйте без замены папки темы.

Четыре фронта

Код	Фронт	Сайт в админке
`mz`	mz.sotrans.ru	mz.sotrans.ru
`truckland`	truckland.ru	truckland.ru
`bereit`	bereit.sotrans.ru	bereit.ru
`piterbus`	pbc-dev.sotrans.ru	piterbus.com
`it`	it.sotrans.ru	it.sotrans.ru

Коды зашиты в routes.php (mz|truckland|bereit|piterbus|it) и в OctoClub\Tutorial\Classes\SiteResolver. Домен из роута в код: первое слово до точки.

Bereit /catalog/filtered и меню каталога отдают 500 и на проде: нет корня Shopaholic. Не «чините» это сменой контракта для остальных сайтов.

Где лежит код

Путь	Зачем
`plugins/sandbox/restapi/routes.php`	v1 `/api/{site}` и v2 `/api/v2/{site}`
`Http/Controllers/`	Тонкие контроллеры
`Services/`	Сборка ответа, меню, формы, sitemap
`Http/Resources/`	Маппинг в DTO/массивы
`swagger.json`, `swagger-v2.json`	Спека, её отдают роуты `/swagger.json`
`plugins/sandbox/restapi/views/`	Swagger UI
`docs/`	Инструкции (эта и соседние HTML)

Linux чувствителен к регистру. Каталоги Http и Services с большой буквы. Нижний регистр http/ / services/ уже удалён — не возвращайте дубли.

Сайт в URL

Контент режется по Tutorial Category / Shopaholic-корню, имя которых совпадает с доменом сайта. Резолв — SiteResolver::extractCode() и candidateNames(). Для piterbus предпочитаемый домен piterbus.com.

Новый сайт — это не только фронт: код в where роутов, Swagger enum, KNOWN_SITES, запись сайта в админке и корень каталога.

Как добавить метод

Роут в routes.php. Если контракт старых витрин не должен меняться — только v2.
Контроллер в Http/Controllers, логика в Services, не в маршруте.
Поля ответа опишите в swagger.json / swagger-v2.json. UI читает эти файлы с Cache-Control: no-store.
Проверьте все четыре кода сайта, не только mz.
Сверьте HTTP-статусы с продом по Swagger GET (локальная база ≠ прод по телу).

Меню шапки: CatalogController::getHeaderTestMenuCatalog + MenuFormatter::formatTestHeaderMenu (дерево children / link). Не подменяйте плоским getHeaderMenuCatalog.

Swagger

UI: /swagger, /swagger-v2.
Файлы в корне репозитория, не генерировать на лету. Генератор swagger-php убран.
Пер-сайтовые копии JSON/HTM тоже убраны — один файл на версию, сайт выбирается в UI.

Кроны и логи

Sitemap: restapi:generatesitemapcommand ежедневно в 03:00, не каждую минуту.
Логи событий: в system_event_logs пишутся warning+, eventlog:prune в 03:15. Не возвращайте Log::info в горячие методы — таблица снова вырастет до гигабайт.

Регистрация кронов — plugins/sandbox/restapi/Plugin.php → registerSchedule.

Плагины

Живые: Restapi, Tutorial, Shopaholic + Properties, News, Vacancy, Employees, Map, Seo, Services, RicheditorSnippets.

Отключённые в БД (is_disabled=1) могут остаться строками без файлов. Так и задумано: plugin:disable, не plugin:remove. Remove дропает таблицы.

Builder снят. DaData в composer есть, из API не вызывается — не выкидывать без отдельного решения.

Чего не делать

Менять JSON v1 «для красоты» — отвалятся четыре фронта.
plugin:remove и DROP таблиц «мусорных» плагинов.
Писать отладку в Log::info на проде.
Копировать контроллеры в http/ строчными буквами.
Тащить обратно demo-тему October, Leaflet, Wibxi, Staff, MagicForms, RainLab.Sitemap.

Чеклист перед мержем

Четыре сайта, v1 и v2: статусы как на проде (кроме известных 500 Bereit).
Меню шапки — дерево, фронт MZ его ест.
Swagger v1 содержит header/footer menu, если трогали меню.
Нет новых Log::info в контроллерах выдачи.
Контентщикам Питербас по-прежнему хватает их инструкции.