# 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.