From a6742e467e9ac40ceaf794c167103d238cf7db3e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D0=BB=D0=B5=D0=BA=D1=81=D0=B5=D0=B9=20=D0=A1=D0=B0?= =?UTF-8?q?=D0=B1=D0=B8=D0=BB=D0=B8=D0=BD?= Date: Wed, 15 Apr 2026 21:51:20 +0300 Subject: [PATCH] v0.0.1 --- .gitignore | 2 + specification.txt | 184 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 186 insertions(+) create mode 100644 .gitignore create mode 100644 specification.txt diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2945697 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +/.idea/ +/EventHubSpec.iml diff --git a/specification.txt b/specification.txt new file mode 100644 index 0000000..3cf88d6 --- /dev/null +++ b/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) \ No newline at end of file