# 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 (`HMAC_SHA256_FY_V1`) и несмещенной перетасовки Фишера-Йетса.
  - **Seed Pre-Commitment**: SHA-256 хеш сида фиксируется и публикуется на этапе фиксации слепка до жеребьевки, исключая seed grinding.
  - Snapshot Hash (SHA-256) канонического списка участников + раскрытый Seed = 100% математическая воспроизводимость.
  - Публичный результат (`GET /api/giveaways/[id]/public` и страница `/giveaways/[id]`) доступен любому участнику без входа в систему.
  - Поддержка основных и резервных призовых мест.
- **Интерактивный 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. Установка зависимостей

```bash
npm install
```

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

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

```bash
cp .env.example .env
```

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

Для работы с реальным VK API укажите в `.env`:
```env
VK_SERVICE_TOKEN="ваш_сервисный_ключ_vk"
```

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

```bash
docker compose up -d
npm run prisma:push
```

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

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

```bash
npm test
```

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

```bash
npm run dev
```

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

---

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

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

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

Запуск:
```bash
npm run test
```

---

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

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