Система NFC ключей (Hikvision и интеграции)¶

Обзор¶

Данный документ описывает функционал бесконтактного доступа в номера отелей с использованием технологии NFC в мобильном приложении Архыз.CLUB. Система позволяет гостям использовать смартфон в качестве ключа от номера, заменяя физические карты доступа.

Основная интеграция реализована для оборудования Hikvision, с возможностью расширения для других производителей СКУД (Систем Контроля и Управления Доступом).

Архитектура решения¶

1. Мобильное приложение (Frontend)¶

Технологии: React + Capacitor (для доступа к NFC модулю смартфона).
Функции:
Безопасное хранение цифрового ключа (Token/Credential).
Эмуляция карты доступа (HCE - Host Card Emulation) или передача команды на открытие.
Отображение статуса доступа и номера комнаты.

2. Серверная часть (Backend)¶

Технологии: FastAPI, Supabase.
Функции:
Управление жизненным циклом ключей (выдача, продление, отзыв).
Интеграция с API производителей замков (Hikvision ISAPI / HikCentral).
Логирование событий доступа.

3. Оборудование (Hardware)¶

Hikvision: Контроллеры доступа (серии DS-K26xx, DS-K28xx) и считыватели с поддержкой NFC/Mifare.
Умные замки: Автономные замки с поддержкой Bluetooth/NFC (интеграция через шлюзы).

Сценарий использования (User Flow)¶

Бронирование и Заселение:
Гость оформляет бронирование.
Администратор (или автоматическая система) выполняет Check-in.
Система генерирует цифровой ключ для указанного номера на период проживания.
Получение ключа:
Гость видит в приложении активную бронь.
Нажимает "Получить ключ" или ключ загружается автоматически.
Ключ сохраняется в защищенное хранилище приложения.
Открытие двери:
Гость подходит к двери номера.
Разблокирует телефон и подносит его к считывателю замка.
Происходит обмен данными через NFC.
Дверь открывается.
Выселение:
По истечении времени бронирования ключ автоматически деактивируется.
При досрочном выселении ключ отзывается сервером.

Интеграция с Hikvision¶

Для работы с оборудованием Hikvision используется протокол ISAPI или интеграция через ПО HikCentral.

Требования к оборудованию¶

Контроллер доступа Hikvision с поддержкой сетевого интерфейса.
Считыватели карт (Mifare/NFC).
Корректно настроенное время (NTP) на устройствах.

Процесс настройки в Админ-панели¶

Добавление устройства:
Перейдите в раздел "Устройства доступа".
Добавьте новый контроллер (IP, Port, Login, Password).
Маппинг дверей:
Свяжите ID двери из контроллера с конкретным номером (Room) в системе отеля.
Настройка прав:
Укажите группы доступа по умолчанию для гостей.

API Эндпоинты (Планируемые)¶

POST /api/v1/keys/issue - Выдача ключа для бронирования.
POST /api/v1/keys/revoke - Отзыв ключа.
GET /api/v1/keys/my - Получение активных ключей пользователя.
POST /api/v1/integrations/hikvision/sync - Синхронизация пользователей с контроллером.

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

Шифрование: Все данные ключей передаются по защищенному каналу (HTTPS).
Валидация: Ключ привязан к устройству и конкретному пользователю.
Аудит: Все попытки открытия (успешные и неуспешные) логируются.

Поддержка других систем¶

Архитектура позволяет подключать адаптеры для других систем: - Perco - Sigur - IronLogic - TTLock (через Cloud API)

Для добавления новой системы необходимо реализовать интерфейс AccessControlProvider в backend-части.