Система управления пропусками автотранспорта

Веб-система управления автомобильными пропусками с ролями, гибкими правами, генерацией PDF и мобильным приложением для охранников.

Быстрая установка (одна команда)

curl -fsSL https://git.kinoteka.space/KirsanovAdmin/Car-transport-pass-system/raw/branch/main/install.sh | bash

Скрипт автоматически:

• Установит Docker и Docker Compose (если не установлены)
• Запросит пароль БД, адрес сервера и SECRET_KEY
• Загрузит образ из реестра
• Создаст и запустит контейнеры
• Инициализирует базу данных
• Создаст учётную запись администратора

Структура репозитория

Car-transport-pass-system/
├── backend/          # FastAPI + PostgreSQL (API + отдача web)
│   ├── Dockerfile
│   ├── requirements.txt
│   └── .env          # создать вручную (см. ниже)
├── web/              # Веб-интерфейс (PWA-ready, HTML/CSS/JS)
├── mobile/android/   # Android-приложение GuardPass (Kotlin)
└── docker-compose.yml

Функционал

• Роли: admin, manager, guard, viewer
• Гибкие права (extra_permissions): создание / редактирование / аннулирование / архивирование пропусков, активация, пометка на удаление, скачивание PDF, видимость разделов меню
• Постоянные пропуска: создание, редактирование, активация, аннулирование, восстановление, архивирование, история изменений, автоматическое аннулирование по истечении срока
• Временные пропуска: выдача, отметки «Заехал» / «Выехал», отзыв, печать PDF, отчёт по организациям
• PDF: одиночная и пакетная печать, отчёт по организациям
• Визуальные редакторы шаблонов: пропуск (100×90 мм), отчёт по организациям, временный пропуск, отчёт временных пропусков
• Справочники: организации, марки и модели автомобилей, водители
• Главная (мониторинг): кликабельные карточки статусов с переходом на фильтрованный список
• NVR-интеграция: синхронизация номеров с видеосистемой Dahua, автоочистка истёкших номеров
• REST API + Swagger /docs

---

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

Требования

• Docker 24+
• Docker Compose v2 (входит в Docker Desktop)

Шаг 1 — Клонировать репозиторий

git clone https://git.kinoteka.space/KirsanovAdmin/Car-transport-pass-system.git
cd Car-transport-pass-system

Шаг 2 — Создать файл окружения

Создайте файл backend/.env на основе примера ниже:

# База данных (хост db — имя сервиса в docker-compose)
POSTGRES_DB=propusk_system
POSTGRES_USER=postgres
POSTGRES_PASSWORD=сменить_пароль
POSTGRES_HOST=db
POSTGRES_PORT=5432

# Безопасность
SECRET_KEY=сменить_на_длинную_случайную_строку

# CORS — укажите адрес, с которого открывается интерфейс
CORS_ALLOW_ORIGINS=http://localhost:8000,http://127.0.0.1:8000

# Cookies
COOKIE_SECURE=False
COOKIE_SAMESITE=lax

Важно: POSTGRES_HOST=db — это имя сервиса БД внутри Docker-сети. Не меняйте, если не переименовываете сервис в docker-compose.yml.

Полный список переменных — в разделе Переменные окружения.

Шаг 3 — Авторизоваться в реестре и запустить

Образ хранится в Forgejo Container Registry. Войдите перед первым запуском:

docker login git.kinoteka.space

Затем собрать и запустить:

docker compose up -d --build

Либо скачать готовый образ без сборки:

docker pull git.kinoteka.space/kirsanovadmin/car-transport-pass-system:latest
docker compose up -d

Docker соберёт образ приложения, поднимет PostgreSQL и дождётся готовности БД перед стартом приложения.

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

docker compose ps

Ожидаемый результат:

NAME          STATUS
propusk_db    Up (healthy)
propusk_app   Up

Шаг 4 — Инициализация базы данных (только при первом запуске)

# Создать таблицы
docker compose exec app python init_db.py

# Заполнить справочники (марки, модели, организации)
docker compose exec app python seed_data.py

# Создать учётную запись администратора
docker compose exec app python create_admin.py

seed_propusks.py — опциональные тестовые данные. Не запускайте на продакшене.

Шаг 5 — Открыть приложение

Адрес	Что
http://localhost:8000/	Веб-интерфейс
http://localhost:8000/docs	Swagger API
http://localhost:8000/health	Health-check

---

Обновление

git pull
docker compose up -d --build

Если добавились миграции БД:

docker compose exec app python migrate.py migrate

---

Полезные команды

# Логи приложения (в реальном времени)
docker compose logs -f app

# Логи базы данных
docker compose logs -f db

# Остановить все сервисы
docker compose down

# Остановить и удалить данные БД (осторожно: данные будут удалены)
docker compose down -v

# Перезапустить только приложение
docker compose restart app

# Зайти в контейнер приложения
docker compose exec app bash

# Зайти в PostgreSQL
docker compose exec db psql -U postgres -d propusk_system

---

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

Файл backend/.env. Если задан DATABASE_URL — переменные POSTGRES_* игнорируются.

Переменная	По умолчанию	Описание
DATABASE_URL	(строится из POSTGRES*)_	Полная строка подключения
POSTGRES_DB	propusk_system	Имя базы данных
POSTGRES_USER	postgres	Пользователь БД
POSTGRES_PASSWORD	postgres	Пароль БД
POSTGRES_HOST	db	Хост БД (внутри Docker — имя сервиса)
POSTGRES_PORT	5432	Порт БД
SECRET_KEY	(обязательно)	Ключ подписи JWT
ACCESS_TOKEN_EXPIRE_MINUTES	1440	Время жизни токена (мин)
CORS_ALLOW_ORIGINS	(обязательно)	Разрешённые origin через запятую
COOKIE_SECURE	False	True при HTTPS
COOKIE_SAMESITE	lax	lax или strict
TELEGRAM_BOT_TOKEN	—	Токен бота для Telegram-авторизации
TELEGRAM_AUTH_MAX_AGE_SECONDS	86400	Время жизни Telegram-сессии
TELEGRAM_WELCOME_MESSAGE	—	Текст приветствия после привязки
N8N_TG_WELCOME_WEBHOOK_URL	—	Webhook n8n для приветственного сообщения
APP_NAME	Система управления пропусками	Название приложения
APP_VERSION	1.0.0	Версия
DEBUG	False	Режим отладки

---

Локальный запуск (без Docker)

Требуется Python 3.12. Версии 3.13+ не поддерживаются из-за совместимости зависимостей.

cd backend

# Создать виртуальное окружение
python3.12 -m venv venv312

# Установить зависимости
# Windows:  .\venv312\Scripts\python.exe -m pip install -r requirements.txt
# Linux/macOS:
./venv312/bin/python -m pip install -r requirements.txt

# Переменные окружения
export DATABASE_URL=postgresql+psycopg://user:pass@localhost:5432/propusk_system
export SECRET_KEY=your_secret_key
export CORS_ALLOW_ORIGINS=http://localhost:8000
export COOKIE_SECURE=False
export COOKIE_SAMESITE=lax

# Инициализация БД
./venv312/bin/python init_db.py
./venv312/bin/python seed_data.py
./venv312/bin/python create_admin.py

# Запуск
./venv312/bin/python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

---

Мобильное приложение GuardPass (Android)

Приложение для охранников КПП. Находится в mobile/android/GuardPass/.

• Открыть проект в Android Studio
• В настройках приложения указать адрес сервера (например http://192.168.1.10:8000)
• Войти под учётной записью с ролью guard

Функции: поиск по госномеру, просмотр всех активных пропусков, отметка въезда/выезда, статус синхронизации с NVR.

---

Заметки

• После изменения прав пользователя требуется перелогиниться.
• Для корректной кириллицы в PDF: docker compose exec app python install_fonts.py
• Если вместо кириллицы отображаются «???» — очистите кэш браузера, убедитесь что сервер отдаёт charset=utf-8.
• Секретный путь к админке задаётся в настройках (admin_secret_path).

---

Лицензия

Использование допускается только с письменного разрешения правообладателя. См. LICENSE.