109 lines
5.6 KiB
Markdown
109 lines
5.6 KiB
Markdown
# 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 и схемы связей.
|