Macoo.Fun – Dokumentace v1.2.0

Přehled

Macoo.Fun je součástí ekosystému Macooin.com, který se zaměřuje na propagaci prostřednictvím interaktivního systému žetonů a dalších herních prvků. V této aktualizaci jsme sloučili dvě funkce – Párování mincí a Moje mince – do jedné přehledné stránky (Moje mince).

Systém umožňuje dva způsoby zapojení:

  • Nákup náramků: Získání investičních mincí v hodnotě 1000 Kč
  • Plnění úkolů: Sbírání pozičních tokenů na mapě bez nutnosti nákupu

Co se změnilo

1. Sloučení funkce Párování do stránky Moje mince

  • Uživatel si zvolí až 3 mince (typu Investiční nebo Soutěžní) a klikne na „Sloučit vybrané mince“.
  • Po sloučení se z původních mincí stávají Sběratelské (nelze je již dále použít) a vznikne nová mince ve vyšší vrstvě (uživatel získává bonus).

2. Kontrola maximálně 3 mincí

  • Ošetřeno jak na frontendu (checkboxy nedovolí vybrat více než 3), tak na backendu (případné vyhození chyby)

3. Zobrazení dosažitelných vrstev

  • Při výběru mincí se uživateli dynamicky počítá celková hodnota a ukazuje se, na kterou vyšší vrstvu může dosáhnout.
  • Pokud uživatel potřebuje doplnit hodnotu, zobrazí se mu, kolik mu ještě chybí.

4. Přehled vrstev

  • Pod seznamem mincí je tabulka všech vrstev s uvedenou hodnotou, minimální hodnotou a možným bonusem (hodnota mínus minimální hodnota).
  • Tato tabulka je standardně sbalená (collapse); uživatel si ji může rozbalit, pokud ho detail zajímá.

5. Zachování ostatních funkcí

  • Stávající API zůstává prakticky beze změn
  • Původní stránka pro párování mincí (makecoin/) zůstává skryta a slouží jen pro interní testování

Registrace a účet

K čemu slouží registrace?

Bez registrace můžete:

  • Hledat poziční tokeny na mapě
  • Objevovat GPS pozice

S registrací získáte:

  • Možnost párování mincí
  • Přístup k odměnám a slevám
  • Možnost nákupu merche
  • Upozornění na novinky
  • Správu vašeho účtu

Proces registrace (běžný uživatel)

Požadované údaje:

  • Jméno
  • Email
  • Telefon
  • Heslo

Požadavky na heslo:

  • Musí obsahovat alespoň jedno číslo
  • Musí obsahovat alespoň jeden speciální znak (.-_*[]<>@#$%^&+=!?)
  1. Vyplnění registračního formuláře
  2. Odeslání aktivačního odkazu na zadaný email
  3. Kliknutí na aktivační odkaz pro ověření emailu
  4. Aktivace účtu
  5. Přihlášení do systému

Správa profilu

Možnosti úprav profilu:

  • Heslo
  • Jméno
  • Telefon

Informace v profilu:

  • Datum registrace
  • Datum posledního přihlášení

Administrátorská registrace uživatelů

Kromě klasického registračního formuláře pro veřejnost lze nové uživatele vytvářet přímo z administrace. Tato funkce je užitečná v případech, kdy je náramek už prodaný a je potřeba zaevidovat nového vlastníka (který zatím nemá účet).

  • Vyplní se jen jméno, email a (volitelně) telefon.
  • Heslo se může automaticky vygenerovat (nebo zadat ručně, dle potřeb projektu). Uživatel následně může využít funkci „Zapomenuté heslo“.
  • Neposílá se aktivační email. Účet se rovnou založí ve stavu aktivní (pokud takto definujete) nebo s minimálním nastavením dle vašich interních pravidel.

Příklad: Administrátor má informaci, že náramek s kódem 1W213ABC byl prodán zákazníkovi Jan Novák. Administrator otevře „Správa uživatelů“ → „Přidat uživatele“, vyplní jméno, email, telefon. Systém vygeneruje dočasné heslo a uživatele zapíše do tabulky uzivatele.

První kroky po přihlášení

  1. Zobrazení sekce "Moje mince"
    • Přehled všech nárokovaných mincí uživatele
    • Pokud si uživatel chce vyžádat heslo, použije reset – v emailu mu přijde odkaz.
  2. Propojení s náramky
    • Jakmile je účet vytvořen, náramek (bracelet) se dá spárovat s user_id → uživatel po přihlášení uvidí svůj náramek a k němu příslušnou fyzickou minci.

Struktura tabulky uzivatele

Základní tabulka pro ukládání uživatelských účtů. Může se ještě rozšiřovat o další sloupce (např. avatar, role apod.). Základní schéma:

Název sloupce Typ Popis
id INT (PK) Primární klíč
uuid CHAR(36) Unikátní identifikátor uživatele (např. generované UUID)
jmeno VARCHAR(100) Jméno uživatele
email VARCHAR(100) Emailová adresa (unikátní)
telefon VARCHAR(20) Telefon (volitelný)
heslo VARCHAR(255) Zahashované heslo (např. pomocí bcrypt)
aktivni TINYINT(1) Příznak, zda je účet aktivován (0/1)
datum_registrace DATETIME Datum a čas registrace (výchozí NOW())
opravneni TINYINT(1) Role uživatele (např. 1=Admin, 2=User)
registracni_ip VARCHAR(45) IP adresa při registraci
posledni_prihlaseni DATETIME Datum a čas posledního přihlášení
neuspesne_pokusy TINYINT(3) Počet neúspěšných pokusů o přihlášení
blokovan_do DATETIME Datum a čas dočasného blokování
aktivacni_token VARCHAR(64) Token pro emailovou aktivaci (může být NULL)
status ENUM('active','pending_deletion','deleted') Stav účtu (např. active, deleted)

Registrace a účet

K čemu slouží registrace?

Bez registrace můžete:

  • Hledat poziční tokeny na mapě
  • Objevovat GPS pozice

S registrací získáte:

  • Možnost párování mincí
  • Přístup k odměnám a slevám
  • Možnost nákupu merche
  • Upozornění na novinky
  • Správu vašeho účtu

Proces registrace

Požadované údaje:

  • Jméno
  • Email
  • Telefon
  • Heslo

Požadavky na heslo:

  • Musí obsahovat alespoň jedno číslo
  • Musí obsahovat alespoň jeden speciální znak (.-_*[]<>@#$%^&+=!?)
  1. Vyplnění registračního formuláře
  2. Odeslání aktivačního odkazu na zadaný email
  3. Kliknutí na aktivační odkaz pro ověření emailu
  4. Aktivace účtu
  5. Přihlášení do systému

Správa profilu

Možnosti úprav profilu:

  • Heslo
  • Jméno
  • Telefon

Informace v profilu:

  • Datum registrace
  • Datum posledního přihlášení

První kroky po přihlášení

  1. Zobrazení sekce "Moje mince"
    • Přehled všech vašich nárokovaných mincí
    • Pokud žádné mince nevidíte a vlastníte fyzickou minci, je potřeba ji nejprve nárokovat na https://macoo.fun/narokovani-mince/
  2. Možnosti práce s mincemi
    • Vystavení mince na Market pomocí tlačítka „Prodat“
    • Sbírání dalších mincí pro sloučení do vyšších vrstev

K čemu mince slouží?

Základní informace

Mince (fyzický žeton) lze získat především se zakoupením náramku na Macooin.com. Na přední straně mince je vygravírovaný unikátní kód, který slouží k ověření pravosti náramku. Každá nová (investiční) mince má základní hodnotu 1000 Kč.

Možnosti využití

  1. Uplatnění slevy na Macooin.com
    • S investiční nebo soutěžní mincí lze uplatnit slevu na vybraný produkt
    • Sleva může pokrýt až do výše hodnoty mince (1000 Kč, 3000 Kč, 9000 Kč apod.)
  2. Nákup merche a dalších produktů
    • Možnost nákupu triček, mikin, kšiltovek aj. podle dostupné nabídky
    • Při využití mince se odečte její hodnota a mince se stává Sběratelskou
  3. Výsadba stromů
    • Možnost využít minci k výsadbě stromů (1 strom = 200 Kč)
    • Uživatel obdrží certifikát potvrzující počet vysazených stromů
    • Mince se stává Sběratelskou po využití
  4. Investiční mince k dalšímu prodeji
    • Mince v hodnotě 1000+ Kč lze předat/prodat dalšímu zájemci (pouze jednou)
    • Prodej možný dohodou nebo přes Market
    • Po dokončení prodeje nelze tutéž minci znovu nabízet na Marketu

Důležité poznámky:

  • Mince nelze dělit, pouze slučovat do vyšších vrstev
  • Po využití se mince stává Sběratelskou a nelze ji dále používat k transakcím
  • Sběratelské mince zachovávají funkci ověření pravosti

Systém vrstev

Vrstva Hodnota vrstvy (Kč) Minimální hodnota pro převod (Kč) Bonus při převodu (Kč)
1 ≡ Kruh poznání 1 000 1 000 -
2 ≡ Kruh znalostí 3 000 2 250 750
3 ≡ Obruč moci 9 000 6 500 2 000
4 ≡ Kruh vládnutí 23 500 18 500 5 000
5 ≡ Prsten vznešenosti 85 000 70 500 14 500
6 ≡ Kruhový klenot 300 000 255 000 45 000
7 ≡ Eternia ≡ kruh moudrosti 1 000 000 900 000 100 000

Poziční tokeny (záporné vrstvy)

Vrstva Popis Hodnota (Kč) Min. hodnota (Kč)
≡ Grešle (-10) Grešle 10 10
≡ Fenik (-9) Fenik 25 25
≡ Groš (-8) Groš 50 50
≡ Tolar (-7) Tolar 100 100
≡ Dukát (-6) Dukát 150 150
≡ Zlaťák (-5) Zlaťák 200 200
≡ Dublón (-4) Dublón 250 250
≡ Průzkumník (-2) Průzkumník 500 500

Ukázkový scénář slučování

Uživatel má 2 mince po 1000 Kč a 1 minci 250 Kč.
Vrstva 2 (Kruh znalostí) vyžaduje minimální hodnotu 2250 Kč, ale má celkovou hodnotu 3000 Kč.
Jakmile spojí obě mince (2×1000) a jednu 250, dosáhne hodnoty 2250 Kč → dostane novou minci ve vrstvě 2 (3000 Kč), tj. 750 Kč bonus.
Původní mince jsou změněny na Sběratelské.

Nárokování mincí

Proces nárokování

  1. Ověření kódu mince
    • Zadání 8místného kódu mince (písmena a číslice)
    • Systém ověří existenci mince
    • Zobrazení základních údajů (hodnota, typ, současný vlastník)
  2. Ověření přes HASH (volitelné)
    • Pro mince s HASH: Zadání požadované části HASH kódu
    • Pro mince bez HASH: Ověření pomocí emailu spojeného s mincí
  3. Přihlášení / Registrace
    • Nutné být přihlášen pro dokončení nárokování
    • Nepřihlášení uživatelé budou vyzváni k přihlášení nebo registraci
  4. Dokončení nárokování
    • Zobrazení tlačítka „Nárokovat minci"
    • Přiřazení mince k uživatelskému účtu
    • Mince se stává nedostupnou pro ostatní uživatele

Bezpečnostní aspekty

  • Účel ověřování: Potvrzení pravosti a aktuálního stavu mince
  • Metody ověření:
    • Kontrolní kód u mincí z nákupu nebo směny
    • Email použitý při nákupu (pro mince z první série)
  • Bezpečnostní doporučení:
    • Nezobrazovat zadní stranu mince s ověřovacím kódem
    • Ověřovací proces vyžaduje pouze specifickou sekvenci kódu

Market

Co je Market?

Market je stránka, na níž mohou uživatelé nabídnout své fyzické mince (vrstvy 1–7, typ investiční/soutěžní) k prodeji ostatním. V ekosystému Macoo.Fun to umožňuje, aby si uživatelé mezi sebou předávali (prodávali) mince za individuálně dohodnutou cenu – avšak pouze jednou.

Proces prodeje na Marketu

  1. Nabídnutí mince k prodeji
    • Uživatel má minci ve stavu „volný“
    • V sekci Moje mince klikne na „Prodat“
    • Vyplní:
      • Požadovanou cenu
      • Platnost nabídky (např. 14 dní)
      • Poznámku k doručení
  2. Zpracování systémem
    • Nastavení stavu mince na market
    • Vytvoření záznamu v coin_transfer_requests se status='pending'
    • Blokace mince pro jiné operace
  3. Rezervace kupujícím
    • Kupující klikne na „Koupit“ a vyplní formulář
    • Status se změní na reserved
    • Domluva na fyzickém předání a platbě
  4. Dokončení převodu
    • Po fyzickém převzetí kupující zadá HASH kód
    • Systém změní status na completed
    • Převod mince na účet kupujícího

Praktický příklad prodeje

Máte minci v hodnotě 1000 Kč a chcete ji prodat za 500 Kč:

  1. Kupující vám zaplatí 500 Kč (individuální dohoda)
  2. Fyzicky předáte žeton
  3. Kupující se přihlásí do Macoo.Fun
  4. Zadá kód mince a úplný HASH
  5. Provede nárokování → mince se převede do jeho účtu
  6. Získává slevu 1000 Kč (pořízeno za 500 Kč)

Samotná dohoda a platba probíhá mezi uživateli. Macoo.Fun pouze poskytuje systém pro ověření kódu a bezpečný převod mince.

Důležitá omezení

  • Na Marketu lze nabízet pouze mince vrstvy 1–7 typu investiční/soutěžní
  • Každou minci lze prodat pouze jednou
  • Po prodeji nelze minci znovu nabídnout na Marketu
  • Kupující může minci využít na slevu nebo sloučení, ale ne další prodej

Certifikáty

V ekosystému Macoo.Fun může nastat situace, kdy je potřeba uchovávat doprovodné dokumenty nebo certifikáty související s mincemi, náramky a dalšími aktivitami. K tomu slouží modul pro nahrávání dokumentů.

Účel a využití

  • Potvrzení o pravosti – Ručně podepsané či jinak ověřené dokumenty mohou doprovázet vybrané mince nebo náramky a potvrzovat jejich pravost.
  • Sledování historie – Administrátor či uživatel může k danému kódu (např. kódu certifikátu) nahrát související PDF nebo obrázek s detailním vysvětlením, původem apod.
  • Nahrané dokumenty – V systému se ukládají v databázi (tabulka docs) s informacemi o názvu, kódu certifikátu a názvem souboru v úložišti.

Struktura a nahrávání

Tabulka docs obsahuje například tyto sloupce:

Název sloupce Typ Popis
id INT Primární klíč
title VARCHAR(150) Název dokumentu
certificate_code VARCHAR(100) Kód certifikátu (např. pro spárování s náramkem)
filename VARCHAR(255) Název souboru uloženého na disku
created_at / updated_at DATETIME Datum vytvoření a poslední změny
user_id INT (NULL) ID uživatele, který dokument nahrál

Nahraný soubor se ukládá do složky /uploads/docs na serveru a v DB je uložen jen jeho název (resp. nově vygenerovaný unikátní název).

Práce s dokumenty

  • Vytvoření (upload) – Vyplní se název, kód certifikátu (např. ABC-12345) a připojí se soubor (JPEG, PNG, PDF...). Systém si dokument uloží a přiřadí mu unikátní název souboru.
  • Aktualizace – V případě potřeby lze změnit název nebo kód certifikátu, popř. nahrát nový soubor (starý se vymaže z disku).
  • Smazání – Odstraní záznam z databáze a zároveň vymaže fyzický soubor.

Ukázkový scénář použití

  1. Uživatel (admin) klikne na „Přidat dokument“ a vyplní:
    • Název (např. „Certifikát k náramku Tyrkys“)
    • Kód certifikátu (např. TYRK-2023-WINTER)
    • Soubor PDF nebo obrázek
  2. Dokument se uloží do systému a je viditelný v přehledu „Správa dokumentů“.
  3. Kdykoli později lze k tomuto kódu dohledat relevantní dokument.

Certifikáty se mohou vztahovat k náramkům, mincím vyšších hodnot, speciálním edicím nebo sponzorským darům (např. stromky).

Náramky

V systému se mimo jiné spravují i náramky, které mohou (ale nemusí) být přímo spárovány s konkrétní fyzickou mincí (cooin). Každý náramek je uložen v databázi v tabulce bracelets.

Propojení s tabulkou cooin

  • Kód žetonu (např. 1W21936W) se ukládá do bracelets.cooin_id (cizí klíč do cooin.id).
  • Vrstvy 1–8 jsou typicky použitelné pro náramky (vrstvy 9+ už jsou speciální – např. vyšší investice).
  • Při zadávání kódu se v systému používá našeptávač, který vyhledává mince ve stavu volný.
  • Pokud už je mince k nějakému náramku přidělená, systém vyhodí chybu (nelze použít stejný cooin_id pro dva náramky).

Struktura tabulky bracelets

Sloupec Typ Popis
id INT Primární klíč
name VARCHAR(150) Název náramku
description TEXT Popis (nepovinné)
bead_diameter DECIMAL(5,2) Průměr korálků v mm
date_made DATE Datum výroby (nepovinné)
date_sold DATE Datum prodeje (nepovinné)
price DECIMAL(10,2) Cena náramku (např. 250 Kč, 3000 Kč, atd.)
photo_filename VARCHAR(255) Název nahrané fotky v /upload/naramky/
video_url VARCHAR(255) Odkaz na video (např. z YouTube)
cooin_id INT Odkaz do tabulky cooin – konkrétní mince
docs_id INT Odkaz do tabulky docs – certifikát kamene aj. (nepovinné)
user_id INT Majitel náramku (nepovinné), odkaz na uzivatele
created_at, updated_at DATETIME Datum vytvoření / poslední úpravy záznamu

Základní pravidla

  • Povinné: name, bead_diameter, price a cooin_kod (kód mince) – při vytváření náramku.
  • Nahrávání fotky (photo_filename) je volitelné, ukládá se do složky /upload/naramky.
  • Certifikát (docs_id) – lze přidat, pokud existuje příslušný dokument v tabulce docs (např. GIA certifikát kamene).
  • Majitel (user_id) – volitelné, pokud je náramek již prodaný (viz date_sold), lze přiřadit konkrétního uživatele.

Našeptávač kódu mince

V administraci je pole pro Kód žetonu. Jakmile začnete psát, systém provede AJAX dotaz do cooin, vyfiltruje mince (vrstvy ≤ 8, stav = volný) a nabídne je k výběru. Po potvrzení se do náramku uloží odpovídající cooin_id.

Ukázka vytvoření náramku

  1. Otevřete sekci „Správa náramků“
  2. Klikněte na „Přidat náramek“
  3. Vyplňte Název, Průměr korálků, Cenu, zadejte Kód žetonu (např. 1W21936W) a/nebo připojte fotku, video URL.
  4. Uložte – systém ověří, zda kód mince odpovídá cooin a zda není mince již přiřazená jinému náramku.

Správa adres

Pro potřeby doručení zboží, náramků nebo budoucích rezervací bylo potřeba rozšířit uživatelské profily o možnost ukládání adres. Rozhodli jsme se uchovávat tyto adresy v samostatné tabulce (např. addresses), a pouze je propojovat s tabulkou uživatelů (např. cizím klíčem user_id).

Proč samostatná tabulka?

  • Více adres: Uživatel může mít fakturační a doručovací adresu, nebo i více různých doručovacích adres.
  • Čistota DB schématu: Místo přeplnění tabulky uzivatele sloupci pro ulici, město, PSČ apod. je logické uchovávat je samostatně.
  • Možnost rozšíření: V budoucnu lze snadno přidat např. fakturační vs. doručovací typy, oblíbené adresy, atd.

Struktura tabulky addresses

Název sloupce Typ Popis
id INT Primární klíč
user_id INT Odkaz na tabulku uzivatele
is_billing TINYINT(1) Příznak, zda se jedná o fakturační adresu (1) či nikoli (0)
is_shipping TINYINT(1) Příznak, zda se jedná o doručovací adresu (1) či nikoli (0)
firstname VARCHAR(100) Jméno
lastname VARCHAR(100) Příjmení
company VARCHAR(100) Název společnosti (volitelné)
ico VARCHAR(20) IČ (pokud je potřeba)
dic VARCHAR(20) DIČ (pokud je potřeba)
street VARCHAR(100) Ulice
street_no VARCHAR(20) Číslo popisné
city VARCHAR(100) Město
zip VARCHAR(20) PSČ
country VARCHAR(100) Stát
email VARCHAR(100) Email (může se propsat z uživatele, ale lze změnit)
phone VARCHAR(20) Telefon (může se propsat z uživatele, ale lze změnit)
created_at DATETIME Datum přidání adresy
updated_at DATETIME Datum poslední změny

Přidávání a úprava adres

Adresy lze obsluhovat např. v sekci Můj profil v samostatné kartě nebo podsekci. Tam uživatel vidí seznam svých adres a může je:

  • Vytvořit – vyplněním formuláře (jméno, příjmení, street atd.)
  • Upravit – změnit telefon, e-mail, nastavit příznak doručovací, atp.
  • Smazat – pokud se adresa již nehodí

Uživatel tak může mít (pro příklad) doručovací adresu (is_shipping=1) i fakturační adresu (is_billing=1). Zda obě, nebo jen jednu, záleží na jeho potřebách.

Propojení s budoucími funkcemi

  • Rezervační systém – Při předplatném akce (např. workshopu) se vybere či uloží fakturační adresa
  • Automatické doručení náramků – Adresy pro zaslání zboží (pokud mince dosáhne vyšší úrovně a uživatel si objedná další merch)

Ukázka: Odeslání dárku

  1. Uživatel v sekci Moje mince vymění body za dárek
  2. Je vyžadováno zadání doručovací adresy
  3. Pokud adresu ještě nemá, vytvoří ji, zvolí is_shipping=1
  4. Po potvrzení dojde k fyzickému odeslání dárku na danou adresu