Randomayzer — VK Giveaway Randomizer (Этап 1)

Веб-приложение для проведения честных, прозрачных и доказуемых (Provably Fair) розыгрышей среди пользователей ВКонтакте (с архитектурным заделом под Telegram, YouTube и др.).

---

🎯 Возможности первого этапа

• Парсинг и превью записей VK: Поддержка любых ссылок на посты ВКонтакте (vk.com/wall..., m.vk.com, vk.ru, ?w=wall...).
• Сбор участников и фильтрация:
  • Лайки записи ❤️
  • Комментарии (с дедупликацией: 1 пользователь = 1 шанс) 💬
  • Репосты (с учетом настроек приватности профилей) 🔁
  • Проверка подписки на сообщество-организатор 👥
  • Исключение администраторов сообщества 🛡️
  • Черный список ID и логинов.
• Детерминированный Randomizer (Provably Fair):
  • Исключен непрозрачный Math.random().
  • Выборка на основе HMAC-SHA256 и перетасовки Фишера-Йетса.
  • Snapshot Hash (SHA-256) канонического списка участников + Seed = 100% повторяемость и верифицируемость.
  • Поддержка основных и резервных призовых мест.
• Интерактивный UI:
  • Dashboard со статистикой и списком кампаний.
  • 5-шаговый визард создания розыгрыша.
  • Живое превью условий и статуса допуска каждого участника с указанием причин отклонения.
  • Презентация победителей и сертификат криптографического аудита.

---

🏗 Архитектура и стек технологий

• Frontend / Backend: Next.js 14+ (App Router), TypeScript, React, TailwindCSS, Lucide Icons.
• Core Domain: Независимый от соцсетей слой (src/core/) для жеребьевки, хеширования и фильтрации.
• Social Providers: Абстракция SocialMediaProvider (src/providers/) с клиентом VK API и встроенным VkMockProvider для изолированной разработки.
• База данных: PostgreSQL 16 + Prisma ORM (с in-memory fallback для быстрого локального запуска).
• Тесты: Vitest (юнит-тесты детерминированности, seed reproducibility, фильтров и парсера).

---

🚀 Инструкция по локальному запуску

1. Установка зависимостей

npm install

2. Настройка переменных окружения

Скопируйте файл конфигурации:

cp .env.example .env

По умолчанию приложение работает в автономном/mock-режиме без обязательного указания боевого ключа VK API.

Для работы с реальным VK API укажите в .env:

VK_SERVICE_TOKEN="ваш_сервисный_ключ_vk"

3. Запуск базы данных (Docker Compose, опционально)

docker compose up -d
npm run prisma:push

(Если Docker не запущен, приложение автоматически использует встроенный store).

4. Запуск тестов

npm test

5. Запуск сервера разработки

npm run dev

Откройте в браузере: http://localhost:3000

---

🧪 Запуск автоматических тестов

В проекте реализованы unit-тесты ядра:

• tests/randomizer.test.ts: Тесты воспроизводимости seed, отсутствия дублей, выборки резерва и сторонней верификации verifyDrawResult.
• tests/filter-engine.test.ts: Тесты всех комбинаций условий отбора, дедупликации комментариев и черных списков.
• tests/vk-parser.test.ts: Тесты парсинга всех форматов ссылок VK.

Запуск:

npm run test

---

📚 Документация проекта

• docs/VK_API_RESEARCH.md — Исследование официального VK API, лимитов, токенов и методов execute.
• docs/ARCHITECTURE.md — Архитектура слоев, абстракция провайдеров и механизм Provably Fair.
• docs/DATA_MODEL.md — Модели данных Prisma и схемы связей.