# Локальное окружение

Разработка идёт на Windows с Laragon. Глобальная версия PHP в Laragon не меняется, поэтому другие проекты
не затрагиваются: инструменты проекта подключаются в конкретную сессию терминала.

| Компонент | Версия | Где лежит |
|---|---|---|
| PHP | 8.5 (TS, x64) | `D:\laragon\bin\php\php-8.5.11-Win32-vs17-x64` |
| PostgreSQL | 17 (ICU `ru-RU`, UTF-8) | `D:\laragon\bin\postgresql\postgresql-17.11`, данные — `D:\laragon\data\postgresql` |
| Composer | 2.9 | `D:\laragon\bin\composer` |
| Node.js | 22 | `D:\laragon\bin\nodejs\node-v22` |

Пути можно переопределить переменными `LARAGON_ROOT`, `LOYAL_PHP_DIR`, `LOYAL_NODE_DIR`, `LOYAL_PG_DIR`,
`LOYAL_PG_DATA`.

## Первый запуск

По умолчанию Windows запрещает запуск PowerShell-скриптов. Один раз разрешите локальные скрипты для своего
пользователя (или запускайте их через `powershell -ExecutionPolicy Bypass -File ...`):

```powershell
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```

Затем в корне проекта:

```powershell
. .\scripts\dev\env.ps1                    # PHP 8.5, Composer, Node, psql — в PATH текущей сессии
composer install
copy .env.example .env
php artisan key:generate
php artisan pii:generate-keys              # ключи шифрования ПДн (ADR-0008); не теряйте их
.\scripts\dev\postgres.ps1 init            # кластер PostgreSQL; пароль суперпользователя попадёт в .env
```

Заполните в `.env` пароли ролей `DB_PASSWORD`, `DB_OWNER_PASSWORD`, `DB_SYSTEM_PASSWORD` (любые случайные
строки) и создайте роли и базы:

```powershell
php artisan db:bootstrap --database=loyal --database=loyal_test
composer migrate                           # миграции от имени владельца схемы
npm ci --ignore-scripts --prefix sdk/typescript   # компилятор TypeScript для SDK, приложения кассы и виджетов
composer check                             # Pint, Larastan, Deptrac, тесты
```

Сотрудник для входа в кабинеты (ADR-0013): `php artisan staff:create admin@example.test --name="Администратор"`
(команда дважды спросит пароль), затем `php artisan staff:grant admin@example.test --platform --role=admin`. Консоль
платформы — `http://localhost:8000/console` (`php artisan serve`): вход по паролю; приложение-аутентификатор (Яндекс
Ключ, Google Authenticator и др.) с кодами восстановления подключается по желанию в профиле. Готовые
демо-записи — оператор и владелец демо-мерчанта с паролем из `database/seeders/LocalCabinetSeeder.php` — создаёт
`php artisan db:seed --class=LocalCabinetSeeder` (только в окружении `local`, повторный запуск ничего не дублирует).
Ресурсы Filament публикует `php artisan filament:assets` (выполняется после `composer install`).

Веб-касса (ADR-0016): приложение собирает `composer till:build` в папку сборки `public/till-app/<версия>` (не в git;
компилятор TypeScript — из `sdk/typescript/node_modules`, см. первый запуск). Демо-кассу делает
`php artisan db:seed --class=LocalTillSeeder` (только в окружении `local`): в демо-мерчанте — программу с
опубликованными правилами, точку с веб-кассой, кассира с PIN-кодом из `database/seeders/LocalTillSeeder.php` и
участника с баллами. Каждый запуск печатает ссылку привязки с новым кодом: откройте её на `http://localhost:8000`
(`php artisan serve`) — без HTTPS касса работает только на самой машине (`localhost`, `127.0.0.1`, `[::1]`). Коды
подтверждения (регистрация, списание баллов) локально не отправляются, а пишутся в `storage/logs/laravel.log`.

Виджеты участника (ADR-0018, `docs/api/widgets.md`): `composer widgets:build` собирает `frontend/widgets` в новую
версию `public/embed/v1/<версия>/loyal-widgets.js` и называет её в `build.json`. Сборки хранятся в git — после
изменения виджетов или частей SDK, которые в них попадают, закоммитьте новую сборку (`composer widgets:test` проверяет,
что она есть). Сборки, которых нет в git, новая сборка удаляет сама; закоммиченные не трогайте: их могли закрепить
сайты (`tests/Architecture/WidgetBuildsTest.php` следит по истории git). Демо — `php artisan db:seed --class=LocalWidgetsSeeder`
(только в окружении `local`, поверх демо кассы: ключ сайта демо-мерчанта, токен которого нигде не показывается) и
страница `http://localhost:8000/widgets-demo`: она переводит на адрес `127.0.0.1` или `[::1]`, на котором отвечает
сервер, — это «другой сайт», чьи виджеты говорят с API на `localhost` (страница сайта самого API не отправляет `Origin`).

Письма сотрудникам (ссылка «Забыли пароль?», письмо о сбросе 2FA) уходят через очередь: без запущенной очереди
(`composer dev` или `php artisan queue:work`) их нет. Локально `MAIL_MAILER=log` — письмо со ссылкой появляется в
`storage/logs/laravel.log`. Ссылки в письмах строятся от `APP_URL` (и `CONSOLE_DOMAIN` для консоли), поэтому
`APP_URL` должен совпадать с адресом, по которому открываются кабинеты. Вне разработки нужны асинхронная очередь
(`QUEUE_CONNECTION` не `sync`) и почтовый драйвер, который доставляет письма (`MAIL_MAILER` не `log` и не `array`):
иначе письма сотрудникам не уходят.

Пригласить оператора можно в консоли («Приглашения в консоль»): локально письмо со ссылкой появится в
`storage/logs/laravel.log`, ссылка откроется на `APP_URL`. Принятое приглашение ведёт на вход по паролю.

«Состояние системы» в консоли (ADR-0015) показывает то, что раз в минуту отмечает и считает планировщик
(`platform:heartbeat`, `platform:health`). `composer dev` планировщик не запускает, а очередь слушает только `default`,
поэтому локально страница честно показывает сбои. Чтобы увидеть её зелёной, запустите планировщик
`php artisan schedule:work` и очередь для обеих очередей платформы: `php artisan queue:listen --queue=default,offline`.
Учтите, что планировщик выполнит и остальные задачи по расписанию — в том числе отправку вебхуков на адреса из
локальной базы.

Для `cmd.exe` вместо `env.ps1` есть `scripts\dev\env.cmd`.

## Каждый день

```powershell
. .\scripts\dev\env.ps1
.\scripts\dev\postgres.ps1 start           # stop | status | psql
composer dev                               # сервер, очередь и Vite
```

## Команды

| Команда | Что делает |
|---|---|
| `composer check` | всё, что проверяет CI: Pint, Larastan, Deptrac, Pest, тесты SDK на TypeScript, приложений кассы и кабинета покупателя и виджетов |
| `composer till:build` / `composer till:test` | сборка приложения веб-кассы в `public/till-app` / сборка и его тесты |
| `composer portal:build` / `composer portal:test` | сборка приложения кабинета покупателя в `public/portal-app` / сборка и его тесты |
| `composer widgets:build` / `composer widgets:test` | новая сборка виджетов участника в `public/embed/v1` / проверка, что она закоммичена, и тесты виджетов |
| `composer test` | тесты (Pest) на базе `loyal_test` |
| `composer lint` / `composer fix` | проверка / исправление стиля (Pint) |
| `composer analyse` | статический анализ (Larastan, уровень 8) |
| `composer deptrac` | проверка границ модулей |
| `composer migrate` | миграции от имени владельца схемы |
| `php artisan db:bootstrap` | роли, базы и права по умолчанию (только local и CI) |
| `php artisan make:module <name>` | новый модуль; затем `composer update modules/<name>` и строка в `deptrac.php` |
| `php artisan staff:create` / `staff:grant` / `staff:revoke` / `staff:disable` | учётные записи сотрудников и их роли |

## Что важно знать

- **Роли БД.** Приложение работает ролью `loyal_app`, на которую действует RLS; миграции выполняет
  `loyal_owner`; межтенантные процессы — `loyal_system` (ADR-0002). Без контекста тенанта роль приложения
  видит ноль строк в таблицах тенантов.
- **Тесты.** Feature-тесты идут через роль приложения внутри транзакции, которая откатывается после теста.
  Соединение `pgsql_system` — отдельная сессия: данных тестовой транзакции оно не видит. Если тесту нужна
  системная роль, фикстуры коммитятся через неё и удаляются в конце (пример —
  `app-modules/tenancy/tests/Feature/SystemRoleTest.php`).
- **Linux-only компоненты.** Horizon и Octane требуют `pcntl` и не работают на Windows. Локально очередь
  обрабатывает `php artisan queue:work`; Horizon и Octane проверяются в Docker и CI.
- **Cookie сеанса и хосты.** Локально приложение работает по http, поэтому в `.env` стоит
  `SESSION_SECURE_COOKIE=false`. В production нужны `SESSION_SECURE_COOKIE=true`, `SESSION_COOKIE=__Host-loyal_session`
  и `APP_DEBUG=false`, а консоли — свой хост в `CONSOLE_DOMAIN` (кабинеты остаются на хосте `APP_URL`): иначе страницы
  кабинетов отвечают ошибкой 500, а команды и API продолжают работать. За обратным прокси задайте его адреса в
  `TRUSTED_PROXIES`. Время в кабинетах показывается в поясе `CABINET_TIMEZONE` (по умолчанию `Europe/Moscow`).
  Оболочке веб-кассы можно дать свой хост в `TILL_DOMAIN` (только имя хоста): тогда `/till` отвечает только на нём, и
  браузер хранит cookie кассы отдельно от кабинетов; без него, при `CONSOLE_DOMAIN`, касса отвечает на хосте
  `APP_URL`, но не на хосте консоли. Приложение кассы собирается в `public/till-app` (`composer till:build`, и при
  развёртывании тоже) и работает только по HTTPS: SDK не отправляет ключ по http никуда, кроме самой машины
  (`localhost`, `127.0.0.1`, `[::1]`).
- **Кабинет покупателя.** Ему нужен свой хост в `PORTAL_DOMAIN` (кабинет программы — `https://<хост>/p/<имя>/`). Хост
  до 13 знаков держит ссылки «Не вы?» в SMS о списании и о подключении MAX и ВКонтакте одним SMS; до 33 — двумя
  частями; длиннее — ссылок нет: уведомления о списании не уходят, а MAX и ВКонтакте к картам не подключаются
  (ADR-0022, ADR-0023, ADR-0024). Коробке «Я не
  робот» нужен ещё один хост, `PORTAL_CAPTCHA_DOMAIN`, лучше на другом домене (не поддомен домена кабинета): её
  скрипт чужой, и на хосте кабинета он дотянулся бы до сеансов всех кабинетов в браузере. Оба хоста — только имена, не хосты кабинетов, консоли и кассы; хост коробки
  добавьте в хосты капчи в Yandex Cloud. Без него, но с ключами SmartCaptcha кабинет не отправляет коды, а «Состояние
  системы» об этом предупреждает. Приложение кабинета собирается в `public/portal-app` (`composer portal:build`, и при
  развёртывании тоже: без сборки страница кабинета остаётся на «Загрузка…») и работает только по HTTPS, как касса. За
  Apache правило `public/.htaccess` не убирает слеш в конце адреса кабинета: адрес со слешем — граница его приложения.
  Локально кабинет пробуют на мерчанте без каналов: `php artisan db:seed --class=LocalPortalSeeder` — кабинет
  `http://localhost:8000/p/kofe-u-doma/`; код входа, как и код вступления для номера, которого нет в программе,
  пишется в `storage/logs/laravel.log`.
- **PostgreSQL Laragon.** Laragon запускает собственный PostgreSQL (`data\postgresql-17`) на порту 5432, поэтому
  кластер проекта слушает порт из `DB_PORT` — 5433 (`postgres.ps1 init` берёт его из `.env`). Запускайте кластер
  проекта командой `.\scripts\dev\postgres.ps1 start`; экземпляр Laragon ему не мешает.
