Game Faucet - Blockchain Mining Game Platform

Разработчик: Живко Георгиев
Организация: Vi Team Security Group
Версия: 1.5.0
Лиценз: Proprietary - All rights reserved

---

📋 Описание

Game Faucet е пълнофункционална платформа за blockchain mining игра с виртуална икономика. Системата позволява на потребителите да изграждат своя майнинг империя чрез стаи, рафтове и майнъри, да оптимизират производителността си и да печелят криптовалута в реално време.

Платформата включва изцяло функционален административен панел с над 30+ модула за управление на всички аспекти на системата - от потребители и игрова механика до аналитика, сигурност и финанси.

---

✨ Ключови Функционалности

🎮 Игрова Механика

• Виртуален Майнинг: Стаи, рафтове и майнъри с реална икономика
• Hashrate Система: Изчисляване на производителност и награди
• Множество Криптовалути: Поддръжка на различни криптовалути (BTC, VRSC, и др.)
• Автоматични Награди: Cron базирана система за разпределение на награди
• Seasons & Events: Сезонни събития с leaderboards и специални награди
• Missions System: Daily, Weekly, и Seasonal missions
• Login Streak: Ежедневни login бонуси с прогресивни множители
• Guilds/Teams: Социална система за групиране на играчи
• Room → Rack → Miners System: RollerCoin-like room editor с grid layout
• Hashrate Calculation: Автоматично изчисляване на hashrate с бонуси (rack, room, miner)
• Events & Logs: Пълна система за логиране на всички действия
• Support Tickets: Интегрирана support система с тикети и съобщения

👥 Управление на Потребители

• Регистрация и Вход: Пълна система за автентификация
• Социален Вход: Интеграция с Google, Facebook, GitHub, Discord (OAuth)
• Роли и Права: Admin, Moderator, User роли с гранулиран контрол
• Онлайн Статус: Показване на онлайн/офлайн статус на потребителите
• Реферална Система: Проследяване на реферали и награди
• Банове и Модерация: Система за управление на банове и подозрителни акаунти

🛡️ Сигурност и Anti-Cheat

• Anti-Cheat Правила: Настройки на лимити (claims/hour, claims/day)
• IP Ограничения: Максимален брой акаунти на IP, блокиране на TOR/VPN
• Security Events: Лог на събития за сигурност в реално време
• Ban Review Queue: Автоматично откриване на подозрителна активност
• Multi-Account Detection: Откриване на множество акаунти от един потребител

📊 Аналитика и Отчети

• Player Analytics: DAU/WAU/MAU метрики, retention анализ
• Economy Analytics: Проследяване на награди, депозити, тегления
• Room & Miner Analytics: Анализ на популярност и ROI
• Profitability Dashboard: Изчисления на доходност
• Admin Activity Logs: Пълен лог на административни действия

💰 Икономика и Финанси

• Faucet Settings: Настройки на claim интервали и награди
• Exchange Rates: Управление на обменни курсове
• Payment Providers: Интеграция с платежни провайдъри
• Deposits & Withdrawals: Пълна система за депозити и тегления
• Promo Codes: Система за промоционални кодове
• Reward Logs: Детайлни логове на всички награди

📧 Комуникация

• Email System: PHPMailer интеграция (SMTP или PHP mail)
• Email Templates: Управление на email шаблони
• Social Login Settings: Конфигурация на OAuth провайдъри

⚙️ Системни Настройки

• Categorized Settings: 54+ настройки организирани в 7 категории
• Feature Flags: Система за включване/изключване на функции
• Config History: История на промените в настройките
• Maintenance Mode: Режим на поддръжка
• Changelog: Документация на промените в системата
• Extended RBAC: Fine-grained permissions (super_admin, admin, operator, analyst, finance)
• 2FA: Two-factor authentication за админ акаунти
• Rate Limiting: Защита срещу abuse и DDoS
• Security Headers: CSP, X-Frame-Options, HSTS, и др.
• Backup & Recovery: Автоматични backup скриптове
• System Status: Real-time мониторинг на системата

---

🛠️ Технологичен Стек

Backend

• PHP 8.1+ - Основен език за програмиране
• MySQL/MariaDB - Релационна база данни
• PDO - Database abstraction layer
• PHPMailer 6.9+ - Email библиотека
• Repository Pattern - Data access layer
• Service Layer - Business logic separation
• PSR-4 Autoloading - Modern PHP structure

Frontend

• Bootstrap 5.3 - CSS framework за responsive дизайн
• jQuery - JavaScript библиотека
• Bootstrap Icons - Икони за UI

Инфраструктура

• Docker - Контейнеризация
• Docker Compose - Multi-container orchestration
• Composer - PHP dependency manager
• PHPUnit 10 - Unit и Feature тестове
• CI/CD - Forgejo/GitHub Actions pipelines
• .env Configuration - Environment-based config

Архитектура

• Layered Architecture - Repository → Service → Controller
• MVC-like Structure - Организация на кода по модел-изглед-контролер принцип
• Singleton Pattern - За database connections
• Session-based Authentication - Управление на сесии
• REST API - RESTful API endpoints
• Dependency Injection - Service layer с DI

---

📁 Структура на Проекта

shivik/
├── admin/                  # Административен панел
│   ├── ajax/              # AJAX endpoints
│   ├── *.php              # Админ страници (30+ модула)
│   ├── header.php         # Общ header за админ панела
│   └── footer.php         # Общ footer за админ панела
│
├── assets/                 # Статични ресурси
│   ├── css/               # Стилове
│   ├── js/                # JavaScript файлове
│   └── images/            # Изображения
│
├── config/                 # Конфигурационни файлове
│   ├── config.php         # Основни настройки
│   └── db.php             # Database конфигурация
│
├── cron/                   # Автоматизирани задачи
│   └── rewards.php        # Разпределение на награди
│
├── migrations/             # Database миграции
│   └── *.sql              # SQL миграционни скриптове
│
├── sessions/               # Session файлове
│
├── system/                 # Core системни класове (legacy)
│   ├── Auth.php           # Автентификация
│   ├── DB.php             # Database wrapper
│   ├── Session.php        # Session управление
│   ├── User.php           # Потребителски операции
│   ├── Settings.php       # Системни настройки
│   ├── Menu.php           # Динамично меню
│   ├── Mailer.php         # Email система
│   ├── Room.php           # Стаи логика
│   ├── Rack.php           # Рафтове логика
│   ├── Miner.php          # Майнъри логика
│   ├── Payment.php        # Плащания
│   ├── Cryptocurrency.php # Криптовалути
│   ├── Maintenance.php    # Maintenance mode
│   └── functions.php      # Helper функции
│
├── src/                    # Нова архитектура (v1.1+)
│   ├── Repositories/      # Data access layer
│   ├── Services/          # Business logic
│   ├── Controllers/       # HTTP handlers
│   └── Contracts/         # Interfaces
│
├── api/v1/                 # REST API v1
│   ├── index.php          # Entry point
│   ├── routes.php         # Routing
│   ├── openapi.yaml       # API specification
│   └── controllers/       # API controllers
│
├── tests/                  # PHPUnit тестове
│   ├── Unit/              # Unit tests
│   └── Feature/           # Integration tests
│
├── migrations/             # Database миграции
│   ├── 001_extend_settings_table.sql
│   ├── 002_seasons_and_events.sql
│   ├── 003_guilds_and_teams.sql
│   ├── 004_dual_currency.sql
│   ├── 005_offerwall_and_notifications.sql
│   └── 006_security_and_legal.sql
│
├── scripts/                # Utility скриптове
│   ├── backup_database.sh
│   └── restore_database.sh
│
├── docs/                   # Документация
│   ├── ECONOMY.md         # Икономически модел
│   └── ROOM_SYSTEM.md     # Room → Rack → Miners система
│
├── uploads/                # Качени файлове
│   ├── users/             # Потребителски файлове
│   ├── rooms/             # Стаи изображения
│   └── miners/            # Майнъри изображения
│
├── vendor/                 # Composer dependencies
│   └── phpmailer/         # PHPMailer библиотека
│
├── admin/                  # Публични страници
│   ├── index.php          # Главен контролер
│   ├── index_public.php   # Публична landing страница
│   ├── login.php          # Login страница
│   ├── logout.php         # Logout скрипт
│   ├── faq.php            # FAQ страница
│   └── api.php            # API endpoints
│
├── docker-compose.yml      # Docker Compose конфигурация
├── Dockerfile              # Docker image конфигурация
├── composer.json           # Composer зависимости
├── database.sql            # Database schema
├── CHANGELOG.md            # История на промените
└── README.md               # Този файл

---

🚀 Инсталация

Изисквания

• PHP 8.1 или по-нова версия
• MySQL/MariaDB 10.3+
• Composer
• Docker и Docker Compose (опционално)

PHP Extensions

• pdo_mysql - Database connection
• mbstring - String manipulation
• curl - HTTP requests
• gd - Image processing
• openssl - Encryption
• zip - Archive handling
• json - JSON support
• session - Session management

Стъпка 1: Клониране на репозитория

git clone https://git.vi-lab.eu/orion/shivik.git
cd shivik

Стъпка 2: Инсталация на зависимости

composer install

Стъпка 3: Конфигурация

1. Копирай config/db.php.example към config/db.php (ако съществува)
2. Редактирай config/db.php с твоите database credentials:

return [
    'host' => 'localhost',
    'dbname' => 'game_faucet',
    'username' => 'your_username',
    'password' => 'your_password',
    'charset' => 'utf8mb4',
    'options' => [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
    ],
];

3. Редактирай config/config.php за основните настройки (SITE_NAME, BASE_URL, и т.н.)

Стъпка 4: Database Setup

1. Създай MySQL database:

CREATE DATABASE game_faucet CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

2. Импортирай schema:

mysql -u your_username -p game_faucet < database.sql

3. Изпълни миграции (ако има):

php run_migration.php

4. Попълни начални данни:

php seed_default_settings.php
php setup_admin.php  # Създава административен акаунт
php setup_menu_extended.php  # Попълва менюто

Стъпка 5: Permissions

Увери се, че следните директории са записваеми:

chmod -R 755 uploads/
chmod -R 755 sessions/
chmod -R 755 cache/  # Ако съществува

Стъпка 6: Web Server Configuration

Apache

Създай virtual host:

<VirtualHost *:80>
    ServerName game.local
    DocumentRoot /path/to/shivik
    
    <Directory /path/to/shivik>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

Nginx

server {
    listen 80;
    server_name game.local;
    root /path/to/shivik;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

Стъпка 7: Cron Jobs

Добави в crontab за автоматично разпределение на награди:

*/5 * * * * /usr/bin/php /path/to/shivik/cron/rewards.php

---

🐳 Docker Инсталация

Бърз Старт с Docker

# Клонирай репозитория
git clone https://git.vi-lab.eu/orion/shivik.git
cd shivik

# Стартирай контейнерите
docker-compose up -d

# Инсталирай зависимости
docker-compose exec web composer install

# Настрой database (в друг терминал)
docker-compose exec db mysql -u root -proot_pass -e "CREATE DATABASE IF NOT EXISTS faucet_db;"

# Импортирай schema
docker-compose exec -T db mysql -u root -proot_pass faucet_db < database.sql

# Попълни начални данни
docker-compose exec web php seed_default_settings.php
docker-compose exec web php setup_admin.php
docker-compose exec web php setup_menu_extended.php

Доступ

• Web: http://localhost:8008
• Admin Panel: http://localhost:8008/admin/
• Database: localhost:3307 (user: root, password: root_pass)

---

📖 Документация

Основни Документи

• INSTALL.md - Детайлна инструкция за инсталация
• DATABASE.md - Database schema документация
• ADMIN_GUIDE.md - Ръководство за админ панела
• CHANGELOG.md - История на промените
• DOCKER.md - Docker документация
• API_DOCUMENTATION.md - REST API ръководство
• VERSION_SUMMARY.md - Обобщение на версии 1.1-1.5
• QUICK_START_ROOM_SYSTEM.md - Бърз старт за Room System
• docs/ROOM_SYSTEM.md - Пълна документация за Room → Rack → Miners система
• docs/ECONOMY.md - Икономически модел

API Документация

API endpoints са достъпни на /api.php. Виж файла за детайли.

---

🔐 Сигурност

Имплементирани Мерки

• ✅ CSRF Protection - Всички форми използват CSRF токени
• ✅ Prepared Statements - Всички database заявки използват prepared statements
• ✅ XSS Protection - Output escaping с e() функция
• ✅ Role-based Access Control - Гранулиран контрол на достъпа (Extended RBAC)
• ✅ Session Security - HttpOnly cookies, secure session management
• ✅ Password Hashing - password_hash() с PASSWORD_DEFAULT
• ✅ Directory Protection - .htaccess защита на чувствителни директории
• ✅ Input Validation - Валидация на всички потребителски входове
• ✅ 2FA - Two-factor authentication за админ акаунти
• ✅ Security Headers - CSP, X-Frame-Options, HSTS, X-XSS-Protection
• ✅ Rate Limiting - Защита срещу abuse и DDoS атаки
• ✅ Content Security Policy - CSP headers за XSS защита

Препоръки

• Използвай HTTPS в production
• Регулярно обновявай паролите
• Мониторирай Security Events в админ панела
• Настрой правилно firewall правила
• Редовно прав backup на database

---

🧪 Тестване

Функционални Тестове

# Тест на database connection
php test_system.sh

# Тест на локална инсталация
php test_local.sh

Manual Testing Checklist

• Login/Logout функционалност
• User registration
• Admin panel достъп
• CRUD операции за всички модули
• Email система (test email)
• Social login настройки
• Settings запазване
• Analytics данни
• Payment транзакции

---

📊 Административен Панел

Модули (30+)

👥 Users & Accounts

• Users (с онлайн статус)
• User Roles
• Referrals
• Bans & Suspicious

🎮 Game Elements

• Cryptocurrencies
• Room Templates
• User Rooms
• Rack Types
• Miner Types
• User Miners
• Tasks & Achievements

🛡️ Security & Anti-Cheat

• Anti-Cheat Rules
• Security Events
• Ban Review Queue

📊 Analytics

• Player Analytics (DAU/WAU/MAU)
• Economy Analytics
• Room & Miner Analytics

💰 Economy & Rewards

• Faucet Settings
• Reward Logs
• Profitability Dashboard
• Exchange Rates

💳 Finance

• Payments (Deposits & Withdrawals)
• Payment Providers
• Promo Codes

🎧 Support & Community

• Support Tickets
• News & Announcements

📧 Content & Communication

• Email Settings
• Email Templates
• Social Login Settings

⚙️ System & Logs

• General Settings (54+ настройки)
• Feature Flags
• Config History
• Admin Activity Logs
• Audit Exports
• Changelog

---

🔧 Конфигурация

Основни Настройки

Настройките са организирани в 7 категории:

1. General - Основни настройки (site name, timezone, language)
2. Login & Registration - Настройки за вход и регистрация
3. User - Потребителски настройки
4. Security & Anti-Cheat - Сигурност и anti-cheat правила
5. Game & Economy - Игрова механика и икономика
6. Notifications - Настройки за известия
7. Other/Content/Filters - Други настройки

Достъп: Admin → System → General Settings

Email Конфигурация

1. Отиди на Admin → Content & Communication → Email Settings
2. Избери email server (PHP Mail или SMTP)
3. Конфигурирай SMTP настройки (ако използваш SMTP)
4. Тествай email доставката

Social Login

1. Отиди на Admin → Content & Communication → Social Login Settings
2. Включи желаните платформи
3. Добави OAuth credentials (Client ID, Client Secret)
4. Redirect URLs се генерират автоматично

---

🐛 Отстраняване на Проблеми

Често Срещани Проблеми

Database Connection Error

• Провери config/db.php credentials
• Увери се, че MySQL service работи
• Провери firewall правила

Permission Denied

• Провери permissions на uploads/ и sessions/
• Увери се, че web server user има достъп

Session Issues

• Провери sessions/ директория permissions
• Провери PHP session настройки в php.ini

Email Not Sending

• Провери SMTP credentials (ако използваш SMTP)
• Провери server firewall (порт 587/465)
• Тествай с "Debug Email Deliverability" в Email Settings

403 Forbidden

• Провери .htaccess файлове
• Провери web server configuration
• Провери file permissions

---

📝 Changelog

Виж CHANGELOG.md за пълна история на промените.

Версия 1.5.0 (Текуща)

• ✅ Room → Rack → Miners система (RollerCoin-like)
• ✅ Hashrate calculation с бонуси
• ✅ Events & Logs система
• ✅ Support Tickets система
• ✅ Room Editor UI с drag & drop
• ✅ 5 нови Admin панела
• ✅ 9 нови API endpoints
• ✅ Cron rewards актуализиран

Версия 1.4.0

• ✅ 2FA за admin акаунти
• ✅ Security headers (CSP, HSTS)
• ✅ Rate limiting
• ✅ Backup & Recovery скриптове
• ✅ Legal Pages управление
• ✅ System Status страница

Версия 1.3.0

• ✅ Offerwall интеграции
• ✅ Real-time UI елементи
• ✅ Notifications система
• ✅ Extended RBAC

Версия 1.2.0

• ✅ Seasons & Events
• ✅ Missions System
• ✅ Login Streak
• ✅ Guilds/Teams
• ✅ Dual Currency

Версия 1.1.0

• ✅ Repository & Service слой
• ✅ REST API v1
• ✅ PHPUnit тестове
• ✅ CI/CD Pipeline
• ✅ .env конфигурация

Версия 1.0.0

• ✅ Пълен административен панел с 30+ модула
• ✅ Categorized Settings система
• ✅ Email система с PHPMailer
• ✅ Social Login настройки
• ✅ Публична landing страница
• ✅ Online статус за потребители
• ✅ Security & Anti-Cheat модули
• ✅ Analytics и отчети
• ✅ Docker поддръжка

---

👨‍💻 Разработчик

Живко Георгиев
Разработчик в Vi Team Security Group

---

📄 Лиценз

Proprietary - All rights reserved

Този софтуер и свързаната документация са собственост на разработчика. Всяко неоторизирано копиране, разпространение или използване е забранено.

---

🤝 Поддръжка

За въпроси, проблеми или предложения, моля свържи се с разработчика.

---

🔗 Полезни Линкове

• Git Repository: https://git.vi-lab.eu/orion/shivik
• FAQ: /faq.php (публична страница)
• Changelog: /admin/changelog.php (админ панел)

---

Последна актуализация: 2024