Coworking Management System

Система управления коворкинг-пространством — сервис для бронирования рабочих мест и переговорных комнат с QR-кодами для доступа и аналитикой загруженности.

Стек технологий

Компонент	Технология
API	FastAPI
База данных	PostgreSQL
ORM	SQLAlchemy + Alembic
Очередь задач	Celery + RabbitMQ
Кэш	Redis
Контейнеризация	Docker Compose
QR-коды	qrcode + Pillow
Авторизация	JWT (PyJWT) + pwdlib

---

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

1. Клонировать репозиторий

git clone <repo_url>
cd CPB&MSystem/app

2. Создать .env файл

В данном проекте .env файл уже сохранен в репозитории.

DATABASE_URL=postgresql://admin:admin_pass@localhost:5432/coworking
REDIS_URL=redis://localhost:6379/0
RABBITMQ_URL=amqp://coworking:coworking_pass@localhost:5672/
JWT_SECRET_KEY=your-secret-key-here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=1440
QR_OUTPUT_DIR=./qr_codes

3. Запустить через Docker Compose

# Инфраструктура (PostgreSQL, Redis, RabbitMQ) — один раз
docker compose -f docker-compose-infra.yml up -d

# Приложение (API + Celery)
docker compose up --build

4. Открыть Swagger UI

http://localhost:8000/docs

---

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

# Установить зависимости
uv add -r requirements.txt

# Применить миграции
uv run alembic upgrade head

# Терминал 1 — FastAPI
uvicorn main:app --reload

# Терминал 2 — Celery worker
celery -A tasks.celery_app worker --loglevel=info -Q qr,notifications,cleanup,analytics --pool=solo

# Терминал 3 — Celery beat
celery -A tasks.celery_app beat --loglevel=info

Windows: здесь используется --pool=solo для Celery worker

---

Структура проекта

app/
├── core/                   # Конфигурация, БД, кэш, безопасность
│   ├── config.py           # Настройки через pydantic-settings
│   ├── database.py         # SQLAlchemy engine, Base, get_db()
│   ├── cache.py            # Redis клиент, cache_get/set/delete
│   ├── security.py         # JWT + bcrypt
│   └── dependencies.py     # FastAPI Depends алиасы
├── models/                 # SQLAlchemy модели
├── schemas/                # Pydantic схемы
├── services/               # Бизнес-логика
├── api/                    # FastAPI роутеры
├── tasks/                  # Celery задачи
└── alembic/                # Миграции БД

---

API эндпоинты

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

POST /auth/register     — Регистрация
POST /auth/login        — Авторизация, получение JWT токена
GET  /auth/me           — Профиль текущего пользователя
PUT  /auth/me           — Обновление профиля

Пространства (публичные)

GET /workspaces/                        — Список рабочих мест
GET /workspaces/{id}                    — Детали места
GET /workspaces/{id}/availability       — Доступность по слотам (?date=2026-03-20)
GET /meeting-rooms/                     — Список переговорных
GET /meeting-rooms/{id}                 — Детали переговорной
GET /meeting-rooms/{id}/availability    — Доступность по слотам

Бронирования

POST   /bookings/               — Создать бронь
GET    /bookings/               — Мои бронирования (фильтры + пагинация)
GET    /bookings/{id}           — Детали брони
DELETE /bookings/{id}           — Отменить бронь (за 2+ часа до начала)
GET    /bookings/{id}/qr        — Скачать QR-код
POST   /bookings/{id}/checkin   — Отметить приход

Администрирование

POST/PUT/DELETE /admin/workspaces/{id}      — CRUD рабочих мест
POST/PUT/DELETE /admin/meeting-rooms/{id}   — CRUD переговорных
POST/DELETE     /admin/blocked-slots/{id}   — Блокировка слотов
GET/PUT         /admin/operating-hours      — Расписание работы

GET /admin/analytics/occupancy      — Загруженность по дням/часам
GET /admin/analytics/popular        — Топ популярных мест
GET /admin/analytics/revenue        — Доход за период
GET /admin/analytics/daily-report   — Отчёт за сегодня

---

Фоновые задачи (Celery)

Задача	Триггер	Описание
generate_qr_code	После создания брони	Генерация PNG QR-кода
send_reminder	При создании брони	Напоминание за 30 мин до начала
mark_no_show	При создании брони	No-show через 15 мин после start_time
cancel_unpaid_bookings	Каждые 15 мин (Beat)	Отмена pending броней
daily_report	Каждый день в 23:00 (Beat)	Отчёт о загруженности

---

Миграции

# Создать миграцию
uv run alembic revision --autogenerate -m "описание"

# Применить все миграции
uv run alembic upgrade head

# Откатить последнюю
uv run alembic downgrade -1

# История
uv run alembic history

---

Docker команды

# Логи всех сервисов
docker compose logs -f

# Логи конкретного сервиса
docker compose logs -f coworking_api

# Войти в PostgreSQL
docker exec -it coworking_postgres psql -U admin -d coworking

# Список таблиц
\dt

# Остановить (данные сохраняются)
docker compose down

# Остановить и удалить данные
docker compose down -v

---

Бизнес-логика бронирования

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

1. Место существует и is_available = True
2. start_time < end_time
3. Минимальная длительность — 30 минут
4. Время в рамках расписания коворкинга (operating_hours)
5. Нет пересечения с существующими бронями
6. Нет пересечения с заблокированными слотами (blocked_slots)
7. Rate limit — не более 10 броней в час на пользователя

Стоимость рассчитывается автоматически:

total_price = duration_hours * price_per_hour

---

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

Переменная	Описание	Пример
DATABASE_URL	PostgreSQL connection string	postgresql://user:pass@localhost:5432/db
REDIS_URL	Redis connection string	redis://localhost:6379/0
RABBITMQ_URL	RabbitMQ connection string	amqp://user:pass@localhost:5672/
JWT_SECRET_KEY	Секретный ключ для JWT	любая длинная строка
ALGORITHM	Алгоритм JWT	HS256
ACCESS_TOKEN_EXPIRE_MINUTES	Время жизни токена	1440 (24 часа)
QR_OUTPUT_DIR	Папка для QR-кодов	./qr_codes