ТЗ — Онбординг/визард установки (cms/onboarding)

Слой: 🔵 инфра-модуль · Зрелость доноров: ★ · Донор: — Статус: ТЗ к разработке

Назначение и возможности

Пошаговый визард первичной настройки свежей установки: от проверки системных требований до создания первого администратора и базовых настроек сайта. Снижает риск получить недонастроенную установку в проде и даёт predictable первый опыт для нового клиентского сайта.

• Проверка требований (версия PHP, расширения, права на директории, доступность Redis/PG);
• создание первого администратора (email, пароль, обязательная смена при первом входе);
• выбор профиля установки (пустой сайт / демо-контент для проверки блоков и тем);
• базовые настройки на старте (название сайта, локаль, часовой пояс, контакты);
• повторный запуск отдельного шага без прохождения визарда заново;
• блокировка визарда после завершения (повторный доступ — только через явную команду).

Зависимости и выключение

requires: — · provides: onboarding · выключение возможно только до первого прохождения визарда либо вручную после — модуль не хранит данных, критичных для рантайма.

Поведение при выключении: если визард уже пройден, отключение модуля не влияет на работу сайта — это одноразовый инструмент установки, не рантайм-зависимость.

Внешних платных API модуль не вызывает (проверки требований — локальные: PHP, файловая система, Redis/PG самого сервера) — критерий «стоимость внешних API» не применим.

Модель данных

Своих таблиц нет — использует settings-store ядра для флага completed_at и временное хранилище состояния шагов визарда (кеш, не БД).

ПДн-паспорт: собственных таблиц с персональными данными у модуля нет — хранить нечего. Email первого администратора вводится на шаге визарда, но создаётся и хранится сервисом ядра users (см. «Входные и выходные данные»), а не в таблице onboarding. Ретеншн этого email, участие в «выгрузить всё по субъекту» и «забыть по запросу» (152-ФЗ) — зона ответственности ядра (users/consents), не onboarding; модуль лишь инициирует создание записи один раз при установке.

Входные и выходные данные

Входы

Источник	Данные/поля	Чем валидируется
POST .../steps/requirements/complete	без полей (триггер проверки)	studio-роль; сами проверки — фиксированный whitelist из onboarding.required_checks
POST .../steps/admin/complete	email, password, password_confirmation	FormRequest: email уникален среди пользователей, пароль — политика ядра (длина/сложность), обязательная смена при первом входе
POST .../steps/profile/complete	site_name, locale, timezone, contacts	FormRequest whitelist полей группы настроек site/locale
POST .../steps/content-profile/complete	profile (empty|demo)	enum whitelist, неизвестное значение → 422
POST .../steps/{step}/rerun	step (slug шага)	studio-роль; step — только зарегистрированный шаг степпера
cms:onboarding:check/:reset (CLI)	без пользовательского ввода	доступ на уровне сервера (не HTTP)

Выходы

Потребитель	Данные	Формат
Filament-визард	текущий шаг, статус проверок требований	Blade через сервис модуля
/api/v1/admin/onboarding/*	конверт data/meta	JSON REST
settings-store ядра (site, locale, onboarding)	базовые настройки сайта, флаг завершения	запись через SettingsStore, не напрямую в таблицы
Первый администратор (ядро: users)	учётная запись с флагом обязательной смены пароля	создаётся через сервис ядра, не raw insert

Настройки (группа onboarding)

Ключ	Тип	Дефолт	affectsPageCache	Описание
onboarding.completed_at	datetime|null	null	—	Отметка завершения визарда (блокирует повторный автозапуск)
onboarding.demo_content_enabled	bool	false	—	Установлен ли демо-контент при онбординге
onboarding.required_checks	array	["php_version","storage_permissions","redis","database"]	—	Список обязательных проверок требований
onboarding.step_state_ttl_minutes	int	60	—	TTL кеша состояния шагов визарда
onboarding.password_min_length	int	12	—	Минимальная длина пароля первого администратора (согласована с политикой ядра)
onboarding.reset_requires_studio_confirmation	bool	true	—	Kill-switch: блокирует cms:onboarding:reset на уже настроенном сайте без явного подтверждения studio

Лимиты и квоты модуля исчерпываются двумя настройками: password_min_length — нижняя граница сложности пароля первого администратора (поведение при нарушении — 422 от FormRequest, не тихое усечение), step_state_ttl_minutes — верхняя граница жизни кеша состояния шагов (по истечении шаг считается непройденным, визард возвращается к последнему сохранённому состоянию). Оба — явные настройки с дефолтами, других лимитов (частота, размер) у модуля нет — визард не принимает файлы и не работает под нагрузкой.

Kill-switch: onboarding.reset_requires_studio_confirmation (default true) — рискованная операция здесь одна, cms:onboarding:reset на уже настроенном сайте (см. «Крайние случаи»); при включённом флаге команда на managed-инсталляции требует явного подтверждения studio-роли (интерактивный --confirm или отдельный флаг команды), а не выполняется по одному вызову. Отключать флаг допустимо только на dev/staging.

API

Метод	Путь	Доступ	Назначение
GET	/api/v1/admin/onboarding/status	studio-роль	Текущий шаг визарда и статус проверок требований
POST	/api/v1/admin/onboarding/steps/{step}/complete	studio-роль	Завершить конкретный шаг визарда
POST	/api/v1/admin/onboarding/steps/{step}/rerun	studio-роль	Повторно запустить отдельный шаг

Компоненты

Filament: страница-визард (степпер с проверками требований, формой администратора, выбором профиля). Команды: cms:onboarding:check --json (проверка требований вне UI, удобно для CI/деплоя), cms:onboarding:reset --json (сброс для повторного прохождения).

Демо-контент: onboarding не заводит собственных демо-сидеров. Профиль demo на шаге выбора контента — это оркестрация: модуль последовательно вызывает стандартный сидер demo-данных каждого включённого блока/виджета (§8 стандарта — «сидер demo-данных для каждого блока/виджета» обязателен в каждом модуле), помечая установленные сущности как демо-происхождение для последующего поиска/удаления. Свой набор демо-данных модуль не изобретает и не дублирует.

События и обмен

Событие	Когда	Payload
OnboardingStepCompleted	Шаг визарда завершён	step, completed_at
OnboardingCompleted	Визард пройден полностью	completed_at, demo_content_enabled

Реализует контракт onboarding, но не потребляется другими модулями напрямую — одноразовый инструмент установки. FilterBus и provides-контракты не используются. Слушает только собственные HTTP-запросы визарда (шаги степпера).

Таблица взаимодействий

Сущность/модуль	Канал	Направление	Что происходит
settings-store ядра (site, locale)	сервис-вызов через SettingsStore (контракт ядра)	out	Запись базовых настроек сайта на шаге профиля
users ядра	сервис-вызов через сервис создания пользователя (контракт ядра)	out	Создание первого администратора с обязательной сменой пароля
Демо-контент (страницы/типы контента ядра)	сервис-вызов через PageRepository/ContentRepository	out	Установка демо-профиля (только при demo_content_enabled)
Событие UserRegistered (ядро)	событие (канал 1)	in/out	Издаётся ядром при создании администратора визардом — потребляется аналитикой/аудитом, если включены

Фоновая работа

Фоновой работы нет — проверки требований и шаги визарда выполняются синхронно в рамках HTTP-запроса администратора установки.

Ранбук эксплуатации (§15 стандарта)

Метрики/алерты в мониторинг не выносятся — визард одноразовый инструмент установки, а не постоянно работающий сервис (время прохождения и доля незавершённых визардов не собираются как метрики; при необходимости разово смотрятся по OnboardingStepCompleted/ OnboardingCompleted в логе событий). Основной инструмент диагностики — cms:onboarding:check --json, формализуется как часть ранбука:

Симптом	Что проверить	Команда
Визард обрывается на шаге проверки требований	Какое именно требование failed (Redis/PG/права/версия PHP)	cms:onboarding:check --json
completed_at установлен, но первого администратора нет	Расхождение флага и фактического состояния (см. «Крайние случаи»)	cms:onboarding:check --json
Нужен повторный визард на уже настроенном сайте	Подтверждение studio обязательно, данные сайта не удаляются	cms:onboarding:reset --json (требует подтверждения при reset_requires_studio_confirmation=true)
Демо-контент не установился при выбранном профиле demo	demo_content_enabled должен быть false, если установка не завершилась успешно	cms:onboarding:check --json (сверка флага с фактическим наличием демо-сущностей)
Состояние шагов «потерялось» между запросами	TTL кеша шагов не истёк ли (step_state_ttl_minutes)	cms:onboarding:check --json

Бэкап: своих таблиц у модуля нет, поэтому в бэкап инсталляции ничего специфичного для onboarding не входит — временный кеш состояния шагов не персистентный и в бэкап не попадает и не должен. После восстановления инсталляции из бэкапа состояние onboarding пересобирать не нужно (флаг completed_at и администратор — в бэкапе ядра), но стоит прогнать cms:onboarding:check --json, чтобы убедиться, что рестор не оставил инсталляцию в противоречивом состоянии (флаг есть, а администратора или базовых настроек — нет).

Производительность и кеш

Объёмы: тривиальные — визард проходит один раз на инсталляцию, состояние шагов живёт секунды-минуты. Горячего пути нет — визард не участвует в публичном трафике и не влияет на бюджет запросов сайта. Состояние шагов визарда хранится в кеше (не в БД) с коротким TTL (порядка часа — прохождение визарда не растягивается на дни) — тегов инвалидации не объявляет: данные не участвуют в page-cache и живут только на время прохождения визарда. Проверки требований (php_version, storage_permissions, redis, database) выполняются синхронно и должны быть быстрыми (доли секунды каждая) — долгая проверка (например, тестовая запись в БД под нагрузкой) не должна ощутимо задерживать степпер.

Безопасность

/api/v1/admin/onboarding/* — доступ строго под studio-ролью. Создание первого администратора — FormRequest с обязательной сменой пароля при первом входе. Визард блокируется после completed_at, повторный доступ — только через cms:onboarding:reset (без этого — случайный повторный сброс настроек в проде). Специфичные векторы: визард — самый ранний код, который выполняется на свежей инсталляции, часто ещё до полной настройки rate-limit и CSRF — эти границы обязаны быть активны с первого запроса, не «донастраиваются после визарда»; создание первого администратора — единственная точка в системе, где допустим bootstrap без предварительной аутентификации, поэтому доступна только локально/до completed_at и логируется отдельно от обычного создания пользователей (аудит первого входа).

Права: onboarding.manage (только studio-роль).

Матрица ролей

Визард — единственная точка bootstrap без предварительной аутентификации: до completed_at в системе ещё не существует ни одной обычной роли (админ/менеджер/ редактор) — сайт не настроен, ролевая модель клиента ещё не применима. Поэтому матрица вырождена в одну строку:

Роль	onboarding.manage (проверка требований, создание администратора, профиль, настройки)	cms:onboarding:reset
Studio-роль / оператор установки	✅ (единственный доступный субъект до/во время визарда)	✅, с подтверждением при reset_requires_studio_confirmation=true
Админ клиента, менеджер, редактор	— (роли не существуют на этом этапе; после completed_at доступ к onboarding-эндпоинтам закрыт всем, включая созданного администратора)	—

После completed_at доступ к /api/v1/admin/onboarding/* закрыт для всех ролей, включая только что созданного администратора сайта — повторный вход в визард только через cms:onboarding:reset studio-ролью.

UX-требования

Админ (оператор установки — обычно инженер студии, не конечный клиент): пустое состояние на каждом шаге — понятная подсказка что нужно сделать («укажите email и пароль администратора»), а не голая форма без контекста; проверки требований — статус каждой отдельно (зелёная галка/красный крест с причиной, «Redis недоступен: не удалось подключиться к 127.0.0.1:6379»), не общий «провалено» без деталей; массовых действий в визарде нет по природе (степпер линейный), но повторный запуск шага — явная, не скрытая кнопка «Перезапустить этот шаг»; подтверждение необратимого — cms:onboarding:reset на уже настроенном сайте обязан явно предупреждать о последствиях (сброс завершения, не удаление данных сайта) перед выполнением; прогресс визарда виден всегда (степпер с отметками пройденных шагов), пользователь не должен гадать сколько шагов осталось.

Крайние случаи и типовые баги

• повторный запуск визарда на живом сайте → без cms:onboarding:reset визард недоступен после completed_at — это основной инвариант модуля; reset не удаляет уже сохранённые данные сайта (настройки, администратора, контент) — только снимает флаг завершения и позволяет пройти шаги заново, значения по умолчанию в форме шага подставляются из текущих настроек, а не с нуля;
• двойной сабмит шага «Создать администратора» → идемпотентность по email: повторный сабмит с тем же email не создаёт второго администратора, отдаёт ошибку «уже существует» без утечки, существует ли другой email в системе;
• параллельное прохождение визарда в двух вкладках → степпер должен опираться на серверное состояние (кеш шагов), не на клиентское — переключение в другой вкладке на уже пройденный шаг не откатывает прогресс, последний сохранённый шаг побеждает;
• обрыв соединения посреди шага с частичным эффектом (например, настройки сохранены, но событие OnboardingStepCompleted не издано из-за обрыва) → cms:onboarding:check --json должен уметь диагностировать фактическое состояние независимо от кеша шагов — источник истины для «что реально настроено» это сами настройки/пользователи, не флаг в кеше;
• демо-контент установлен, затем визард сброшен и пройден снова с профилем "пустой сайт" → старый демо-контент не удаляется автоматически повторным прохождением — модуль явно помечает демо-сущности так, чтобы их можно было найти и удалить одной командой, но не делает это неявно при reset;
• отсутствие Redis/БД на этапе проверки требований → визард не должен падать 500 — шаг проверки отображает failed-статус конкретного требования и блокирует переход дальше, но сам визард (степпер) остаётся доступен для повторной проверки после устранения;
• выключение модуля до завершения визарда (нетипичный, но возможный сценарий на managed-инсталляции) → §3 стандарта: деградация, не поломка — сайт остаётся ненастроенным (без базовых настроек/администратора), что само по себе не критично для приложения, но требует ручной настройки через другие инструменты (dev-panel/ artisan) взамен визарда;
• пустой профиль контента при выборе "демо" (несогласованное состояние — выбран demo, но контент не успел установиться из-за сбоя) → demo_content_enabled в настройках должен отражать фактический результат установки, не намерение — выставляется только после успешного завершения установки демо-данных;
• измерения locale/city/site — визард настраивает единственную (дефолтную) локаль и не оперирует city/site по определению (это ранняя стадия установки, до включения cms/multisite/cms/multicity); явно зафиксировать, что мультисайтовая/мультигородская настройка — отдельный шаг за пределами онбординга, не входит в это ТЗ;
• противоречивая комбинация: onboarding.completed_at установлен вручную (в обход визарда, например при переносе инсталляции с другого сервера), но администратор так и не создан → визард не должен считаться «пройденным» только по флагу — cms:onboarding:check обязан отдельно проверять наличие хотя бы одного администратора и предупреждать о несоответствии, если флаг стоит, а условие не выполнено.

Донорский код

Донор: — (новая разработка)

Миграция legacy-данных (§16 стандарта) не применима: onboarding — визард первичной установки новой инсталляции, он не импортирует данные с донорских сайтов и не мигрирует легаси-таблицы — это задача модулей-получателей контента (import и конкретные модули данных), не onboarding.

Тесты и приёмка

• [ ] Контрактные тесты: визард недоступен повторно после completed_at без явного reset;
• [ ] health-чек модуля = проверка требований (cms:onboarding:check --json) переиспользуется вне визарда;
• [ ] деградация при выключении — уже настроенный сайт продолжает работать без визарда;
• [ ] права ограничивают визард только studio-ролью;
• [ ] демо-контент помечен так, что легко отличим и удаляем одной командой;
• [ ] повторный запуск отдельного шага не ломает уже сохранённые настройки других шагов;
• [ ] reset на уже настроенном сайте не удаляет данные — только снимает флаг завершения;
• [ ] двойной сабмит создания администратора не создаёт вторую учётную запись;
• [ ] cms:onboarding:check фиксирует несоответствие «флаг завершён, но администратор отсутствует»;
• [ ] cms:onboarding:reset на managed-инсталляции с reset_requires_studio_confirmation=true отказывает без явного подтверждения studio (kill-switch работает);
• [ ] неавторизованная/не-studio роль не получает доступ ни к одному онбординг-эндпоинту ни до, ни после completed_at (матрица ролей соблюдена);
• [ ] профиль demo вызывает существующие сидеры demo-данных блоков/виджетов модулей, а не собственный набор фикстур onboarding;
• [ ] контрактный набор cms-testing зелёный, пакет протестирован в testbench-изоляции;
• [ ] feature-тест на каждый роут API; тестовая БД только onboarding_test, migrate:fresh/refresh/reset запрещены.