diff --git a/README.md b/README.md index 0f231ec..7476c49 100644 --- a/README.md +++ b/README.md @@ -73,4 +73,10 @@ InviteMe/ Проект разрабатывается для компании **Integrita**. Планируется развёртывание на виртуальной машине. -См. `docs/DEPLOY.md` для инструкций по настройке SMTP, запуску в production и резервному копированию. +- Подробный контекст, бизнес-процесс и чеклист — в `docs/CONTEXT.md`. +- Инструкции по настройке SMTP, запуску в production и резервному копированию — в `docs/DEPLOY.md`. + +## Ссылки на документацию + +- `docs/CONTEXT.md` — контекст, роли, поток данных, чеклист +- `docs/DEPLOY.md` — развёртывание, настройка SMTP, запуск в production diff --git a/docs/CONTEXT.md b/docs/CONTEXT.md new file mode 100644 index 0000000..07a0ad7 --- /dev/null +++ b/docs/CONTEXT.md @@ -0,0 +1,187 @@ +# Контекст проекта InviteMe + +## Назначение + +InviteMe — внутреннее веб-приложение для компании **Integrita**, предназначенное для организации регистрации гостей на корпоративные мероприятия. Является упрощённым аналогом Timepad: загрузка списка участников, генерация персональных QR-кодов, рассылка приглашений, контроль входа на мероприятии и административная аналитика. + +## Бизнес-процесс + +### 1. Подготовка до мероприятия + +1. Организатор формирует Excel-файл со столбцами: + - `Отдел` + - `ФИО` + - `Должность` + - `e-mail` + - `название фото` +2. Собирает фотографии гостей. Название каждого файла должно совпадать со значением в столбце `название фото`. +3. В админ-панели загружает Excel. Система автоматически создаёт записи гостей и генерирует для каждого уникальный QR-код. +4. Загружает фото (по одному или ZIP-архивом) в папку `app/static/uploads/photos/`. +5. При необходимости вручную добавляет, редактирует или блокирует гостей. +6. Запускает массовую рассылку приглашений. Каждый гость получает письмо с QR-кодом. + +### 2. Вход на мероприятие + +1. Сотрудники на входе открывают страницу `/check-in` на телефоне/планшете. +2. Авторизуются под учётной записью `staff`. +3. Проверяют гостей одним из способов: + - Сканирование QR-кода с экрана телефона или распечатки. + - Поиск по ФИО (вводят фамилию, выбирают из выпадающего списка). +4. На экране отображается крупное фото гостя, отдел, должность, email и кнопка «Отметить вход». +5. Сотрудник сверяет фото с гостем и нажимает кнопку. +6. Если гость уже был отмечен, система показывает предупреждение и время входа. + +### 3. Аналитика во время и после мероприятия + +1. Организатор в админ-панели видит: + - Общее количество гостей. + - Количество пришедших. + - Процент посещаемости. + - Список последних входов. +2. Может быстро проверить по ФИО, пришёл ли конкретный человек. +3. Может выгрузить отчёт в Excel с отметкой о посещении и временем входа для каждого участника. + +## Роли пользователей + +| Роль | Логин по умолчанию | Возможности | +|---|---|---| +| Администратор | `admin` / `admin` | Полный доступ: загрузка данных, управление гостями, рассылка, аналитика, отчёты | +| Сотрудник на входе | `staff` / `staff` | Только страница `/check-in`: сканирование QR, поиск, отметка входа | + +> В production пароли обязательно меняются через переменные окружения или файл `.env`. + +## Архитектура + +```text +┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ +│ Браузер │──────│ Flask │──────│ SQLite │ +│ (Admin/ │ │ (Python) │ │ (inviteme.db) │ +│ Staff) │ │ │ └─────────────────┘ +└─────────────┘ └──────┬──────┘ + │ + ┌────────────────┼────────────────┐ + │ │ │ + ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐ + │ QR-сервис │ │ Email │ │ Excel │ + │ (qrcode) │ │ (SMTP) │ │ (openpyxl)│ + └────────────┘ └───────────┘ └───────────┘ +``` + +- **Flask** обрабатывает HTTP-запросы и рендерит HTML-шаблоны. +- **SQLite** хранит данные гостей и историю входов. +- **Локальная файловая система** хранит фото и QR-коды. +- **SMTP** используется для отправки приглашений. + +## Поток данных + +### Импорт гостей + +```text +Excel-файл + ↓ +excel_service.read_guests_from_excel() + ↓ +Создание/обновление записей Guest в SQLite + ↓ +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= + ↓ +Загрузка карточки гостя + ↓ +POST /api/check-in/ + ↓ +Проверка: уже отмечен? + ↓ +Создание записи CheckIn или возврат ошибки 409 +``` + +## Формат Excel + +Обязательные столбцы (имена должны совпадать точно): + +| Столбец | Описание | Пример | +|---|---|---| +| `Отдел` | Название отдела | IT | +| `ФИО` | Полное имя | Иванов Иван Иванович | +| `Должность` | Должность гостя | Разработчик | +| `e-mail` | Email для рассылки | ivanov@company.com | +| `название фото` | Имя файла фото | ivanov.jpg | + +> Важно: значение в столбце `название фото` должно точно совпадать с именем загруженного файла, включая расширение. + +## Хранение файлов + +```text +app/static/uploads/ +├── photos/ # Фото гостей +├── qrcodes/ # Сгенерированные QR-коды +├── reports/ # Выгруженные отчёты +└── temp/ # Временные файлы при загрузке +``` + +Эти папки создаются автоматически при старте приложения. + +## Ограничения и предположения + +- Приложение рассчитано на сотни гостей. При необходимости масштабирования на тысячи рекомендуется перейти с SQLite на PostgreSQL. +- Все фото и QR-коды хранятся локально на диске. Перед переносом на другой сервер их нужно копировать отдельно (они не хранятся в git). +- Рассылка писем происходит синхронно. Для очень больших списков (сотни писем) рекомендуется рассылать партиями. +- QR-код содержит прямую ссылку на страницу входа. При переносе на другой хост необходимо указать корректный `BASE_URL` в `.env` или при загрузке Excel. + +## Чеклист перед мероприятием + +- [ ] Подготовлен Excel со списком гостей. +- [ ] Собраны и загружены фото всех гостей. +- [ ] Загружен Excel в админ-панель. +- [ ] Проверено, что QR-коды сгенерированы. +- [ ] Настроен SMTP и отправлено тестовое письмо. +- [ ] Разосланы приглашения. +- [ ] Созданы учётные записи для сотрудников на входе (или используется общая `staff`). +- [ ] Протестирована страница `/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, аналитика.