# 05 · Гид администратора

[← Home](Home.md)

Обход всех разделов админки: что где лежит и как этим пользоваться каждый день.
Админка доступна ролям `admin` (всё) и `operator` (жители, касса, шлагбаум,
рассылки — без настроек/пользователей/системы).

## Дашборд (`/admin`)

* Сводка: активные жители, собираемость за период, долг, открытия за сегодня.
* График открываний по дням, последние события, должники-топ.
* Быстрые действия: открыть шлагбаум, создать начисление, гостевой пропуск.
* Статус устройств и очереди уведомлений.

## Жители (`/admin/residents`)

**Список**: по умолчанию только **активные**; фильтры — статус
(активные/отключённые/все/без доступа/должники/удалённые), корпус, поиск
(ФИО, квартира, телефон, e-mail, госномер — всё сразу). Колонки: квартира,
ФИО, контакты, баланс/долг, флаги. Массовые операции над выделенными:
включить/выключить, доступ, уведомления, участие в оплатах.

**Карточка жителя** — всё в одном месте:

* данные: ФИО, квартира/корпус/этаж, площадь, число жителей, доля, роль
  (собственник/арендатор), комментарии;
* чекбоксы: **«доступ»** (разрешено открывать), **«включен»** (участвует во
  всём: списках, расчётах, рассылках), «участвует в оплатах», «гостевой
  доступ», «уведомления»;
* **контакты**: несколько телефонов и e-mail (метки: мобильный/домашний/
  рабочий, флаг «слать уведомления», верификация);
* **машины**: несколько на жителя — госномер (валидация формата РФ/кириллица)
  + марка/модель + цвет, активные/архивные;
* **оплаты**: счета и оплаты жителя, баланс, кнопка «Принять оплату»,
  «Выставить счёт» (ручной);
* **журнал**: открывания жителя, гостевые пропуска, история изменений карточки;
* **учётная запись**: создать/привязать кабинет жителя (логин, временный
  пароль, требование смены при первом входе);
* быстрое открытие шлагбаума «от имени квартиры».

**Форма жителя**: обязательны фамилия и квартира; телефоны нормализуются
в E.164; e-mail валидируется; госномера — с подсказкой формата; площадь/доля —
для распределения сумм. Удаление — мягкое (восстанавливается из фильтра
«удалённые»).

## Оплаты (`/admin/billing`)

Вкладки: **Начисления** · **Счета** · **Платежи** · **Должники** · **Мастер**.

**Мастер начисления** (главный сценарий месяца):

1. Общая сумма (запоминается между запусками) → предпросмотр: сколько
   активных участников, сколько с каждого, сумма счетов (сходится до копейки).
2. Способ распределения: **поровну** (default), **по площади**, **по числу
   жителей**, **по доле**.
3. Период (метка + даты), срок оплаты (дней или точная дата), ссылка на
   оплату (с подстановками `{id}`, `{apartment}`, `{sum}`, `{period}`),
   сообщение рассылки (или автогенерируемое из шаблона `payment_new`).
4. «Выставить счета» → счета у всех активных + очередь уведомлений.

**Начисление (charge)** — групповая операция: статусы `draft → issued →
closed/cancelled`; внутри — счета участников. Действия: **перерасчёт**
(новая сумма/состав → корректирующие счета, выставленные не трогаются),
**рассылка** (повторно/выборочно), **экспорт**, закрыть/отменить.

**Счета (invoices)**: номер, житель, сумма, оплачено, остаток, срок, статус
(`pending/partial/paid/overdue/void`), связь с начислением. Операции: принять
оплату, сторнировать (void), ручная корректировка.

**Платежи (payments)**: дата, сумма, метод (наличные/перевод/карта/онлайн/
бартер), внешний ID (из платёжки), комментарий; оплата распределяется FIFO
по старейшим счетам; переплата падает на баланс жителя. Удаление платежа
откатывает счёт обратно.

**Должники**: все активные с непогашенными счетами, сортировка по долгу/
просрочке, кнопка **«Напомнить»** — рассылка `payment_overdue` всем сразу.

Подробнее о деньгах: [08 · Биллинг](08-Billing.md).

## Шлагбаум (`/admin/gate`)

* **Журнал** (`/admin/gate`): каждое открытие — время, кто (житель/гость/
  оператор/API), тип доступа (`own/guest/manual/remote/emergency/api`),
  квартира, устройство, результат (успех/отказ/ошибка). Фильтры по датам/
  типу/результату/жителю, экспорт CSV. На панели оператора рядом с кнопкой —
  живой кадр камеры (события хранят текст, а не фото).
* **Статистика** (`/admin/gate/stats`): по дням/часам, пики, доли типов доступа.
* **Устройства** (`/admin/gate/devices`): панели и реле — добавление, проверка
  связи, токен/статус SIP, каналы замка, снимок камеры, перезагрузка;
  несколько устройств (основное + дополнительные ворота). В карточке
  устройства — раздел **«Камера шлагбаума и видеопоток»**: включение,
  режим (кадры через сервер / поток через сервер / прямой поток / выкл),
  snapshot-endpoint панели (BAS-IP `security/ipcam`), URL видеопотока
  (MJPEG/HTTP), кэш кадра и ширина. Камера привязана к шлагбауму и
  автоматически появляется в пульте жителя (`/remote`) и панели оператора;
  для прямого режима нужные хосты автоматически разрешаются в CSP.
* **Расписания** (`/admin/gate/schedules`): окна свободного прохода и «тихие
  часы» (например, ночной режим с запретом гостевых открытий).
* **Открыть/закрыть** вручную (с комментарием в журнал).

## Гостевой доступ (`/admin/guest`)

* Все пропуска дома: активные/истёкшие/отозванные, кто выдал, гость, срок,
  использования (сколько раз и когда открыли).
* Создание от имени любого жителя (админом), отзыв, экспорт.
* Настройки лимитов — в Настройках и `config.guest`.

Механика с точки зрения жителя — [07 · Гостевой доступ](07-Guest-Access.md).

## Пользователи (`/admin/users`)

* Учётные записи staff и жителей: роль, привязка к жителю, **телефон**
  (по нему житель входит), статус, 2FA, последний вход; создание/сброс
  пароля/блокировка/удаление. Учётка жителя создаётся одной кнопкой из его
  карточки: логин = цифры телефона, пароль генерируется и показывается один
  раз, при первом входе — обязательная смена.
* **Сессии**: активные сессии (устройство, IP, возраст) — отзыв любой или
  «все, кроме текущей».
* **Журнал входов**: успехи и неудачки с IP/агентом, блокировки.

## Уведомления (`/admin/notifications`)

* **Рассылка**: произвольное сообщение всем активным / выборочным (фильтр по
  корпусу, должникам, наличию e-mail), каналы на выбор, предпросмотр с
  подстановками, тестовая отправка себе.
* **Шаблоны**: редактирование текстов `payment_new` и др. из UI (хранятся в
  БД, переопределяют конфиг), список доступных плейсхолдеров, сброс к дефолту.
* **Очередь**: состояние outbox (pending/sent/failed), ретрай failed,
  статистика батчей, «разобрать сейчас».
* **Объявления**: баннеры в кабинете жителя и на панели (текст, срок, важность).

## Данные (`/admin/data`)

* **Экспорт**: жители (CSV/JSON, с контактами/машинами/оплатами или без),
  оплаты, журнал ворот, гостевые, аудит.
* **Импорт**: загрузка CSV/JSON/Excel → **инспекция** (предпросмотр, маппинг
  колонок, обнаружение дублей по квартире/ФИО) → режим (upsert/insert/
  replace/dry-run) → отчёт по строкам. Отдельный импорт оплат.
* **Бэкапы**: создать сейчас, список (размер, способ, статус), скачать,
  **восстановить** (с предупреждением), удалить; настройка авто-бэкапа.
* Образцы файлов для импорта.

## Настройки (`/admin/settings`)

Группы (хранятся в БД, применяются сразу):

* **Интерфейс**: название ЖК, логотип/фавикон, тема по умолчанию, язык,
  размер страницы, поддержка (телефон/e-mail для писем).
* **Биллинг**: валюта/символ, способ распределения, срок оплаты, префиксы,
  ссылка на оплату, напоминания, пени.
* **Гостевой доступ**: TTL по умолчанию и максимум, пресеты, лимиты,
  обязательные поля, PIN.
* **Уведомления**: каналы и реквизиты (SMTP, Telegram-бот, SMS, webhook —
  секреты шифруются), шаблоны, очередь.
* **Устройство**: параметры панели (можно править из UI: адрес, логин,
  канал, камера).
* **Бэкапы**: расписание, количество, шифрование.
* Скачать текущий `.bas-ip.config.local.php` (для переноса установки).

## Система (`/admin/system`)

* **Состояние**: версия, PHP, БД, драйвер устройства, очередь, диск;
  `/health` для мониторинга.
* **Диагностика (doctor)**: проверки прав, ключей, 2FA, устройства — с
  подсказками и автофиксом части проблем.
* **Журналы**: просмотр каналов (app/audit/gate/device/notify/error/access/
  update) с фильтрами по уровню и тексту, очистка.
* **Обслуживание**: включить/выключить maintenance (шлагбаум продолжает
  работать), запустить cron-задачи вручную, очистка кэша, prune старых
  данных по политике хранения.
* **API-токены** (`/admin/api-tokens`): создание с областями доступа и сроком
  (показывается один раз), список, отзыв.
* **Обновления** (`/admin/updates`): текущая версия, проверка, changelog
  новой версии, установка (с бэкапом), снимки и откат.
* **Аудит** (`/admin/audit`): кто что менял (жители, оплаты, настройки,
  входы, API), фильтр по актёру/действию/датам, экспорт.

## Кабинет оператора

Оператор (консьерж/охрана) работает на `/panel`: большая кнопка открытия,
статус устройства, снимок камеры, поиск жителя по квартире/ФИО/номеру машины
с открытием в один тап, последние события, гостевой код. Всё — только
активные жители с флагом «доступ».

---
Дальше: [06 · Кабинет жителя](06-Resident-Cabinet.md)