154 lines
7.4 KiB
Markdown
154 lines
7.4 KiB
Markdown
# Wheel of Fortune za WooCommerce (Kolo Sreče)
|
|
|
|
**Wheel of Fortune** je napreden WordPress/WooCommerce vtičnik, ki omogoča gamifikacijo spletne trgovine. Kupcem omogoča, da z nakupom določenih izdelkov pridobijo "vrtljaje" (spins) in zavrtijo kolo sreče za priboritev nagrad (popusti, kuponi, fizična darila ali sporočila).
|
|
|
|
Vtičnik podpira več različnih koles, napredno upravljanje verjetnosti, samodejno ustvarjanje WooCommerce kuponov, pošiljanje e-poštnih obvestil (SMTP) in dnevne nagrade (Cron job).
|
|
|
|
## 🚀 Glavne funkcionalnosti
|
|
|
|
* **Več koles:** Ustvarite lahko neomejeno število različnih koles za različne priložnosti.
|
|
* **Povezava z WooCommerce:** Določite, kateri izdelki prinašajo vrtljaje in koliko.
|
|
* **Napredne nagrade:**
|
|
* Avtomatsko ustvarjanje kuponov za popuste (odstotni popust).
|
|
* Fizične nagrade.
|
|
* "Poskusi znova" (Try Again) polja.
|
|
* Nastavljanje verjetnosti dobitka (uteženo).
|
|
* **Uporabniški račun:** Beleženje zgodovine vrtljajev in preostalih vrtljajev za vsakega uporabnika.
|
|
* **Dnevni vrtljaji:** Možnost nastavitve, da vsak uporabnik prejme 1 brezplačen vrtljaj vsakih 24 ur.
|
|
* **E-poštna obvestila:** Integriran SMTP klient za zanesljivo pošiljanje obvestil o nagradah.
|
|
* **Diagnostika:** Orodje za testiranje generiranja kuponov in pošiljanja e-pošte.
|
|
|
|
---
|
|
|
|
## 📂 Struktura map in datotek
|
|
|
|
Spodaj je podroben opis vseh datotek v projektu in njihov namen.
|
|
|
|
### root (koren mape)
|
|
* **`wheel-of-fortune.php`**:
|
|
* Glavna datoteka vtičnika.
|
|
* Inicializira vtičnik, registrira 'hooks' (akcije in filtre).
|
|
* Ustvari in posodablja podatkovne baze (`dbDelta`).
|
|
* Registrira REST API endpoint (`/wp-json/wheel-of-fortune/v1/spin`) za varno izvedbo vrtljaja.
|
|
* Obravnava logiko dodeljevanja spinov ob zaključku WooCommerce naročila (`woocommerce_order_status_completed`).
|
|
* Vsebuje logiko za pošiljanje e-pošte in generiranje SVG kolesa.
|
|
|
|
### `/admin` (Administracija)
|
|
Vsebuje logiko za backend vmesnik v WP Adminu.
|
|
|
|
* **`coupon-test.php`**:
|
|
* Diagnostično orodje. Preizkusi 4 različne metode ustvarjanja WooCommerce kuponov (API, programsko, DB insert), da najde tisto, ki deluje na strežniku, in jo shrani kot privzeto.
|
|
* **`wheels-page.php`**:
|
|
* Prikazuje seznam vseh ustvarjenih koles.
|
|
* Omogoča dodajanje novih koles in brisanje obstoječih.
|
|
* **`edit-wheel-page.php`**:
|
|
* Glavni urejevalnik za posamezno kolo.
|
|
* Upravljanje nagrad (CRUD): dodajanje, urejanje, verjetnosti, barve, template e-pošte.
|
|
* Povezovanje WooCommerce izdelkov s tem kolesom (koliko spinov prinese izdelek).
|
|
* **`settings-page.php`**:
|
|
* Globalne nastavitve: SMTP podatki, Cron nastavitve za dnevne spine, "cooldown" čas.
|
|
* Vsebuje orodja za ročno dodajanje spinov in testiranje e-pošte.
|
|
* **`stats-page.php`**:
|
|
* Analitika: Kdo je vrtel, kaj je zadel, kdaj.
|
|
* Filtriranje uporabnikov glede na preostale spine.
|
|
* **`users-page.php`**:
|
|
* Pregled uporabnikov in njihovih spinov.
|
|
* Možnost ročnega resetiranja ali dodajanja spinov specifičnemu uporabniku.
|
|
* **`partials/prize-form-fields.php`**:
|
|
* HTML delček (partial) za obrazec nagrade, ki se uporablja pri dodajanju in urejanju, da se koda ne podvaja.
|
|
* **`js/admin.js`**:
|
|
* jQuery skripte za admin vmesnik (odpiranje modalov, AJAX klici za shranjevanje nagrad, testiranje e-pošte).
|
|
* **`js/wheel.js`** (Admin preview):
|
|
* Skripta za animacijo kolesa v predogledu v administraciji.
|
|
|
|
### `/assets` (Sredstva)
|
|
Datoteke, ki se nalagajo na frontend-u (in delno v adminu za stilizacijo).
|
|
|
|
* **`css/admin.css`**:
|
|
* Stili za WP Admin (kartice, tabele, gumbi, postavitev urejevalnika).
|
|
* **`css/wheel.css`**:
|
|
* CSS za izgled kolesa na spletni strani.
|
|
* Vsebuje animacije (utripanje lučk), senčenje (SVG filtri) in odzivnost (responsive design) za mobilne naprave.
|
|
* **`js/wheel.js`**:
|
|
* **Glavna frontend logika.**
|
|
* Komunicira z REST API-jem za pridobitev rezultata vrtljaja (rezultat se določi na strežniku, ne v brskalniku zaradi varnosti).
|
|
* Izvaja animacijo vrtenja (easing functions) in prikaže "popup" z rezultatom.
|
|
|
|
### `/languages`
|
|
* **`wheel-of-fortune.pot`**:
|
|
* Predloga za prevajanje vtičnika v druge jezike (npr. v slovenščino).
|
|
|
|
### `/public`
|
|
* **`shortcode-template.php`**:
|
|
* HTML predloga, ki se izpiše, ko na stran vstavite `[wheel_of_fortune]`. Vsebuje kontejner za SVG kolo in gumb za vrtenje.
|
|
|
|
### `/templates`
|
|
* **`wheel.php`**:
|
|
* Alternativna ali starejša PHP predloga za generiranje SVG strukture (gradienti, filtri).
|
|
* **`emails/default-prize-email.html`**:
|
|
* HTML predloga za e-poštno sporočilo, ki ga prejme uporabnik ob zadetku. Vsebuje "placeholders" kot so `{user_name}`, `{prize_name}`, itd.
|
|
|
|
---
|
|
|
|
## 🗄️ Podatkovna baza
|
|
|
|
Vtičnik ustvari naslednje tabele v bazi:
|
|
1. `wp_wof_wheels`: Seznam koles.
|
|
2. `wp_wheel_prizes`: Nagrade povezane s kolesi (verjetnost, tip nagrade).
|
|
3. `wp_wheel_spins`: Stanje spinov za vsakega uporabnika (ločeno po kolesih).
|
|
4. `wp_wheel_log`: Zgodovina vseh vrtljajev (log).
|
|
5. `wp_wheel_of_fortune_products`: Povezovalna tabela med WC izdelki in kolesi.
|
|
|
|
---
|
|
|
|
## 🛠️ Navodila za uporabo
|
|
|
|
### 1. Namestitev in Aktivacija
|
|
1. Naložite mapo `wheel-of-fortune` v mapo `wp-content/plugins/` ali namestite preko ZIP datoteke v WP Adminu.
|
|
2. Aktivirajte vtičnik. Ob aktivaciji se bodo ustvarile potrebne tabele.
|
|
|
|
### 2. Ustvarjanje Kolesa
|
|
1. Pojdite na **Wheels of Fortune > Wheels**.
|
|
2. Vnesite ime kolesa in kliknite "Add New Wheel".
|
|
3. Kliknite na ime kolesa ali "Edit" za urejanje.
|
|
|
|
### 3. Dodajanje Nagrad (Prizes)
|
|
V urejevalniku kolesa:
|
|
1. Kliknite "Add New Prize".
|
|
2. Izpolnite podatke:
|
|
* **Probability:** Verjetnost med 0 in 1 (npr. 0.1 je 10%). *Pomembno: Vsota vseh verjetnosti naj bo 1.*
|
|
* **Is Discount?:** Če označite, vpišite odstotek. Sistem bo avtomatsko generiral unikatno kodo kupona.
|
|
* **Is Try Again?:** Če uporabnik ne zadene ničesar, a lahko vrti ponovno.
|
|
3. Shranite nagrado.
|
|
|
|
### 4. Povezava z Izdelki (Kako do spinov?)
|
|
Na isti strani urejanja kolesa (spodaj):
|
|
1. V sekciji "Produkti & spini" izberite WooCommerce izdelek.
|
|
2. Določite "Število spinov na nakup" (npr. 1).
|
|
3. Kliknite "Dodaj". Ko kupec kupi ta izdelek (status naročila: Completed/Processing), bo prejel spine.
|
|
|
|
### 5. Prikaz na spletni strani
|
|
Na katerokoli stran ali prispevek dodajte shortcode:
|
|
```
|
|
[wheel_of_fortune id="1"]
|
|
```
|
|
*Zamenjajte `1` z ID-jem vašega kolesa.*
|
|
|
|
### 6. Nastavitve SMTP in Dnevni Spin
|
|
Pojdite na **Wheels of Fortune > Settings**:
|
|
* **SMTP:** Vnesite podatke vašega mail strežnika za zanesljivo dostavo nagrad.
|
|
* **Daily Spin:** Izberite kolo, ki se uporablja za dnevne nagrade. Uporabniki bodo avtomatsko prejeli 1 spin vsakih 24h za to kolo.
|
|
* **Coupon Test:** Če se kuponi ne generirajo, zaženite "Testiraj ustvarjanje kuponov" in shranite delujočo metodo.
|
|
|
|
---
|
|
|
|
## ⚠️ Pomembna opozorila
|
|
|
|
* **DEBUG mode:** V datoteki `wheel-of-fortune.php` je konstanta `WHEEL_OF_FORTUNE_DEBUG` nastavljena na `true`. Za produkcijo jo nastavite na `false`, da ne polnite `debug.log` datoteke.
|
|
* **Varnost:** Vtičnik uporablja "Nonce" preverjanje za vse AJAX in REST klice, zato je varen pred CSRF napadi.
|
|
* **Login:** Kolo se prikaže samo prijavljenim uporabnikom. Neprijavljeni vidijo obvestilo za prijavo.
|
|
|
|
---
|
|
|
|
**Avtor:** Mark Poljansek
|
|
**Verzija:** 1.0.1 |