ochenstarik/randomayzer
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
No description
7 commits 2 branches 0 tags 652 KiB
TypeScript 97.7%
PowerShell 2.1%
CSS 0.1%
Find a file
Ochenstarik 50973b4f85 feat(core): Phase 1.4 Production Hardening - double draw atomic protection, snapshot concurrency safety, Zod API validation, payload scalability & pagination, provider safety, normalized errors, idempotency, rate limiting, and 20 concurrent draw integration tests
2026-08-18 01:54:35 +07:00
.github/workflows feat(core): Phase 1.2 Final Core Audit Fixes - storage driver policy, snapshot relation binding, true Fisher-Yates HMAC_SHA256_FY_V1, proof/event hash separation, verification API, and GitHub Actions CI 2026-08-17 23:55:01 +07:00
docs test(opencode): independent review, VK integration plan, expanded unit tests, provider capabilities validation, and security/concurrency coverage 2026-08-18 00:24:00 +07:00
prisma feat(core): Phase 1.3 Public Verification Integrity - drawId persistence, real participant snapshot and rules recalculation, reserve winners check, auditEventHash verification, strict snapshot lookup, and anti-tampering test suite 2026-08-18 00:15:30 +07:00
src feat(core): Phase 1.4 Production Hardening - double draw atomic protection, snapshot concurrency safety, Zod API validation, payload scalability & pagination, provider safety, normalized errors, idempotency, rate limiting, and 20 concurrent draw integration tests 2026-08-18 01:54:35 +07:00
tests feat(core): Phase 1.4 Production Hardening - double draw atomic protection, snapshot concurrency safety, Zod API validation, payload scalability & pagination, provider safety, normalized errors, idempotency, rate limiting, and 20 concurrent draw integration tests 2026-08-18 01:54:35 +07:00
.env.example feat: initial commit - VK Giveaway Randomizer Phase 1 2026-08-17 23:34:49 +07:00
.eslintrc.json feat(core): Phase 1.1 hardening - Prisma persistence, FSM, immutable snapshots, unbiased HMAC_SHA256_FY_V1 randomizer, and audit proof 2026-08-17 23:44:51 +07:00
.gitignore feat: initial commit - VK Giveaway Randomizer Phase 1 2026-08-17 23:34:49 +07:00
docker-compose.yml feat: initial commit - VK Giveaway Randomizer Phase 1 2026-08-17 23:34:49 +07:00
next.config.mjs feat: initial commit - VK Giveaway Randomizer Phase 1 2026-08-17 23:34:49 +07:00
package-lock.json feat(core): Phase 1.4 Production Hardening - double draw atomic protection, snapshot concurrency safety, Zod API validation, payload scalability & pagination, provider safety, normalized errors, idempotency, rate limiting, and 20 concurrent draw integration tests 2026-08-18 01:54:35 +07:00
package.json feat(core): Phase 1.4 Production Hardening - double draw atomic protection, snapshot concurrency safety, Zod API validation, payload scalability & pagination, provider safety, normalized errors, idempotency, rate limiting, and 20 concurrent draw integration tests 2026-08-18 01:54:35 +07:00
postcss.config.js feat: initial commit - VK Giveaway Randomizer Phase 1 2026-08-17 23:34:49 +07:00
README.md feat: initial commit - VK Giveaway Randomizer Phase 1 2026-08-17 23:34:49 +07:00
tailwind.config.ts feat: initial commit - VK Giveaway Randomizer Phase 1 2026-08-17 23:34:49 +07:00
tsconfig.json feat: initial commit - VK Giveaway Randomizer Phase 1 2026-08-17 23:34:49 +07:00
vitest.config.ts feat: initial commit - VK Giveaway Randomizer Phase 1 2026-08-17 23:34:49 +07:00

README.md

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 и схемы связей.