🏫 University Visitor Management System

Современная система учета посетителей для образовательных учреждений

🎯 Инновационное решение для управления потоком посетителей с акцентом на безопасность, эффективность и удобство использования

� Содержание

🎯 Обзор проекта
✨ Ключевые особенности
🖼️ Демонстрация
🏗️ Архитектура
🛠️ Технологический стек
⚡ Быстрый старт
🔧 Подробная установка
📱 Использование
🔧 API документация
⚙️ Конфигурация
🔐 Безопасность
📊 Производительность
🧪 Тестирование
🚀 Развертывание
🤝 Участие в разработке
🗺️ Дорожная карта
❓ FAQ
📜 Лицензия

🎯 Обзор проекта

University Visitor Management System — это современное, высокопроизводительное решение для автоматизации процесса учета посетителей в образовательных учреждениях. Система разработана с учетом современных требований к безопасности, производительности и пользовательскому опыту.

🏆 Почему выбрать эту систему?

🎯 Эффективность	� Безопасность	📱 Современность	📊 Аналитика
Автоматизация всех процессов регистрации	Многоуровневая защита данных	PWA и мобильная адаптация	Детальная отчетность
Сокращение времени ожидания до 80%	Шифрование чувствительных данных	Real-time уведомления	Визуализация данных
Интеграция с внешними системами	Контроль доступа по ролям	Offline-first подход	Экспорт отчетов

✨ Ключевые особенности

� Основной функционал

�📝 Умная регистрация ⚡ Быстрая регистрация за 30 секунд 🔍 Автодополнение данных 📊 Валидация в реальном времени 🖼️ Поддержка фото и документов 📱 QR-коды для быстрого доступа	⏱️ Контроль времени 🕐 Автоматическая фиксация входа/выхода ⏰ Уведомления о превышении времени 📅 Планирование визитов 🔔 Напоминания о встречах � Аналитика времени пребывания
🔐 Безопасность 🔒 Многофакторная аутентификация 🛡️ Шифрование данных AES-256 👤 Ролевая модель доступа 📋 Аудит всех действий 🚫 Blacklist нежелательных лиц	📊 Аналитика и отчеты � Интерактивные дашборды 📋 Настраиваемые отчеты 📤 Экспорт в Excel/PDF 📊 Визуализация данных 📧 Автоматическая рассылка отчетов

🎯 Специальные возможности

Функция	Описание	Преимущества
🌐 PWA Support	Progressive Web App	Работа без интернета, push-уведомления
🔄 Real-time Sync	Синхронизация в реальном времени	Актуальные данные на всех устройствах
🎨 Кастомизация	Настройка интерфейса	Адаптация под корпоративный стиль
🌍 Мультиязычность	Поддержка нескольких языков	Удобство для международных учреждений
📱 Мобильный API	RESTful API	Интеграция с мобильными приложениями
🔗 Интеграции	Связь с внешними системами	Синхронизация с 1C, AD, CRM

�️ Демонстрация

📱 Интерфейс системы

┌─────────────────────────────────────────────────────────────┐
│                    🏫 Панель управления                     │
├─────────────────────────────────────────────────────────────┤
│  📊 Сегодня: 127 посетителей    ⏱️ Средн. время: 45 мин     │
│  🔴 Активных: 23                🟢 Завершенных: 104         │
├─────────────────────────────────────────────────────────────┤
│  [➕ Новый посетитель]  [🔍 Поиск]  [📊 Отчеты]           │
└─────────────────────────────────────────────────────────────┘

🏗️ Архитектура

🏛️ Архитектурная схема

graph TB
    A[👤 Пользователи] --> B[🌐 Nginx Load Balancer]
    B --> C[🖥️ Django Application]
    C --> D[🗄️ PostgreSQL Database]
    C --> E[⚡ Redis Cache]
    C --> F[📨 Celery Workers]
    F --> G[📧 Email Service]
    F --> H[📊 Report Generator]
    C --> I[🔌 WebSocket Handler]
    I --> J[📱 Real-time Updates]

🔧 Компоненты системы

Компонент	Технология	Назначение
Frontend	HTML5, CSS3, JavaScript, Bootstrap	Пользовательский интерфейс
Backend	Django 5.2, Python 3.13+	Бизнес-логика и API
Database	PostgreSQL 15+	Хранение данных
Cache	Redis 7+	Кэширование и сессии
Queue	Celery + Redis	Асинхронные задачи
Web Server	Nginx	Обратный прокси и статика
Container	Docker + Docker Compose	Контейнеризация

🛠️ Технологический стек

🐍 Backend Technologies

Технология	Версия	Назначение
Python	3.13+	Основной язык разработки
Django	5.2	Web-фреймворк
Django REST Framework	3.15+	API разработка
Celery	5.3+	Асинхронные задачи
django-allauth	0.57+	Аутентификация и авторизация
django-select2	8.1+	Улучшенные формы
django-extensions	3.2+	Дополнительные возможности
django-filters	23.5+	Фильтрация данных

🎨 Frontend Technologies

Технология	Версия	Назначение
HTML5	-	Семантическая разметка
CSS3	-	Стилизация интерфейса
JavaScript	ES6+	Клиентская логика
Bootstrap	5.3+	CSS фреймворк
Tabler	1.0+	UI компоненты
jQuery	3.7+	DOM манипуляции
HTMX	1.9+	Интерактивность без JS

🗄️ Database & Storage

Технология	Версия	Назначение
PostgreSQL	15+	Основная база данных
Redis	7+	Кэширование и очереди
MinIO/S3	-	Хранение файлов

🛠️ DevOps & Infrastructure

Технология	Назначение
Docker	Контейнеризация
Docker Compose	Оркестрация контейнеров
Nginx	Веб-сервер и прокси
Gunicorn	WSGI сервер
Poetry	Управление зависимостями
GitHub Actions	CI/CD пайплайн
Prometheus	Мониторинг метрик
Grafana	Визуализация метрик

⚡ Быстрый старт

🚀 Docker - Запуск за 5 минут

# Клонирование репозитория
git clone https://github.com/m3rshALL/university_visitor_system.git
cd university_visitor_system

# Настройка переменных окружения
cp .env.example .env

# Запуск всех сервисов
docker-compose up -d

# Создание суперпользователя
docker-compose exec web python manage.py createsuperuser

# Готово! 🎉 Откройте http://localhost:8000

⚡ Poetry - Локальная разработка

# Установка зависимостей
poetry install

# Активация виртуального окружения
poetry shell

# Миграции и запуск
python manage.py migrate
python manage.py runserver

📋 Системные требования

Компонент	Минимальные требования	Рекомендуемые
RAM	2 GB	4+ GB
CPU	2 cores	4+ cores
HDD	10 GB	50+ GB SSD
Python	3.11+	3.13+
PostgreSQL	13+	15+

🔧 Подробная установка

🐳 Установка через Docker (Рекомендуется)

Предварительные требования

Docker 20.10+
Docker Compose 2.0+
Git

Пошаговая инструкция

Подготовка проекта

# Клонирование репозитория
git clone https://github.com/m3rshALL/university_visitor_system.git
cd university_visitor_system

# Создание файла переменных окружения
cp .env.example .env

Настройка переменных окружения

Отредактируйте файл .env:

# Основные настройки
DJANGO_SECRET_KEY=your-super-secret-key-here
DJANGO_DEBUG=False
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1,your-domain.com

# База данных
POSTGRES_DB=visitor_system
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your-strong-password
POSTGRES_HOST=db
POSTGRES_PORT=5432

# Redis
REDIS_URL=redis://redis:6379/0

# Email (опционально)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password

Запуск сервисов

# Запуск всех контейнеров в фоновом режиме
docker-compose up -d

# Проверка статуса контейнеров
docker-compose ps

Инициализация базы данных

# Применение миграций
docker-compose exec web python manage.py migrate

# Создание суперпользователя
docker-compose exec web python manage.py createsuperuser

# Загрузка тестовых данных (опционально)
docker-compose exec web python manage.py loaddata fixtures/initial_data.json

Проверка установки

Откройте браузер и перейдите по адресу:
- Основное приложение: http://localhost:8000
- Админ-панель: http://localhost:8000/admin
- API документация: http://localhost:8000/api/docs

💻 Локальная установка с Poetry

Предварительные требования

Python 3.11+
PostgreSQL 13+
Redis 6+
Poetry

Пошаговая инструкция

Подготовка окружения

# Клонирование репозитория
git clone https://github.com/m3rshALL/university_visitor_system.git
cd university_visitor_system

# Установка зависимостей
poetry install

# Активация виртуального окружения
poetry shell

Настройка базы данных

-- Подключение к PostgreSQL
psql -U postgres

-- Создание базы данных
CREATE DATABASE visitor_system;
CREATE USER visitor_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE visitor_system TO visitor_user;

Конфигурация приложения

# Создание .env файла
cp .env.example .env

# Редактирование настроек
nano .env

Настройте переменные:

DJANGO_SECRET_KEY=your-secret-key
DATABASE_URL=postgresql://visitor_user:your_password@localhost:5432/visitor_system
REDIS_URL=redis://localhost:6379/0

Инициализация приложения

# Переход в папку проекта Django
cd visitor_system

# Применение миграций
python manage.py migrate

# Сбор статических файлов
python manage.py collectstatic --noinput

# Создание суперпользователя
python manage.py createsuperuser

Запуск сервисов

# Запуск Django сервера
python manage.py runserver

# В отдельном терминале - запуск Celery worker
celery -A visitor_system worker -l info

# В третьем терминале - запуск Celery beat (планировщик)
celery -A visitor_system beat -l info

🔧 Настройка дополнительных сервисов

Мониторинг с Prometheus и Grafana

# Запуск мониторинга
docker-compose -f docker-compose.monitoring.yml up -d

# Доступ к сервисам:
# Prometheus: http://localhost:9090
# Grafana: http://localhost:3000 (admin/admin)

Настройка SSL сертификатов

# Генерация самоподписанного сертификата
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365

# Или использование Let's Encrypt с certbot
certbot --nginx -d your-domain.com

� Использование

👨‍💼 Для администраторов

🚀 Первый запуск системы

Вход в админ-панель
- Перейдите по адресу: http://your-domain.com/admin
- Войдите под учетной записью суперпользователя

Настройка организационной структуры

# Создание отделов через Django shell
python manage.py shell
>>> from departments.models import Department
>>> Department.objects.create(name="IT отдел", code="IT")
>>> Department.objects.create(name="Приемная комиссия", code="ADMISSIONS")

Создание пользователей
- Добавьте сотрудников через админ-панель
- Назначьте соответствующие роли и права доступа

📊 Ежедневная работа

🖱️ Просмотр статистики

Главная панель управления
- Общее количество посетителей за день/неделю/месяц
- Активные визиты в реальном времени
- Самые посещаемые отделы
Детальная аналитика
- Время пиковой нагрузки
- Средняя продолжительность визитов
- Самые частые цели посещения

👩‍💼 Для сотрудников reception

📝 Регистрация нового посетителя

Стандартная регистрация

Шаг 1: Нажмите "Новый посетитель"
Шаг 2: Заполните обязательные поля:
        - ФИО посетителя
        - Цель визита
        - К кому направляется
        - Контактные данные
Шаг 3: Нажмите "Зарегистрировать"
Шаг 4: Система автоматически отправит уведомление принимающей стороне

Экспресс-регистрация по QR-коду

📱 Отсканируйте QR-код → Автозаполнение → Подтверждение

🔍 Управление активными визитами

Поиск посетителя: Используйте глобальный поиск по ФИО или номеру документа
Завершение визита: Нажмите "Завершить визит" при выходе гостя
Продление визита: При необходимости можно продлить время пребывания

🎓 Для студентов и абитуриентов

📋 Самостоятельная регистрация

Веб-интерфейс
- Откройте http://your-domain.com/register
- Заполните форму самостоятельной регистрации
- Укажите цель визита (консультация, подача документов, экзамен)
Мобильное приложение (PWA)
- Установите веб-приложение на смартфон
- Используйте для быстрой регистрации и получения уведомлений

🔧 API документация

🌐 REST API

Система предоставляет полнофункциональный REST API для интеграции с внешними системами.

� Аутентификация

# Получение токена аутентификации
curl -X POST http://your-domain.com/api/auth/token/ \
     -H "Content-Type: application/json" \
     -d '{"username": "your_username", "password": "your_password"}'

# Использование токена в запросах
curl -H "Authorization: Bearer YOUR_TOKEN" \
     http://your-domain.com/api/v1/visits/

📋 Основные эндпоинты

Метод	Эндпоинт	Описание
`GET`	`/api/v1/visits/`	Список всех визитов
`POST`	`/api/v1/visits/`	Создание нового визита
`GET`	`/api/v1/visits/{id}/`	Детали конкретного визита
`PUT`	`/api/v1/visits/{id}/`	Обновление визита
`DELETE`	`/api/v1/visits/{id}/`	Удаление визита
`GET`	`/api/v1/visitors/`	Список посетителей
`GET`	`/api/v1/departments/`	Список отделов

📝 Примеры запросов

📤 Создание нового визита

curl -X POST http://your-domain.com/api/v1/visits/ \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "visitor_name": "Иванов Иван Иванович",
       "visitor_iin": "123456789012",
       "visitor_phone": "+7 777 123 45 67",
       "purpose": "Консультация по поступлению",
       "department": 1,
       "host_name": "Петров Петр Петрович",
       "expected_duration": 60
     }'

📥 Получение статистики

# Статистика за сегодня
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "http://your-domain.com/api/v1/statistics/today/"

# Статистика за период
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "http://your-domain.com/api/v1/statistics/period/?start=2024-01-01&end=2024-01-31"

📖 Интерактивная документация

Swagger UI: http://your-domain.com/api/docs/
ReDoc: http://your-domain.com/api/redoc/
OpenAPI Schema: http://your-domain.com/api/schema/

⚙️ Конфигурация

🔧 Переменные окружения

📋 Полный список переменных

Основные настройки Django

# Секретный ключ (обязательно)
DJANGO_SECRET_KEY=your-super-secret-key-here

# Режим отладки (только для разработки)
DJANGO_DEBUG=False

# Разрешенные хосты
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1,your-domain.com

# Настройка модуля настроек
DJANGO_SETTINGS_MODULE=visitor_system.conf.prod

База данных

# PostgreSQL (рекомендуется)
DATABASE_URL=postgresql://username:password@localhost:5432/database_name

# Или отдельные параметры
POSTGRES_DB=visitor_system
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password
POSTGRES_HOST=localhost
POSTGRES_PORT=5432

Кэширование и очереди

# Redis
REDIS_URL=redis://localhost:6379/0
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/0

Email настройки

# SMTP настройки
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password
EMAIL_USE_TLS=True
DEFAULT_FROM_EMAIL=noreply@your-domain.com

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

# Шифрование чувствительных данных
IIN_ENCRYPTION_KEY=your-base64-encoded-key

# OAuth настройки (Microsoft)
MICROSOFT_CLIENT_ID=your-client-id
MICROSOFT_CLIENT_SECRET=your-client-secret
MS_TENANT_ID=your-tenant-id

🎨 Кастомизация интерфейса

Изменение темы и логотипа

# visitor_system/conf/custom.py
CUSTOM_SETTINGS = {
    'SITE_TITLE': 'Ваш Университет - Система учета посетителей',
    'SITE_LOGO': '/static/images/your-logo.png',
    'PRIMARY_COLOR': '#1f2937',
    'SECONDARY_COLOR': '#3b82f6',
}

Настройка уведомлений

# Шаблоны email уведомлений
EMAIL_TEMPLATES = {
    'visitor_arrival': 'notifications/visitor_arrival.html',
    'visit_reminder': 'notifications/visit_reminder.html',
    'daily_summary': 'notifications/daily_summary.html',
}

📊 Настройка мониторинга

Prometheus метрики

# prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'visitor-system'
    static_configs:
      - targets: ['localhost:8000']
    metrics_path: '/metrics'

Grafana дашборды

Импортируйте готовые дашборды из папки grafana/dashboards/:

django-overview.json - Общая статистика Django
visitor-analytics.json - Аналитика посетителей
system-performance.json - Производительность системы

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

🛡️ Встроенные механизмы защиты

🔒 Шифрование данных

# Чувствительные данные (ИИН) шифруются с помощью Fernet
from cryptography.fernet import Fernet

# Генерация ключа шифрования
key = Fernet.generate_key()
# Сохраните этот ключ в переменной окружения IIN_ENCRYPTION_KEY

👤 Система ролей и доступа

Роль	Описание	Права доступа
SuperAdmin	Системный администратор	Полный доступ ко всем функциям
Reception	Сотрудник приемной	Регистрация/управление всеми посетителями
Department	Сотрудник отдела	Просмотр посетителей своего отдела
Security	Служба безопасности	Просмотр и контроль всех визитов
Guest	Временный доступ	Самостоятельная регистрация

🚫 Защита от атак

Rate Limiting: Ограничение частоты запросов
CSRF Protection: Защита от межсайтовой подделки запросов
XSS Protection: Фильтрация вредоносных скриптов
SQL Injection: Использование ORM Django предотвращает SQL-инъекции
Brute Force: Блокировка IP после неудачных попыток входа

🔍 Аудит и логирование

📝 Журнал аудита

# Все действия пользователей записываются в AuditLog
class AuditLog(models.Model):
    user = models.ForeignKey(User, on_delete=models.CASCADE)
    action = models.CharField(max_length=50)  # CREATE, UPDATE, DELETE, VIEW
    model_name = models.CharField(max_length=50)
    object_id = models.PositiveIntegerField()
    timestamp = models.DateTimeField(auto_now_add=True)
    ip_address = models.GenericIPAddressField()
    user_agent = models.TextField()

📊 Мониторинг безопасности

Уведомления о подозрительной активности
Еженедельные отчеты по безопасности
Автоматическое резервное копирование данных
Мониторинг целостности файлов

🔧 Рекомендации по безопасности

✅ Чеклист безопасности для продакшена

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

⚡ Оптимизации

🗄️ Оптимизация базы данных

-- Индексы для ускорения поиска
CREATE INDEX idx_visitor_iin_hash ON visitors_guest(visitor_iin_hash);
CREATE INDEX idx_visit_entry_time ON visitors_visit(entry_time);
CREATE INDEX idx_visit_department ON visitors_visit(department_id);

-- Партиционирование таблицы аудита по датам
CREATE TABLE audit_log_2024 PARTITION OF visitors_auditlog
FOR VALUES FROM ('2024-01-01') TO ('2025-01-01');

💾 Кэширование

# Настройки кэширования в settings.py
CACHES = {
    'default': {
        'BACKEND': 'django_redis.cache.RedisCache',
        'LOCATION': 'redis://localhost:6379/1',
        'OPTIONS': {
            'CLIENT_CLASS': 'django_redis.client.DefaultClient',
            'COMPRESSOR': 'django_redis.compressors.zlib.ZlibCompressor',
        },
        'KEY_PREFIX': 'visitor_system',
        'TIMEOUT': 300,
    }
}

🔄 Асинхронные задачи

# Примеры Celery задач
@shared_task
def send_visitor_notification(visit_id):
    """Отправка уведомления о прибытии посетителя"""
    # Асинхронная отправка email
    
@shared_task
def generate_daily_report():
    """Генерация ежедневного отчета"""
    # Обработка больших объемов данных в фоне
    
@shared_task
def cleanup_old_records():
    """Очистка устаревших записей"""
    # Удаление старых данных для экономии места

📈 Метрики производительности

🎯 Ключевые показатели

Метрика	Текущее значение	Целевое значение
Время отклика	<200ms	<100ms
Пропускная способность	1000 req/min	2000 req/min
Использование CPU	<30%	<50%
Использование RAM	<2GB	<4GB
Доступность	99.9%	99.99%

📊 Мониторинг в реальном времени

# Кастомные метрики Prometheus
from prometheus_client import Counter, Histogram, Gauge

# Счетчики
visitor_registrations = Counter('visitor_registrations_total', 'Total visitor registrations')
api_requests = Counter('api_requests_total', 'Total API requests', ['method', 'endpoint'])

# Гистограммы
request_duration = Histogram('request_duration_seconds', 'Request duration')
database_query_duration = Histogram('db_query_duration_seconds', 'Database query duration')

# Показатели
active_visitors = Gauge('active_visitors_current', 'Current number of active visitors')

🚀 Рекомендации по масштабированию

📈 Стратегии масштабирования

Горизонтальное масштабирование

# docker-compose.scale.yml
version: '3.8'
services:
  web:
    deploy:
      replicas: 3
  worker:
    deploy:
      replicas: 2
  
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - web

Вертикальное масштабирование

# Увеличение ресурсов контейнера
docker-compose up --scale web=3 --scale worker=2

Оптимизация для больших нагрузок

Использование CDN для статических файлов
Настройка кэширования на уровне веб-сервера
Репликация базы данных (master-slave)
Использование брокера сообщений (RabbitMQ вместо Redis)

🧪 Тестирование

Для запуска тестов используйте следующие команды:

# Запуск всех тестов
python manage.py test

# Запуск тестов для конкретного приложения
python manage.py test visitors

# Запуск тестов с покрытием кода
coverage run --source='.' manage.py test
coverage report

🤝 Участие в разработке

Мы приветствуем любой вклад в развитие проекта! Если вы хотите принять участие:

🍴 Сделайте форк репозитория
🌱 Создайте ветку для вашей фичи/исправления:
```
git checkout -b feature/имя-функции
```
📝 Внесите изменения и закоммитьте их:
```
git commit -m 'Добавлена новая функция X'
```
📤 Отправьте изменения в ваш форк:
```
git push origin feature/имя-функции
```
🔍 Создайте Pull Request в основной репозиторий

🧪 Тестирование

🎯 Стратегия тестирования

Проект использует многоуровневую стратегию тестирования для обеспечения высокого качества кода:

🔬 Типы тестов

Тип тестов	Покрытие	Описание
Unit Tests	~85%	Тестирование отдельных функций и методов
Integration Tests	~70%	Тестирование взаимодействия компонентов
Functional Tests	~60%	Тестирование пользовательских сценариев
API Tests	~90%	Тестирование REST API эндпоинтов

🚀 Запуск тестов

Базовые команды

# Запуск всех тестов
python manage.py test

# Запуск тестов для конкретного приложения
python manage.py test visitors

# Запуск с подробным выводом
python manage.py test --verbosity=2

# Запуск конкретного тестового класса
python manage.py test visitors.tests.TestVisitorModel

# Запуск конкретного теста
python manage.py test visitors.tests.TestVisitorModel.test_visitor_creation

Тесты с покрытием

# Установка coverage
pip install coverage

# Запуск тестов с измерением покрытия
coverage run --source='.' manage.py test

# Генерация отчета в терминале
coverage report

# Генерация HTML отчета
coverage html
# Откройте htmlcov/index.html в браузере

Параллельное тестирование

# Запуск тестов в несколько потоков (для ускорения)
python manage.py test --parallel 4

# Для Docker
docker-compose exec web python manage.py test --parallel auto

🔧 Настройка тестовой среды

Конфигурация тестовой БД

# visitor_system/conf/test.py
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'test_visitor_system',
        'USER': 'test_user',
        'PASSWORD': 'test_password',
        'HOST': 'localhost',
        'PORT': '5432',
        'TEST': {
            'NAME': 'test_visitor_system_test',
        }
    }
}

# Отключение миграций для ускорения тестов
class DisableMigrations:
    def __contains__(self, item):
        return True
    def __getitem__(self, item):
        return None

MIGRATION_MODULES = DisableMigrations()

Фикстуры для тестов

# visitors/tests/fixtures.py
import pytest
from django.contrib.auth.models import User
from visitors.models import Guest, Visit

@pytest.fixture
def test_user():
    return User.objects.create_user(
        username='testuser',
        email='test@example.com',
        password='testpass123'
    )

@pytest.fixture
def test_guest():
    return Guest.objects.create(
        full_name='Тестовый Посетитель',
        visitor_iin_hash='test_hash',
        phone_number='+77771234567'
    )

🚀 Развертывание

🌐 Production развертывание

🐳 Docker Swarm

# docker-compose.prod.yml
version: '3.8'

services:
  web:
    image: visitor-system:latest
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
      restart_policy:
        condition: on-failure
    environment:
      - DJANGO_SETTINGS_MODULE=visitor_system.conf.prod
    depends_on:
      - db
      - redis

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/prod.conf:/etc/nginx/nginx.conf
      - ./ssl:/etc/nginx/ssl
    depends_on:
      - web

  db:
    image: postgres:15-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data/
    environment:
      POSTGRES_DB: visitor_system_prod
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

volumes:
  postgres_data:

📊 Мониторинг в продакшене

Настройка Sentry

# visitor_system/conf/prod.py
import sentry_sdk
from sentry_sdk.integrations.django import DjangoIntegration
from sentry_sdk.integrations.celery import CeleryIntegration

sentry_sdk.init(
    dsn="YOUR_SENTRY_DSN",
    integrations=[
        DjangoIntegration(),
        CeleryIntegration(),
    ],
    traces_sample_rate=0.1,
    send_default_pii=True
)

Логирование

# Настройка логирования
LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'verbose': {
            'format': '{levelname} {asctime} {module} {process:d} {thread:d} {message}',
            'style': '{',
        },
    },
    'handlers': {
        'file': {
            'level': 'INFO',
            'class': 'logging.FileHandler',
            'filename': '/var/log/visitor_system/django.log',
            'formatter': 'verbose',
        },
        'console': {
            'level': 'DEBUG',
            'class': 'logging.StreamHandler',
            'formatter': 'verbose',
        },
    },
    'root': {
        'handlers': ['console', 'file'],
        'level': 'INFO',
    },
}

🤝 Участие в разработке

🌟 Как внести вклад

Мы приветствуем любой вклад в развитие проекта! Есть множество способов помочь:

🐛 Сообщение об ошибках

Проверьте, что ошибка не была уже зарегистрирована в Issues
Создайте новый issue с подробным описанием:
- Версия системы
- Шаги для воспроизведения
- Ожидаемое поведение
- Фактическое поведение
- Скриншоты (если применимо)

💡 Предложение новых функций

Откройте Discussion для обсуждения идеи
Опишите проблему, которую решает ваша идея
Предложите возможные варианты реализации
Дождитесь обратной связи от сообщества

🔧 Разработка

Настройка среды разработки

# Форк репозитория и клонирование
git clone https://github.com/YOUR_USERNAME/university_visitor_system.git
cd university_visitor_system

# Создание ветки для разработки
git checkout -b feature/your-feature-name

# Установка в режиме разработки
poetry install --with dev,test

# Установка pre-commit хуков
pre-commit install

Стандарты кодирования

# Линтинг и форматирование
black .                    # Форматирование кода
isort .                    # Сортировка импортов
flake8 .                   # Проверка стиля кода
mypy .                     # Проверка типов
bandit -r .               # Проверка безопасности

Гит воркфлоу

# Создание коммита
git add .
git commit -m "feat: add visitor notification system"

# Push изменений
git push origin feature/your-feature-name

# Создание Pull Request через GitHub UI

🗺️ Дорожная карта

🎯 Версия 2.0 (Q2 2024)

🚀 Новые функции

🤖 AI-интеграция
- Автоматическое определение типа посетителя
- Предиктивная аналитика посещений
- Chatbot для быстрой регистрации
📱 Мобильное приложение
- Нативное Android/iOS приложение
🔗 Расширенные интеграции
- Интеграция с Microsoft Teams
- Синхронизация с календарем Outlook
- API для 1С:Предприятие

🔧 Улучшения

⚡ Производительность
- Оптимизация базы данных
- Кэширование на уровне приложения
- Асинхронные операции
🎨 UI/UX
- Полное обновление дизайна
- Темная тема
- Accessibility улучшения

🔮 Версия 3.0 (Q4 2024)

🌐 Микросервисная архитектура

Разделение на микросервисы
Event-driven архитектура
GraphQL API

🔐 Расширенная безопасность

Биометрическая аутентификация
Blockchain-логирование
Zero-trust архитектура

📊 Продвинутая аналитика

Machine Learning модели
Предиктивная аналитика
Интеграция с BI системами

🎪 Долгосрочные планы

🌍 Интернационализация

Поддержка 10+ языков
Локализация для разных стран
Культурная адаптация

🏢 Enterprise функции

Мультитенантность
Advanced RBAC
Корпоративные интеграции

❓ FAQ

🔧 Технические вопросы

❓ Какие версии Python поддерживаются?

Система поддерживает Python 3.11 и выше. Рекомендуется использовать Python 3.13 для получения всех новых возможностей и улучшений производительности.

❓ Можно ли использовать MySQL вместо PostgreSQL?

Хотя Django поддерживает MySQL, мы рекомендуем PostgreSQL из-за:

Лучшей поддержки JSON полей
Более продвинутых возможностей полнотекстового поиска
Лучшей производительности для сложных запросов

Если необходимо использовать MySQL, измените настройки DATABASES в файле конфигурации.

❓ Как настроить HTTPS в production?

Получите SSL сертификат (Let's Encrypt или коммерческий)
Настройте Nginx для HTTPS

Обновите настройки Django:

SECURE_SSL_REDIRECT = True
SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')

🏢 Функциональные вопросы

❓ Можно ли кастомизировать поля регистрации?

Да! Система позволяет настраивать поля через админ-панель:

Перейдите в админ-панель → Настройки → Поля регистрации
Добавьте/удалите/измените поля
Настройте валидацию и обязательность полей

❓ Поддерживается ли групповая регистрация?

Да, система поддерживает групповую регистрацию для экскурсий, конференций и других мероприятий:

Создание группового приглашения
QR-код для всей группы
Массовая регистрация участников

❓ Как работает система уведомлений?

Система поддерживает несколько каналов уведомлений:

📧 Email уведомления
📱 Push-уведомления (PWA)
🔔 In-app уведомления

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

❓ Как обеспечивается защита персональных данных?

Система реализует множество мер защиты:

Шифрование чувствительных данных (AES-256)
Хеширование ИИН для поиска
Аудит всех действий
Автоматическое удаление старых данных
Соответствие требованиям GDPR

❓ Можно ли настроить retention policy для данных?

Да, система позволяет настроить:

Автоматическое удаление записей старше N дней
Архивирование данных
Очистку логов аудита
Backup старых данных

📊 Отчеты и аналитика

❓ Какие форматы экспорта поддерживаются?

Поддерживаемые форматы:

📊 Excel (XLSX)
📄 PDF
📋 CSV
📊 JSON для API интеграций

❓ Можно ли создавать кастомные отчеты?

Да, система предоставляет:

Конструктор отчетов через веб-интерфейс
API для создания отчетов программно
Шаблоны отчетов для типовых задач
Планировщик автоматической генерации отчетов

📜 Лицензия

📄 MIT License

MIT License

Copyright (c) 2024 Sagat Akimbay

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

🏛️ Соответствие законодательству

Система разработана с учетом требований:

🇰🇿 Казахстан: Закон "О персональных данных"

Создано с ❤️ для образовательных учреждений по всему миру

Name		Name	Last commit message	Last commit date
Latest commit History 189 Commits
.github/workflows		.github/workflows
grafana		grafana
templates		templates
visitor_system		visitor_system
.dockerignore		.dockerignore
.env.example		.env.example
.flake8		.flake8
.gitignore		.gitignore
AUTO_CHECKIN_CHECKOUT_FEATURE.md		AUTO_CHECKIN_CHECKOUT_FEATURE.md
CELERY_HIKVISION_FIX.md		CELERY_HIKVISION_FIX.md
DEPLOYMENT_VERIFICATION.md		DEPLOYMENT_VERIFICATION.md
Dockerfile		Dockerfile
FINAL_ANSWER_AUTOMATION.md		FINAL_ANSWER_AUTOMATION.md
FINAL_INTEGRATION_REPORT.md		FINAL_INTEGRATION_REPORT.md
HIKVISION_BUGS_FIXED.md		HIKVISION_BUGS_FIXED.md
HIKVISION_GAPS_ANALYSIS.md		HIKVISION_GAPS_ANALYSIS.md
HIKVISION_WORKER_GUIDE.md		HIKVISION_WORKER_GUIDE.md
HIKVISION_WORKER_SETUP.md		HIKVISION_WORKER_SETUP.md
LICENSE		LICENSE
OPTIMIZATION_README.md		OPTIMIZATION_README.md
PHASE2_PHASE3_IMPLEMENTATION_REPORT.md		PHASE2_PHASE3_IMPLEMENTATION_REPORT.md
PHOTO_UPLOAD_SOLUTION.md		PHOTO_UPLOAD_SOLUTION.md
QUICK_FIXES_CHECKLIST.md		QUICK_FIXES_CHECKLIST.md
QUICK_START.md		QUICK_START.md
QUICK_START_HIKVISION.md		QUICK_START_HIKVISION.md
README.md		README.md
SYSTEM_GAPS_AND_ROADMAP.md		SYSTEM_GAPS_AND_ROADMAP.md
WEBPUSH_README.md		WEBPUSH_README.md
alert_rules.yml		alert_rules.yml
alertmanager.yml		alertmanager.yml
check_guest_status.ps1		check_guest_status.ps1
check_services_status.bat		check_services_status.bat
check_status.bat		check_status.bat
docker-compose.monitoring.yml		docker-compose.monitoring.yml
docker-compose.yml		docker-compose.yml
entrypoint.sh		entrypoint.sh
generate_vapid_keys.py		generate_vapid_keys.py
poetry.lock		poetry.lock
prometheus.yml		prometheus.yml
pyproject.toml		pyproject.toml
setup_hikvision_env.py		setup_hikvision_env.py
start_celery.bat		start_celery.bat
start_celery_hikvision_worker.bat		start_celery_hikvision_worker.bat
start_full_stack.bat		start_full_stack.bat
start_hikvision_worker.bat		start_hikvision_worker.bat
start_postgres_docker.bat		start_postgres_docker.bat
start_redis_docker.bat		start_redis_docker.bat
start_with_ngrok.bat		start_with_ngrok.bat
stop_all.bat		stop_all.bat
stop_all_services.bat		stop_all_services.bat

License

m3rshALL/university_visitor_system

Folders and files

Latest commit

History

Repository files navigation

🏫 University Visitor Management System

Современная система учета посетителей для образовательных учреждений

🎯 Инновационное решение для управления потоком посетителей с акцентом на безопасность, эффективность и удобство использования

� Содержание

🎯 Обзор проекта

🏆 Почему выбрать эту систему?

✨ Ключевые особенности

� Основной функционал

�📝 Умная регистрация

⏱️ Контроль времени

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

📊 Аналитика и отчеты

🎯 Специальные возможности

�️ Демонстрация

📱 Интерфейс системы

🏗️ Архитектура

🏛️ Архитектурная схема

🔧 Компоненты системы

🛠️ Технологический стек

🐍 Backend Technologies

🎨 Frontend Technologies

🗄️ Database & Storage

🛠️ DevOps & Infrastructure

⚡ Быстрый старт

🚀 Docker - Запуск за 5 минут

⚡ Poetry - Локальная разработка

📋 Системные требования

🔧 Подробная установка

🐳 Установка через Docker (Рекомендуется)

Предварительные требования

Пошаговая инструкция

💻 Локальная установка с Poetry

Предварительные требования

Пошаговая инструкция

🔧 Настройка дополнительных сервисов

Мониторинг с Prometheus и Grafana

Настройка SSL сертификатов

� Использование

👨‍💼 Для администраторов

🚀 Первый запуск системы

📊 Ежедневная работа

👩‍💼 Для сотрудников reception

📝 Регистрация нового посетителя

🔍 Управление активными визитами

🎓 Для студентов и абитуриентов

📋 Самостоятельная регистрация

🔧 API документация

🌐 REST API

� Аутентификация

📋 Основные эндпоинты

📝 Примеры запросов

📖 Интерактивная документация

⚙️ Конфигурация

🔧 Переменные окружения

Основные настройки Django

База данных

Кэширование и очереди

Email настройки

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

🎨 Кастомизация интерфейса

Изменение темы и логотипа

Настройка уведомлений

📊 Настройка мониторинга

Prometheus метрики

Grafana дашборды

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

🛡️ Встроенные механизмы защиты

🔒 Шифрование данных

👤 Система ролей и доступа

🚫 Защита от атак

🔍 Аудит и логирование

📝 Журнал аудита

📊 Мониторинг безопасности

🔧 Рекомендации по безопасности