# Wheel of Fortune - WordPress Plugin

Vtičnik "Kolo Sreče" (Wheel of Fortune) omogoča uporabnikom vrtenje kolesa za nagrade. Povezan je z WooCommerce za dodeljevanje spinov ob nakupu izdelkov.

## Funkcionalnosti

- Prikaz interaktivnega kolesa sreče preko kratke kode [wheel_of_fortune]
- Povezava z WooCommerce za dodeljevanje spinov ob nakupu izdelkov
- Upravljanje z nagradami, verjetnostmi in barvami
- Statistika vrtljajev in zadetkov

## Namestitev

1. Prenesite datoteke vtičnika v mapo `/wp-content/plugins/wheel-of-fortune/`
2. Aktivirajte vtičnik preko menija 'Vtičniki' v WordPress skrbniški plošči
3. Nastavite vtičnik preko menija 'Kolo sreče' v skrbniški plošči

## Uporaba

### Osnovna uporaba

Vstavite kratko kodo `[wheel_of_fortune]` na katerokoli stran ali prispevek, kjer želite prikazati kolo sreče.

### Parametri kratke kode

Kratka koda sprejme naslednje parametre:

- `size`: Velikost kolesa (možnosti: `small`, `medium`, `large`, privzeto: `medium`)
- `theme`: Tema kolesa (možnosti: `light`, `dark`, privzeto: `light`)
- `scale`: Dodatno prilagajanje velikosti (možnosti: `scale-90`, `scale-80`, `scale-70`, `scale-60`, `scale-50`, privzeto: prazen)

#### Primeri

```
[wheel_of_fortune]
[wheel_of_fortune size="large" theme="dark"]
[wheel_of_fortune size="medium" theme="light" scale="scale-80"]
```

## Vsebina
1. [Namen vtičnika](#namen-vtičnika)
2. [Ključne funkcionalnosti](#ključne-funkcionalnosti)
3. [Tehnični opis](#tehnični-opis)
4. [Logika delovanja](#logika-delovanja)
5. [Administratorske nastavitve](#administratorske-nastavitve)
6. [Kratka koda](#kratka-koda)
7. [Varnost in integracije](#varnost-in-integracije)
8. [Možne razširitve](#možne-razširitve)
9. [Implementacija kolesa](#implementacija-kolesa)
10. [Namestitev in uporaba](#namestitev-in-uporaba)

## Namen vtičnika

Vtičnik »Kolo Sreče« omogoča obiskovalcem spletne strani, da zavrtijo interaktivno kolo in prejmejo naključno nagrado. Vrtljaji so vezani na nakupe določenih izdelkov in uporabniške račune, kar omogoča gamificirano izkušnjo zvestobe in nagrajevanja.

## Ključne funkcionalnosti

- 🎯 Naključni izbor nagrade ob vrtenju kolesa
- 🔐 Vezava spinov (vrtljajev) na uporabniški račun
- 🛒 Samodejna dodelitev spinov ob nakupu določenih izdelkov
- 🧠 Nastavljive nagrade in verjetnosti zadetkov
- 📊 Spremljanje števila preostalih spinov
- 🎛️ Kratka koda za vključitev kolesa kjerkoli v WordPress vsebino
- 📬 Email obvestila ob zadetkih (opcijsko)
- 📈 Administratorska statistika: število zadetkov, porabljenih spinov ipd.

## Tehnični opis

### Arhitektura
- WordPress Plugin: zgrajen po WordPress standardih (object-oriented, namespacing, varnostni hooki)
- Frontend: JavaScript za animacijo kolesa, AJAX za komunikacijo z backendom
- Backend: PHP (WP REST API), povezano z WP uporabniki in WooCommerce naročili
- Baza podatkov: uporaba wp_usermeta, lastne tabele wp_wheel_spins in wp_wheel_prizes

### Tabele podatkovne baze

#### wp_wheel_spins

| Polje | Tip | Opis |
|-------|-----|------|
| id | INT | Primarni ključ |
| user_id | INT | ID uporabnika (WordPress) |
| spins_available | INT | Število razpoložljivih spinov |
| last_spin_date | DATETIME | Datum zadnjega vrtenja |

#### wp_wheel_prizes

| Polje | Tip | Opis |
|-------|-----|------|
| id | INT | Primarni ključ |
| name | VARCHAR(255) | Ime nagrade |
| description | TEXT | Opis nagrade |
| probability | FLOAT | Verjetnost zadetka (0-1) |
| color | VARCHAR(20) | Barva segmenta (HEX ali RGB) |
| is_active | TINYINT | Ali je nagrada aktivna |
| image_url | VARCHAR(255) | URL do slike nagrade (opcijsko) |

#### wp_wheel_log

| Polje | Tip | Opis |
|-------|-----|------|
| id | INT | Primarni ključ |
| user_id | INT | ID uporabnika |
| prize_id | INT | ID zadete nagrade |
| spin_date | DATETIME | Datum in čas vrtenja |
| redeemed | TINYINT | Ali je nagrada unovčena |

## Logika delovanja

### Podeljevanje spinov

Ob zaključenem nakupu določenega izdelka (npr. ID = 123), WooCommerce hook (woocommerce_order_status_completed) sproži funkcijo za dodelitev spinov.

```php
function assign_spins_on_purchase($order_id) {
  $order = wc_get_order($order_id);
  foreach ($order->get_items() as $item) {
    $product_id = $item->get_product_id();
    $spin_products = get_option('wheel_spin_products', array());
    
    if (array_key_exists($product_id, $spin_products)) {
      $user_id = $order->get_user_id();
      $current_spins = get_user_meta($user_id, '_wheel_spins', true) ?: 0;
      $new_spins = $current_spins + $spin_products[$product_id];
      update_user_meta($user_id, '_wheel_spins', $new_spins);
      
      // Posodobi tudi v tabeli wp_wheel_spins
      global $wpdb;
      $table_name = $wpdb->prefix . 'wheel_spins';
      
      $existing = $wpdb->get_var($wpdb->prepare(
        "SELECT id FROM $table_name WHERE user_id = %d",
        $user_id
      ));
      
      if ($existing) {
        $wpdb->update(
          $table_name,
          array('spins_available' => $new_spins),
          array('user_id' => $user_id)
        );
      } else {
        $wpdb->insert(
          $table_name,
          array(
            'user_id' => $user_id,
            'spins_available' => $new_spins,
            'last_spin_date' => current_time('mysql')
          )
        );
      }
    }
  }
}
add_action('woocommerce_order_status_completed', 'assign_spins_on_purchase');
```

### Vrtenje kolesa

1. Uporabnik klikne gumb "Zavrti"
2. JS animira kolo (CSS transformacija)
3. Medtem AJAX zahteva iz strežnika rezultat
4. PHP backend izbere nagrado glede na verjetnosti
5. Backend zabeleži zadetek, zmanjša število spinov

```php
// REST API endpoint za vrtenje kolesa
function spin_wheel_endpoint() {
  register_rest_route('wheel-of-fortune/v1', '/spin', array(
    'methods' => 'POST',
    'callback' => 'process_wheel_spin',
    'permission_callback' => function() {
      return is_user_logged_in();
    }
  ));
}
add_action('rest_api_init', 'spin_wheel_endpoint');

function process_wheel_spin($request) {
  $user_id = get_current_user_id();
  $spins = get_user_meta($user_id, '_wheel_spins', true) ?: 0;
  
  if ($spins <= 0) {
    return new WP_Error('no_spins', 'Nimate več razpoložljivih vrtljajev', array('status' => 403));
  }
  
  // Preveri časovni interval med vrtljaji
  global $wpdb;
  $table_name = $wpdb->prefix . 'wheel_spins';
  $last_spin = $wpdb->get_var($wpdb->prepare(
    "SELECT last_spin_date FROM $table_name WHERE user_id = %d",
    $user_id
  ));
  
  $cooldown_minutes = get_option('wheel_cooldown_minutes', 0);
  if ($cooldown_minutes > 0 && $last_spin) {
    $time_diff = (strtotime(current_time('mysql')) - strtotime($last_spin)) / 60;
    if ($time_diff < $cooldown_minutes) {
      return new WP_Error(
        'cooldown', 
        sprintf('Počakajte še %d minut pred naslednjim vrtenjem', ceil($cooldown_minutes - $time_diff)),
        array('status' => 403)
      );
    }
  }
  
  // Izberi nagrado glede na verjetnosti
  $prize = select_random_prize($prizes);
  
  // Posodobi število spinov
  update_user_meta($user_id, '_wheel_spins', $spins - 1);
  
  // Posodobi tabelo wp_wheel_spins
  $wpdb->update(
    $table_name,
    array(
      'spins_available' => $spins - 1,
      'last_spin_date' => current_time('mysql')
    ),
    array('user_id' => $user_id)
  );
  
  // Zabeleži zadetek
  $log_table = $wpdb->prefix . 'wheel_log';
  $wpdb->insert(
    $log_table,
    array(
      'user_id' => $user_id,
      'prize_id' => $prize['id'],
      'spin_date' => current_time('mysql'),
      'redeemed' => 0
    )
  );
  
  // Pošlji email obvestilo (če je vključeno)
  if (get_option('wheel_send_emails', false)) {
    send_prize_email($user_id, $prize);
  }
  
  return array(
    'success' => true,
    'prize' => $prize,
    'remaining_spins' => $spins - 1,
    'degree' => calculate_prize_degree($prize['id'], $prizes)
  );
}

function calculate_prize_degree($prize_id, $prizes) {
  // Izračunaj stopinje za animacijo kolesa
  $prize_index = 0;
  foreach ($prizes as $index => $prize) {
    if ($prize['id'] == $prize_id) {
      $prize_index = $index;
      break;
    }
  }
  
  $segment_size = 360 / count($prizes);
  $degree = 360 - ($prize_index * $segment_size + $segment_size / 2);
  // Dodaj naključno odstopanje znotraj segmenta
  $degree += mt_rand(-($segment_size / 4), $segment_size / 4);
  // Dodaj še nekaj obratov
  $degree += 360 * 5;
  
  return $degree;
}
```

## Administratorske nastavitve

- 📦 Seznam izdelkov, ki podeljujejo spin (ID + št. spinov)
- 🎁 Nastavitev nagrad (ime, opis, slika, verjetnost, barva)
- 🗳️ Max. spinov na uporabnika
- 🕒 Časovna omejitev (1 spin na X minut)
- 🔧 Reset spinov / bonus kampanje
- 📧 Nastavitve email obvestil

```php
function wheel_admin_menu() {
  add_menu_page(
    'Kolo Sreče',
    'Kolo Sreče',
    'manage_options',
    'wheel-of-fortune',
    'wheel_settings_page',
    'dashicons-marker',
    30
  );
  
  add_submenu_page(
    'wheel-of-fortune',
    'Nastavitve',
    'Nastavitve',
    'manage_options',
    'wheel-of-fortune',
    'wheel_settings_page'
  );
  
  add_submenu_page(
    'wheel-of-fortune',
    'Nagrade',
    'Nagrade',
    'manage_options',
    'wheel-prizes',
    'wheel_prizes_page'
  );
  
  add_submenu_page(
    'wheel-of-fortune',
    'Statistika',
    'Statistika',
    'manage_options',
    'wheel-stats',
    'wheel_stats_page'
  );
}
add_action('admin_menu', 'wheel_admin_menu');
```

## Kratka koda

Kolo lahko prikažemo kjerkoli s pomočjo:

```
[wheel_of_fortune]
```

Možne opcije:

```
[wheel_of_fortune size="large" theme="dark"]
```

Implementacija kratke kode:

```php
function wheel_shortcode($atts) {
  $atts = shortcode_atts(array(
    'size' => 'medium', // small, medium, large
    'theme' => 'light', // light, dark
  ), $atts);
  
  // Preveri, če je uporabnik prijavljen
  if (!is_user_logged_in()) {
    return '<div class="wheel-login-required">Za sodelovanje v nagradni igri se morate <a href="' . wp_login_url(get_permalink()) . '">prijaviti</a>.</div>';
  }
  
  // Preveri, če ima uporabnik na voljo spine
  $user_id = get_current_user_id();
  $spins = get_user_meta($user_id, '_wheel_spins', true) ?: 0;
  
  if ($spins <= 0) {
    return '<div class="wheel-no-spins">Trenutno nimate razpoložljivih vrtljajev. Kupite izdelke za pridobitev novih vrtljajev.</div>';
  }
  
  // Naloži potrebne skripte in stile
  wp_enqueue_style('wheel-of-fortune-css', plugin_dir_url(__FILE__) . 'assets/css/wheel.css');
  wp_enqueue_script('wheel-of-fortune-js', plugin_dir_url(__FILE__) . 'assets/js/wheel.js', array('jquery'), '1.0', true);
  
  wp_localize_script('wheel-of-fortune-js', 'wheelSettings', array(
    'ajaxUrl' => rest_url('wheel-of-fortune/v1/spin'),
    'nonce' => wp_create_nonce('wp_rest'),
    'prizes' => get_wheel_prizes(),
    'remainingSpins' => $spins
  ));
  
  // Vrni HTML za kolo
  ob_start();
  include plugin_dir_path(__FILE__) . 'templates/wheel.php';
  return ob_get_clean();
}
add_shortcode('wheel_of_fortune', 'wheel_shortcode');
```

## Varnost in integracije

- CSRF zaščita za AJAX klice (WordPress nonce)
- Preverjanje uporabniške prijave
- Integracija z WooCommerce
- Možna integracija z emailing sistemom (npr. MailPoet, Sendinblue)
- Preverjanje vlog in pravic uporabnikov
- Sanitizacija vnosov in validacija podatkov

## Možne razširitve

- 🎟️ Shranjevanje zgodovine zadetkov (WP tabelo wp_wheel_log)
- 🏆 Leaderboard: največ zadetkov / spinov
- 🔗 Integracija z zvestobnim sistemom (CLIP)
- 📱 Mobilna verzija (PWA)
- 🔔 Push obvestila za bonus spin
- 📊 Napredna analitika in poročila
- 🌐 Večjezična podpora

## Implementacija kolesa

Glede na priloženo sliko, bo kolo implementirano kot interaktivna SVG ali Canvas komponenta z naslednjimi lastnostmi:

### Struktura kolesa
- Kolo je razdeljeno na več segmentov (8-12)
- Vsak segment ima svojo barvo (modra, rdeča, siva)
- Segmenti vsebujejo besedilo z nagrado
- Kazalec na vrhu označuje zmagovalni segment

### CSS in JS implementacija

```css
.wheel-container {
  position: relative;
  width: 100%;
  max-width: 500px;
  margin: 0 auto;
}

.wheel {
  width: 100%;
  height: auto;
  transform-origin: center;
  transition: transform 5s cubic-bezier(0.17, 0.67, 0.83, 0.67);
}

.wheel-pointer {
  position: absolute;
  top: 0;
  left: 50%;
  transform: translateX(-50%);
  width: 40px;
  height: 40px;
  z-index: 10;
}

.wheel-segment {
  transform-origin: center;
}

.wheel-segment-blue {
  fill: #5DADE2;
}

.wheel-segment-red {
  fill: #E74C3C;
}

.wheel-segment-gray {
  fill: #D5D8DC;
}

.wheel-text {
  font-family: Arial, sans-serif;
  font-size: 14px;
  font-weight: bold;
  fill: white;
  text-anchor: middle;
}

.wheel-button {
  display: block;
  margin: 20px auto;
  padding: 10px 20px;
  background-color: #E74C3C;
  color: white;
  border: none;
  border-radius: 5px;
  font-size: 16px;
  cursor: pointer;
}

.wheel-button:disabled {
  background-color: #D5D8DC;
  cursor: not-allowed;
}

.wheel-spins-counter {
  text-align: center;
  margin-top: 10px;
  font-size: 16px;
}

.wheel-result {
  text-align: center;
  margin-top: 20px;
  padding: 15px;
  border-radius: 5px;
  display: none;
}

.wheel-result.win {
  background-color: #D5F5E3;
  border: 1px solid #2ECC71;
}
```

```javascript
jQuery(document).ready(function($) {
  var wheel = $('.wheel');
  var button = $('.wheel-button');
  var result = $('.wheel-result');
  var spinning = false;
  
  button.on('click', function() {
    if (spinning) return;
    
    spinning = true;
    button.prop('disabled', true);
    result.hide();
    
    $.ajax({
      url: wheelSettings.ajaxUrl,
      method: 'POST',
      beforeSend: function(xhr) {
        xhr.setRequestHeader('X-WP-Nonce', wheelSettings.nonce);
      },
      success: function(response) {
        if (response.success) {
          // Animiraj kolo
          wheel.css({
            'transform': 'rotate(' + response.degree + 'deg)'
          });
          
          // Posodobi števec spinov
          $('.wheel-spins-counter span').text(response.remaining_spins);
          
          // Prikaži rezultat po končani animaciji
          setTimeout(function() {
            result.html('<h3>Čestitamo!</h3><p>Zadeli ste: ' + response.prize.name + '</p>');
            result.addClass('win').show();
            spinning = false;
            
            if (response.remaining_spins > 0) {
              button.prop('disabled', false);
            }
          }, 5500);
        }
      },
      error: function(xhr) {
        var errorMsg = 'Prišlo je do napake.';
        if (xhr.responseJSON && xhr.responseJSON.message) {
          errorMsg = xhr.responseJSON.message;
        }
        
        result.html('<p>' + errorMsg + '</p>');
        result.removeClass('win').show();
        spinning = false;
        button.prop('disabled', false);
      }
    });
  });
});
```

### SVG implementacija kolesa

```php
function generate_wheel_svg($prizes) {
  $num_prizes = count($prizes);
  $angle = 360 / $num_prizes;
  $svg = '<svg viewBox="0 0 500 500" class="wheel">';
  
  // Center point
  $cx = 250;
  $cy = 250;
  $radius = 240;
  
  // Generate segments
  for ($i = 0; $i < $num_prizes; $i++) {
    $prize = $prizes[$i];
    $start_angle = $i * $angle;
    $end_angle = ($i + 1) * $angle;
    
    $start_rad = deg2rad($start_angle);
    $end_rad = deg2rad($end_angle);
    
    $x1 = $cx + $radius * cos($start_rad);
    $y1 = $cy + $radius * sin($start_rad);
    $x2 = $cx + $radius * cos($end_rad);
    $y2 = $cy + $radius * sin($end_rad);
    
    // Determine if the arc should be drawn as a large arc
    $large_arc = $end_angle - $start_angle > 180 ? 1 : 0;
    
    // Create the path for the segment
    $path = "M{$cx},{$cy} L{$x1},{$y1} A{$radius},{$radius} 0 {$large_arc},1 {$x2},{$y2} Z";
    
    // Determine the color class
    $color_class = '';
    switch ($prize['color']) {
      case 'blue':
        $color_class = 'wheel-segment-blue';
        break;
      case 'red':
        $color_class = 'wheel-segment-red';
        break;
      default:
        $color_class = 'wheel-segment-gray';
    }
    
    $svg .= "<path d='{$path}' class='wheel-segment {$color_class}' />";
    
    // Add text to the segment
    $text_angle = $start_angle + ($angle / 2);
    $text_rad = deg2rad($text_angle);
    $text_x = $cx + ($radius * 0.75) * cos($text_rad);
    $text_y = $cy + ($radius * 0.75) * sin($text_rad);
    
    // Rotate text to be readable
    $text_rotate = $text_angle;
    if ($text_angle > 90 && $text_angle < 270) {
      $text_rotate += 180;
    }
    
    $svg .= "<text x='{$text_x}' y='{$text_y}' class='wheel-text' transform='rotate({$text_rotate}, {$text_x}, {$text_y})'>{$prize['name']}</text>";
  }
  
  // Add center circle
  $svg .= "<circle cx='{$cx}' cy='{$cy}' r='50' fill='white' />";
  
  $svg .= '</svg>';
  return $svg;
}
```

## Namestitev in uporaba

### Namestitev vtičnika

1. Prenesite ZIP datoteko vtičnika
2. V WordPress administratorski plošči pojdite na "Vtičniki" > "Dodaj nov"
3. Kliknite "Naloži vtičnik" in izberite preneseno ZIP datoteko
4. Aktivirajte vtičnik

### Konfiguracija

1. V administratorski plošči pojdite na "Kolo Sreče" > "Nastavitve"
2. Konfigurirajte izdelke, ki podeljujejo spine
3. Nastavite časovne omejitve in druge možnosti

### Dodajanje nagrad

1. Pojdite na "Kolo Sreče" > "Nagrade"
2. Dodajte nove nagrade z imenom, opisom, verjetnostjo in barvo
3. Zagotovite, da skupna vsota verjetnosti ne presega 1.0

### Prikaz kolesa na strani

Dodajte kratko kodo `[wheel_of_fortune]` na želeno stran ali prispevek.

Za prilagoditev videza uporabite dodatne parametre:
```
[wheel_of_fortune size="large" theme="dark"]
```

### Prilagajanje velikosti kolesa

Če želite dodatno prilagoditi velikost kolesa, da bo vse prišlo na zaslon, lahko uporabite parameter `scale`:

- `scale-90`: Zmanjša kolo na 90% privzete velikosti
- `scale-80`: Zmanjša kolo na 80% privzete velikosti
- `scale-70`: Zmanjša kolo na 70% privzete velikosti
- `scale-60`: Zmanjša kolo na 60% privzete velikosti
- `scale-50`: Zmanjša kolo na 50% privzete velikosti

Primer: `[wheel_of_fortune scale="scale-70"]`

### Dodeljevanje spinov uporabnikom

Spine lahko uporabnikom dodelite na naslednje načine:

1. **Avtomatsko ob nakupu**: Nastavite število spinov za posamezne izdelke v nastavitvah vtičnika
2. **Ročno**: Uporabite stran "Uporabniki" v meniju "Kolo sreče" za ročno dodeljevanje spinov

## Nastavitve

### Splošne nastavitve

- **Zahtevaj prijavo**: Če je omogočeno, morajo biti uporabniki prijavljeni za vrtenje kolesa
- **Dovoli samo en spin na dan**: Če je omogočeno, lahko uporabniki zavrtijo kolo samo enkrat na dan
- **Pošlji e-pošto ob zmagi**: Če je omogočeno, se uporabniku pošlje e-pošta ob zmagi

### Nagrade

Upravljajte z nagradami, ki jih lahko uporabniki zadanejo:

- **Ime**: Ime nagrade
- **Opis**: Opis nagrade
- **Verjetnost**: Verjetnost, da uporabnik zadane to nagrado (v odstotkih)
- **Barva**: Barva segmenta na kolesu
- **Aktivna**: Ali je nagrada aktivna

### Izdelki

Nastavite število spinov, ki jih uporabnik prejme ob nakupu določenih izdelkov:

1. Vnesite ID izdelka
2. Nastavite število spinov
3. Kliknite "Dodaj izdelek"

## Statistika

Spremljajte statistiko vrtljajev in zadetkov:

- **Skupno število vrtljajev**: Skupno število vrtljajev vseh uporabnikov
- **Zadetki po nagradah**: Število zadetkov za vsako nagrado
- **Uporabniki z največ vrtljaji**: Seznam uporabnikov z največ vrtljaji

## Razvijalcem

### Filtri

Vtičnik ponuja naslednje filtre za prilagajanje:

- `wheel_of_fortune_prizes`: Prilagodite seznam nagrad
- `wheel_of_fortune_spin_result`: Prilagodite rezultat vrtljaja
- `wheel_of_fortune_email_content`: Prilagodite vsebino e-pošte ob zmagi

### Akcije

Vtičnik ponuja naslednje akcije:

- `wheel_of_fortune_before_spin`: Izvede se pred vrtljajem
- `wheel_of_fortune_after_spin`: Izvede se po vrtljaju
- `wheel_of_fortune_prize_won`: Izvede se, ko uporabnik zadane nagrado

## Pogosta vprašanja

### Kolo se ne prikaže na strani

Preverite naslednje:

1. Ali je kratka koda pravilno vstavljena?
2. Ali so nagrade nastavljene in aktivne?
3. Ali je uporabnik prijavljen (če je to zahtevano)?
4. Ali ima uporabnik na voljo spine?
5. Poskusite zmanjšati velikost kolesa z uporabo parametra `scale`: `[wheel_of_fortune scale="scale-80"]`

### Uporabnik ne prejme spinov ob nakupu

Preverite naslednje:

1. Ali je WooCommerce aktiviran?
2. Ali je izdelek pravilno nastavljen v nastavitvah vtičnika?
3. Ali je naročilo označeno kot "Zaključeno"?

## Podpora

Za podporo nas kontaktirajte na support@example.com