# 07 · Гостевой доступ

[← Home](Home.md)

Гость (курьер, такси, родственник) открывает шлагбаум сам — по ссылке с
QR-кодом, короткому коду или PIN — без звонка жителю и без регистрации.
По умолчанию пропуск живёт **12 часов**; всё логируется.

## Как это выглядит

```
Житель (кабинет) или админ            Гость (телефон, без аккаунта)
─────────────────────────            ─────────────────────────────
Создать пропуск:                      Получает ссылку (мессенджер/SMS):
 срок 12 ч, имя «Курьер»                https://gate.example.com/guest/<token>
      │                                       │
      ▼                                       ▼
Ссылка + QR + код 7K4M-Q2XD           Страница: адрес ЖК, срок, кнопка
 + PIN 554145                          «Открыть шлагбаум» (большая)
                                              │
                                              ▼
                                       Шлагбаум открыт, событие в журнале:
                                       «Иванов И.И. (гость Курьер)», guest
```

## Три способа открыть (для гостя)

1. **Ссылка/QR** — `/guest/<token>`: подписанная HMAC-ссылка (токен не
   подбирается), страница с большой кнопкой; QR ведёт на неё же. Работает
   без сессии и CSRF — защиту обеспечивает подпись + rate-limit.
2. **Короткий код** — `7K4M-Q2XD` на странице `/guest` («открыть по коду»):
   продиктовать по телефону, ввести на планшете охраны. Алфавит кода не
   содержит неоднозначных символов (0/O, 1/I/L).
3. **PIN** — 6 цифр для клавиатуры панели BAS-IP (`pin_fallback`).

## Создание

* **Житель**: кабинет → «Гостевой доступ» (если карточке разрешено
  `allow_guest_pass`). Поля: срок (пресеты `1, 2, 4, 8, 12, 24, 48, 72` ч),
  имя гостя, телефон, госномер, цель. Обязательность полей — в настройках.
* **Админ/оператор**: `/admin/guest` → «Создать» от имени любого жителя.
* **API**: `POST /api/v1/guest/passes` (scope `guest.create`) — для
  интеграций (домофон, бот, CRM курьеров).
* **CLI**: `bin/bas-ip guest:create --resident=5 --hours=12 --name="Курьер"`.

## Ограничения и безопасность

| Механизм | Значение по умолчанию |
|---|---|
| Срок по умолчанию / максимум | 12 ч / 72 ч |
| Открытий в пределах срока | без лимита (`max_uses=0`) или N |
| Активных пропусков на жителя / на дом | 5 / 200 |
| Созданий в сутки на жителя | 10 |
| Rate-limit страницы и открытия | `guest_open: 20/мин` на IP + cooldown 3 с |
| Подпись ссылки | HMAC ключом приложения (`signed_link`) |
| Автоистечение | cron `schedule:run` гасит истёкшие |

Гостевое открытие не требует авторизации, поэтому защищено комплексно:
подпись + одноразовость токена по сроку + rate-limit + журнал. Попытки
открытия с истёкшим/отозванным кодом дают понятную страницу и пишутся
в журнал как `denied`.

## Журналирование

Каждое событие: **кто** (житель-владелец пропуска + имя гостя), **когда**,
**тип доступа `guest`**, квартира, устройство, результат, источник (web/код/
API), счётчик использований пропуска. Видно в:

* `/admin/gate` (журнал ворот, фильтр «гостевые»),
* карточке пропуска (`/admin/guest`) — сколько раз и когда открыли,
* кабинете жителя (`/cabinet/log`),
* `bin/bas-ip gate:log --access=guest`,
* лог-канале `gate` (`storage/logs/gate-*.log`).

Уведомления (настраивается): жителю при создании (`guest_created`),
при использовании (`guest_used`), гостю — приглашение (`guest_invite`).

## Управление пропусками

* **Отозвать** — в кабинете жителя, в `/admin/guest`, `guest:revoke <код>`;
  причина пишется в журнал.
* **Истёкшие** — гасятся автоматически (`auto_revoke_expired`).
* **Экспорт** — `/admin/guest/export`.

## Настройка

`config.guest` и **Админка → Настройки → Гостевой доступ**: сроки, пресеты,
лимиты, обязательные поля, PIN, синхронизация госномера с whitelist панели
(`car_sync`, driver-specific), уведомления.

---
Дальше: [08 · Биллинг](08-Billing.md)