KAZ-BLANK: GLOBALNA ARHITEKTURA I TEHNIČKI STANDARDI PROJEKTA

Ovaj dokument predstavlja primarni dugoročni kontekst, arhitektonski temelj i inženjerski standard za razvoj prilagođene (custom) WordPress teme kaz-blank. Svi AI agenti i programeri moraju striktno pratiti ova pravila kako bi se očuvao integritet sistema.

1. PREGLED PROJEKTA I OKRUŽENJE

• Tip teme: Potpuno prilagođena (custom) WordPress tema bez gotovih page-builder okvira na backendu.
• Fokus industrije: Investiciono zlato i finansijske usluge visokog nivoa (distribucija premijum proizvoda, visoka osetljivost na tačnost podataka).
• Lokalno okruženje: WordPress instaliran u poddirektorijumu /kaz/ (npr. dev.dunavgold.rs/kaz/).
• Produkciono okruženje: Server sa aktivnim LiteSpeed veb serverom i uključenim agresivnim javnim keširanjem (Public Cache = ON).

2. MEHANIKA SINHRONIZACIJE I ISTORIJE CENA

Sistem cena prati visoko turbulentno berzansko tržište i podeljen je na pozadinske (asinkrone) procese i klijentske (live) zaobilaznice.

A. Minutna sinhronizacija (Bulk Price Importer)

• Logika: Skripta povlači spoljni partnerski feed sa https://dunavgold.rs/dg-feed/cene.json. Početni "meta" objekat u nizu se ignoriše. Mapiranje se vrši isključivo preko SKU koda artikla ($item->art == $sku).
• Putanja marži: Marže se čitaju iz fajla inc/price-sync/koeficijent.json. Putanja MORA biti definisana apsolutno preko WordPress funkcija:

$coefsPath = get_template_directory() . '/inc/price-sync/koeficijent.json';

• Okidanje: Sistemski cPanel Cron Job izvršava komandu na svakih 60 sekundi (svakog minuta) gađajući zaštićeni REST endpoint sa tokenom:

* * * * * curl -s "https://dev.dunavgold.rs/kaz/wp-json/kaz/v1/cron-sync?token=kaz-secure-cron-2026" > /dev/null

B. Dnevna istorija cena (Database Tracking)

• Tabela: Prilagođena tabela unutar WP baze podataka wp_kaz_price_history skladišti dnevne preseke najnižih cena za kategoriju 1g.
• Mehanizam otpornosti: Ako unos za traženi dan ne postoji u tabeli (npr. vikend ili državni praznik kada berza ne radi), SQL upit automatski klizi unazad i povlači poslednji dostupan presek:

SELECT price FROM wp_kaz_price_history WHERE weight_category = '1g' AND date <= %s ORDER BY date DESC LIMIT 1

• Okidanje: CPanel sistemski cron job osigurava stabilno okidanje WP-Cron podsistema svake večeri u 23:55 kako bi se izbeglo kašnjenje uzrokovano odsustvom posetilaca na sajtu:

55 23 * * * wget -q -O - https://dev.dunavgold.rs/kaz/wp-cron.php?doing_wp_cron >/dev/null 2>&1

3. PERFORMANSE I PROBIJANJE LITESPEED KEŠA

Zbog agresivnog keširanja stranica, cene na frontendu se ne smeju ispisivati direktno iz PHP-a ukoliko su podložne brzim promenama.

A. REST API Endpoints & Filteri (inc/live-prices.php)

• Live Prices Ruta: Registrovana na /wp-json/kaz/v1/live-prices. Prihvata pojedinačne ili grupne ID-jeve (?ids=12,45,88) ili tehnički tag (?tag=chart-ref-1g).
• Bypass pravilo: Svi REST API zahtevi koji se odnose na sinhronizaciju i live cene moraju programski zaobići LiteSpeed keširanje pomoću nativnog filtera:

add_filter( 'litespeed_cache_api_bypass', '__return_true' );

B. Klijentski DOM Overwrite (assets/js/live-prices.js)

• Mehanika: JS skripta se pokreće tek na DOMContentLoaded događaju. Ona skenira stranicu, prikuplja sve elemente sa cenama (preko .price klase ili data-live-tag atributa), spaja ih u jedan mrežni zahtev i asinhrono povlači sveže cene iz baze.
• Rezultat: Korisnik vidi iskeširanu stranicu trenutno, a cene "trepnu" i ažuriraju se na najnovije vrednosti u milisekundi, probijajući keš servera bez opterećenja procesora.

C. Maskiranje tehničkih oznaka (chart-ref-)

Sve tehničke oznake proizvoda koje počinju sa prefiksom chart-ref- (npr. chart-ref-1g) služe isključivo za pozadinsko programsko identifikovanje i MORAJU biti filtrirane i sakrivene iz javnih WooCommerce metapodataka, vidljivih tagova na stranici proizvoda i Tag Cloud vidžeta.

4. MULTIMEDIJALNI PIPELINE I OPTIMIZACIJA ASSETA

Jasna podela između sistemskih datoteka i sadržaja koji unosi korisnik.

A. Organizacija Direktorijuma unutar Teme

• assets/css/ i assets/js/ - Stilovi i skripte teme.
• assets/js/vendor/ - Eksterne biblioteke (npr. lenis.min.js).
• assets/img/ - Isključivo sistemska grafika (logotipi, ikone, fiksne pozadine koje čine layout).
• assets/icons/ - Isključivo sistemski SVG fajlovi koji se dinamički učitavaju pomoću kaz_get_icon() helper funkcije.
• assets/video/ ili assets/media/ - Teški elementi koji čine strukturu teme (npr. optimizovani 1080p WebM/MP4 video petlja za pozadinu hero sekcije).

D. Dinamički SVG Helper za ikonice (inc/svg-helper.php)

Kako bi se izbeglo lepljenje sirovog (inline) SVG koda u templejte, a zadržala puna CSS kontrola nad elementima, koristi se PHP helper funkcija kaz_get_icon( $icon_name, $class = '' ).

• Logika: Funkcija dinamički učitava lokalne .svg fajlove iz assets/icons/ foldera (prateći šablon imena icon-{$icon_name}.svg) koristeći apsolutnu serversku putanju i funkciju file_get_contents().
• Manipulacija klasama: Ukoliko je kroz drugi parametar prosleđena CSS klasa, funkcija je programski ubacuje direktno u otvarajući <svg> tag pre samog renderovanja u HTML-u.
• CSS Upravljanje: Na ikonice se primenjuje klasa sa svojstvom fill: currentColor;, što omogućava potpunu kontrolu boja, tranzicija i hover efekata direktno iz style.css preko roditeljskih elemenata (npr. promenom color svojstva na roditeljskom divu).
• Primer upotrebe u templejtu (npr. front-page.php):

<?php echo kaz_get_icon('delivery', 'service-icon-svg'); ?>

B. WP Media Library (.webp Presretač preko Imagick-a)

• Sav sadržaj, slike proizvoda i baneri idu kroz standardnu WordPress medijateku.
• Prilikom uploada, PHP Imagick klasa presreće fajl (wp_handle_upload filter), vrši proveru širine i primenjuje sledeće nivoe kompresije pre konverzije u .webp format uz brisanje originala:
  • Slike iznad 1400px širine: Suptilna kompresija (Quality: 85).
  • Slike do 1400px širine: Intenzivnija kompresija (Quality: 70).

C. Lokalni Squoosh Pratilac (squoosh.py)

Za datoteke koje programer ručno ubacuje u assets/img/ direktorijum, koristi se lokalna Python skripta sa Pillow bibliotekom koja preslikava serversku logiku (85/70 kvalitet u zavisnosti od 1400px limita), generiše kompresovane .webp blizance, ali čuva originalne izvorne fajlove netaknutim na lokalnom disku.

5. KORISNIČKO ISKUSTVO I SKROLMEHANIKA

• Biblioteka: assets/js/vendor/lenis.js obezbeđuje smooth scroll efekat na čitavom sajtu.
• Inicijalizacija (assets/js/scroll.js): Pokreće se sa parametrima koji simuliraju težak, premium, viskozan GSAP osećaj skrolovanja:

const lenis = new Lenis({
  lerp: 0.07,
  smoothWheel: true
});

Skripta je uvezana u WordPress sistem zavisnosti tako da se scroll.js nikada ne učitava pre nego što lenis.js bude potpuno dostupan.

6. STROGA STILSKA I PROGRAMERSKA PRAVILA ZA AI AGENTE

1. Zabranjene relativne putanje: Nikada ne koristiti __DIR__ ili relativne skokove tipa ../ za uključivanje (include/require) osnovnih komponenti unutar functions.php. Uvek koristiti get_template_directory().
2. Razdvajanje faza razvoja: Prilikom izrade novih stranica, HTML struktura i CSS klase se najpre zapišu statički u odgovarajući šablon (npr. front-page.php, page-templates/). Integracija sa ACF (Advanced Custom Fields) i prebacivanje u dinamička polja vrši se tek nakon što je frontend dizajn potpuno potvrđen.
3. Zabrana uništavanja baze kod automatskih grešaka: Sve funkcije koje vrše upis cena ili podataka moraju imati ugrađene fallback odbrambene mehanizme (npr. ako koeficijent nije dostupan, koristi se podrazumevana vrednost 1, kako cena ne bi pala na nulu).
4. Održavanje ovog dokumenta: Svaki naredni korak koji menja globalnu arhitekturu sistema mora biti dokumentovan u ovom fajlu.