InviteMe/docs/CONTEXT.md

Контекст проекта InviteMe

Назначение

InviteMe — веб-приложение для организации регистрации гостей на корпоративные мероприятия. Является упрощённым аналогом Timepad: загрузка списка участников, генерация персональных QR-кодов, рассылка приглашений, контроль входа на мероприятии и административная аналитика.

Бизнес-процесс

1. Подготовка до мероприятия

1. Администратор создаёт учётные записи организаторов и сотрудников на входе.
2. Организатор создаёт новое мероприятие в админ-панели.
3. Организатор формирует Excel-файл со столбцами:
   • Отдел
   • ФИО
   • Должность
   • e-mail
   • название фото
4. Собирает фотографии гостей. Название каждого файла должно совпадать со значением в столбце название фото.
5. В админ-панели выбирает созданное мероприятие и загружает Excel. Система создаёт записи гостей в рамках этого мероприятия и генерирует для каждого уникальный QR-код.
6. Загружает фото (по одному или ZIP-архивом) — они сохраняются в закрытой папке мероприятия instance/uploads/photos/event_<id>/.
7. При необходимости вручную добавляет, редактирует или блокирует гостей.
8. Запускает массовую рассылку приглашений. Каждый гость получает письмо с QR-кодом.

2. Вход на мероприятие

1. Сотрудники на входе открывают страницу /check-in на телефоне/планшете.
2. Авторизуются под учётной записью staff.
3. Проверяют гостей одним из способов:
   • Сканирование QR-кода с экрана телефона или распечатки.
   • Поиск по ФИО (вводят фамилию, выбирают из выпадающего списка).
4. На экране отображается крупное фото гостя, отдел, должность, email и кнопка «Отметить вход».
5. Сотрудник сверяет фото с гостем и нажимает кнопку.
6. Если гость уже был отмечен, система показывает предупреждение и время входа.

3. Аналитика во время и после мероприятия

1. Организатор в админ-панели видит:
   • Общее количество гостей.
   • Количество пришедших.
   • Процент посещаемости.
   • Список последних входов.
2. Может быстро проверить по ФИО, пришёл ли конкретный человек.
3. Может выгрузить отчёт в Excel с отметкой о посещении и временем входа для каждого участника.

Роли пользователей

Роль	Возможности
Администратор	Полный доступ: управление пользователями, всеми мероприятиями, гостями, рассылка, аналитика, отчёты
Организатор	Создание и управление своими мероприятиями, гостями, рассылка, аналитика, отчёты
Сотрудник на входе	Страница /check-in: доступ только к назначенным мероприятиям, сканирование QR, поиск, отметка входа

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

Архитектура

┌─────────────┐      ┌─────────────┐      ┌─────────────────┐
│   Браузер   │──────│   Flask     │──────│   PostgreSQL    │
│  (Admin/    │      │   (Python)  │      │  (inviteme.db)  │
│ Organizer/  │      │             │      └─────────────────┘
│   Staff)    │      └──────┬──────┘
└─────────────┘             │
           ┌────────────────┼────────────────┐
           │                │                │
     ┌─────▼─────┐    ┌─────▼─────┐    ┌─────▼─────┐
     │  QR-сервис │    │  Email    │    │   Excel   │
     │  (qrcode)  │    │  (SMTP)   │    │ (openpyxl)│
     └────────────┘    └───────────┘    └───────────┘

• Flask обрабатывает HTTP-запросы и рендерит HTML-шаблоны.
• PostgreSQL хранит пользователей, мероприятия, гостей, RSVP и историю входов. SQLite используется только локально.
• RQ worker + Redis выполняют массовую рассылку в фоне и сохраняют прогресс независимо от браузера.
• Локальная файловая система хранит фото и QR-коды.
• SMTP используется для отправки приглашений.

Поток данных

Импорт гостей

Создание мероприятия в админ-панели
    ↓
Excel-файл
    ↓
excel_service.read_guests_from_excel()
    ↓
Создание/обновление записей Guest в базе данных (с привязкой к мероприятию)
    ↓
qr_service.generate_qr_for_guest() для каждого нового гостя
    ↓
Готовность к рассылке

Рассылка приглашений

Гость с invitation_sent = false
    ↓
email_service.send_invitation()
    ↓
HTML-шаблон + QR-код как вложение
    ↓
Отправка через SMTP
    ↓
invitation_sent = true

Проверка входа

QR-код → URL /check-in?token=<uuid>
    ↓
Загрузка карточки гостя
    ↓
POST /api/check-in/<token>
    ↓
Проверка: уже отмечен?
    ↓
Создание записи CheckIn или возврат ошибки 409

Формат Excel

Обязательные столбцы (имена должны совпадать точно):

Столбец	Описание	Пример
Отдел	Название отдела	IT
ФИО	Полное имя	Иванов Иван Иванович
Должность	Должность гостя	Разработчик
e-mail	Email для рассылки	ivanov@company.com
название фото	Имя файла фото	ivanov.jpg

Важно: значение в столбце название фото должно точно совпадать с именем загруженного файла, включая расширение.

Хранение файлов

instance/uploads/
├── photos/          # Фото гостей
├── qrcodes/         # Сгенерированные QR-коды
├── reports/         # Выгруженные отчёты
└── temp/            # Временные файлы при загрузке

Эти папки создаются автоматически при старте приложения.

Ограничения и предположения

• Production-конфигурация использует PostgreSQL и рассчитана на мероприятия с сотнями или тысячами гостей при одном экземпляре приложения.
• Все фото и QR-коды хранятся локально на диске. Перед переносом на другой сервер их нужно копировать отдельно (они не хранятся в git).
• Массовая рассылка писем выполняется фоновым worker-процессом; результат и ошибка сохраняются для каждого гостя.
• QR-код содержит прямую ссылку на страницу входа. При переносе на другой хост необходимо указать корректный BASE_URL в .env или при загрузке Excel.

Чеклист перед мероприятием

• Созданы учётные записи организаторов и сотрудников на входе.
• Создано мероприятие в админ-панели.
• Подготовлен Excel со списком гостей.
• Собраны и загружены фото всех гостей.
• Загружен Excel в админ-панель в рамках нужного мероприятия.
• Проверено, что QR-коды сгенерированы.
• Настроен SMTP и отправлено тестовое письмо.
• Разосланы приглашения.
• Протестирована страница /check-in на телефоне/планшете.
• Проверена работа камеры и сканирования QR.
• Проверен поиск по ФИО.
• Настроено резервное копирование базы и загруженных файлов.

Распространённые проблемы

Гость не находится по QR

• Проверьте, что гость не заблокирован (is_active = true).
• Проверьте, что QR-код не был перегенерирован, а старый распечатан.

Фото не отображается на странице входа

• Проверьте точное совпадение имени файла в Excel и в папке uploads/photos/.
• Проверьте, что файл действительно загружен.

Письма не отправляются

• Проверьте настройки SMTP в .env.
• Для Yandex/Google используйте пароль приложения, а не основной пароль.
• Проверьте логи консоли Flask.

QR-код ведёт на localhost

• Укажите BASE_URL в .env.
• Или введите базовый URL при загрузке Excel в админ-панели.

История изменений

• 2026-08-28 — Первая рабочая версия (MVP). Реализованы импорт Excel, QR-коды, рассылка, check-in, аналитика.
• 2026-08-28 — Добавлены пользователи, роли и поддержка нескольких мероприятий.