Initial commit: InviteMe production redesign

2026-09-01 11:04:21 +03:00
commit 6060c22ff3
71 changed files with 6912 additions and 0 deletions
@@ -0,0 +1,195 @@
+# Контекст проекта 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, поиск, отметка входа |
+
+Пользователи создаются и управляются через веб-интерфейс администратора. При первом запуске открывается страница создания первого администратора.
+
+## Архитектура
+
+```text
+┌─────────────┐      ┌─────────────┐      ┌─────────────────┐
+│   Браузер   │──────│   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** используется для отправки приглашений.
+
+## Поток данных
+
+### Импорт гостей
+
+```text
+Создание мероприятия в админ-панели
+    ↓
+Excel-файл
+    ↓
+excel_service.read_guests_from_excel()
+    ↓
+Создание/обновление записей Guest в базе данных (с привязкой к мероприятию)
+    ↓
+qr_service.generate_qr_for_guest() для каждого нового гостя
+    ↓
+Готовность к рассылке
+```
+
+### Рассылка приглашений
+
+```text
+Гость с invitation_sent = false
+    ↓
+email_service.send_invitation()
+    ↓
+HTML-шаблон + QR-код как вложение
+    ↓
+Отправка через SMTP
+    ↓
+invitation_sent = true
+```
+
+### Проверка входа
+
+```text
+QR-код → URL /check-in?token=<uuid>
+    ↓
+Загрузка карточки гостя
+    ↓
+POST /api/check-in/<token>
+    ↓
+Проверка: уже отмечен?
+    ↓
+Создание записи CheckIn или возврат ошибки 409
+```
+
+## Формат Excel
+
+Обязательные столбцы (имена должны совпадать точно):
+
+| Столбец | Описание | Пример |
+|---|---|---|
+| `Отдел` | Название отдела | IT |
+| `ФИО` | Полное имя | Иванов Иван Иванович |
+| `Должность` | Должность гостя | Разработчик |
+| `e-mail` | Email для рассылки | ivanov@company.com |
+| `название фото` | Имя файла фото | ivanov.jpg |
+
+> Важно: значение в столбце `название фото` должно точно совпадать с именем загруженного файла, включая расширение.
+
+## Хранение файлов
+
+```text
+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** — Добавлены пользователи, роли и поддержка нескольких мероприятий.