v0.0.1

specification.txt

@@ -0,0 +1,184 @@
+ТЕХНИЧЕСКОЕ ЗАДАНИЕ (ТЗ) НА ПЛАТФОРМУ EVENTHUB
+Версия: 1.0 (расширенная)
+
+1. ЦЕЛИ И НАЗНАЧЕНИЕ
+EventHub — платформа для управления событиями с поддержкой календарей, записи участников (включая специалистов), гибкого подтверждения, рейтингов, отзывов, модерации, встроенного баг-трекера и платной подписки. Целевая аудитория: владельцы календарей (бизнес), участники (клиенты), администраторы.
+
+2. ФУНКЦИОНАЛЬНЫЕ ТРЕБОВАНИЯ
+
+2.1. Календари
+- CRUD календаря (название, описание, теги, владелец)
+- Расшаривание по ссылке (публичная/приватная)
+- Приглашение пользователей с правами "запись" или "администрирование"
+- Типы календарей: personal (бесплатный, без записи), commercial (платный, запись клиентов, специалисты)
+- Гибкое подтверждение заявок: auto (автоматически), manual (вручную), timeout (авто через N секунд)
+- Теги календаря, рейтинг (средняя оценка, количество голосов)
+
+2.2. События
+- Создание события (название, дата/время, длительность, тип: офлайн/онлайн)
+- Для офлайн: геоточка (адрес + координаты)
+- Для онлайн: ссылка (Zoom, Google Meet)
+- Ограничение количества мест
+- Привязка к специалисту (для коммерческих календарей)
+- Теги событий, рейтинг
+
+2.3. Запись участников и подтверждение
+- Запись через календарь
+- Подтверждение согласно политике календаря
+- Уведомления участника и владельца
+- Привязка события к специалисту (отдельная запись в календаре специалиста)
+
+2.4. Отзывы и рейтинги
+- Только участники событий могут оставлять отзывы
+- Оценка 1-5, текстовый комментарий
+- Отзывы на событие или на календарь
+- Модерация отзывов (администраторы могут скрывать)
+
+2.5. Поиск и фильтрация
+- По тексту, по тегам, по гео-позиции (радиус), по дате/времени
+
+2.6. Расширенные возможности
+- Экспорт в Google Calendar (через OAuth2)
+- Экспорт в Apple Calendar (ICS-файл)
+- Геокодирование (адрес -> координаты) через внешний API (заглушка / Nominatim)
+
+2.7. Модерация и безопасность
+- Жалобы на календари, события, отзывы
+- Автоматическая модерация по ключевым словам и по порогу жалоб
+- Ручная заморозка / разморозка администратором
+- Бан-лист слов
+- Аудит действий администраторов
+
+2.8. Баг-трекер (автоматический)
+- При ошибке создаётся тикет, группировка по хэшу ошибки
+- Учёт количества повторений
+- Уведомление пользователя при создании и при закрытии тикета
+- Доступ только у администраторов
+
+2.9. Платная подписка
+- Личное использование бесплатно (personal)
+- Коммерческое использование платно (commercial)
+- Пробный период 30 дней
+- Планы подписки: 1, 3, 6, 12 месяцев
+- Заглушка платежного шлюза (для тестирования)
+- Автоматическое истечение подписки
+
+2.10. Административная панель
+- Отдельный HTTPS-сервер (порт 8445) и отдельный WSS (порт 8446)
+- Управление календарями, событиями, отзывами, жалобами, тикетами, бан-словами
+- Статистика, информация о нодах кластера
+- WebSocket-уведомления администраторам
+
+2.11. Real-time уведомления (WebSocket)
+- Пользователи: подписка на календарь, получение обновлений
+- Администраторы: подписка на глобальные уведомления (жалобы, авто-заморозки)
+
+3. НЕФУНКЦИОНАЛЬНЫЕ ТРЕБОВАНИЯ
+
+3.1. Производительность и масштабирование
+- 100 000+ пользователей
+- Горизонтальное масштабирование (увеличение нод)
+- Mnesia с дисковыми копиями на нескольких нодах
+- Отдельные ноды для исторических данных (disc_only_copies)
+- Пагинация всех списков
+
+3.2. Надёжность
+- Супервизорное дерево OTP
+- Let it crash – быстрый перезапуск процессов
+- Автоматическое восстановление после падения ноды (Mnesia)
+
+3.3. Безопасность
+- JWT с ролью (user / admin)
+- HTTPS / WSS (самоподписанный сертификат для dev, реальный для prod)
+- Argon2 для хеширования паролей (erlang-argon2)
+- OAuth2 для Google (опционально)
+- Refresh token (запланирован)
+
+3.4. Наблюдаемость
+- Healthcheck эндпоинт
+- Логирование (JSON, ротация)
+- Prometheus метрики (запланированы)
+- Аудит действий админов
+
+3.5. CI/CD
+- Drone CI (или GitLab CI / GitHub Actions)
+- EUnit + Common Test + Tsung
+- Сборка релиза
+- Docker-образ
+- Горячее обновление (rolling upgrade) кластера (3+ нод)
+- Миграции Mnesia
+
+4. СТЕК ТЕХНОЛОГИЙ (С ВЕРСИЯМИ)
+- Бэкенд: Erlang/OTP 28.2
+- Сборка: rebar3 3.27.0
+- HTTP/WebSocket: Cowboy 2.10.0
+- JSON: jsx 3.1.0
+- JWT: jwerl 1.1.0
+- Хеширование паролей: erlang-argon2 1.0.0
+- Тестирование: meck 0.9.2, gun 2.0.0
+- Нагрузочное тестирование: Tsung 1.8.0
+- CI/CD: Drone 2.0+
+- Контейнеризация: Docker 20.10+
+- База данных: Mnesia (встроенная, распределённая)
+
+5. ИЕРАРХИЧЕСКАЯ СТРУКТУРА КОДА
+
+src/
+├── infra/           # инфраструктура (приложение, супервизоры, аутентификация, подписки)
+├── core/            # слой доступа к данным (DAO) и модели
+├── logic/           # бизнес-логика (независимая от HTTP/WS)
+├── services/        # внешние сервисы (заглушки/интеграции)
+└── handlers/        # обработчики HTTP/WebSocket
+
+Правила:
+- Модули handlers/ не содержат бизнес-логики.
+- Модули logic/ не знают о HTTP/WS.
+- Модули core/ (DAO) работают только с Mnesia.
+- Модули services/ могут быть заменены на реальные реализации без изменения остального кода.
+- Заголовочный файл include/records.hrl содержит все записи таблиц Mnesia.
+
+6. ОСНОВНЫЕ API (КРАТКО)
+
+Пользовательские (порт 8080):
+- POST /v1/register
+- POST /v1/login
+- GET /v1/user/me
+- POST /v1/calendars + CRUD
+- POST /v1/calendars/:id/events + CRUD
+- POST /v1/events/:id/join
+- POST /v1/events/:id/confirm/:user_id
+- POST /v1/reviews
+- POST /v1/reports
+- POST /v1/subscription/activate
+- POST /v1/events/:id/export (Google)
+- GET /v1/events/:id/ical (Apple)
+- GET /health
+
+WebSocket (порт 8081): ws://localhost:8081/ws?token=...
+
+Административные (порт 8445):
+- GET /admin/stats/overview
+- GET /admin/nodes
+- GET /admin/calendars, PUT /admin/calendars/:id/freeze, /unfreeze
+- GET /admin/events, PUT /admin/events/:id/freeze
+- GET /admin/reviews, PUT /admin/reviews/:id/hide
+- GET /admin/reports, PUT /admin/reports/:id/status
+- GET /admin/tickets, PUT /admin/tickets/:id/status
+- GET /admin/banned_words, POST, DELETE
+
+Административный WebSocket (порт 8446): wss://localhost:8446/admin/ws?token=...
+
+7. ВЕРСИОНИРОВАНИЕ И СТАТУС
+Текущая версия: 0.0.1 (MVP, альфа)
+
+8. ОГРАНИЧЕНИЯ И ДОПУЩЕНИЯ
+- В разработке используются самоподписанные SSL-сертификаты.
+- Для production требуется реальный сертификат и настройка OAuth2 для Google.
+- Заглушки внешних сервисов должны быть заменены перед запуском.
+
+9. ТРЕБОВАНИЯ К ОКРУЖЕНИЮ
+- Erlang/OTP 28.2
+- rebar3 3.27.0
+- openssl
+- Docker (опционально)
+- Drone (опционально, для CI/CD)