# PANSION ANA ASSETS — KONTEKST I OBAVEZNA PRAVILA ZA CODEX

## Svrha projekta

Ovaj projekt je javni, zajednički repozitorij statičkih resursa za Pansion Ana. Resursi iz njega poslužuju se preko:

`https://assets.pansion-ana.com/`

Namijenjen je datotekama koje stvarno koristi više web-stranica, aplikacija ili poddomena. Nije odlagalište svih datoteka iz drugih projekata i nije mjesto za poslovnu logiku.

Za svaki zadatak vrijedi ovaj red prioriteta:

1. konkretan aktualni korisnički prompt
2. aktualne datoteke u workspaceu kao apsolutni source of truth
3. ova projektna pravila kao kontekst rada

Ovaj dokument nije backlog. Ne migrirati, preimenovati ni brisati resurse bez konkretnog korisničkog zahtjeva.

## Granice workspacea

- Mijenjati samo datoteke unutar ovog `assets` projekta.
- Druge projekte, uključujući `booking`, `site`, `tv` i njihove module, koristiti samo kao read-only referencu osim ako korisnik izričito zatraži izmjenu u njima.
- Ne skenirati velike foldere bez potrebe. Ignorirati `node_modules`, `vendor`, cache, logove, backup arhive, upload i temp foldere.
- Ne kopirati cijele biblioteke ili source pakete ako je za javnu upotrebu potreban samo njihov mali distribucijski dio.

## Organizacija javnih resursa

Trenutne glavne kategorije su:

- `allergens/` — zajedničke ikone alergena i pripadajuće licence; aktivna stabilna verzija je u `allergens/v1/`
- `css/` — zajednički, gotovi CSS koji učitava više aplikacija
- `js/` — zajednički, gotovi JavaScript za preglednik
- `fonts/` — lokalno hostani webfontovi i njihovi stylesheetovi
- `gov/` — javne JSON datoteke za sidrene cijene
- `config/` — javni, statički podatkovni ugovori za više aplikacija; trenutačno `config/v1/ana-public.json`
- `images/` — fotografije, logotipi, pozadine i druge rasterske ili sadržajne slike
- `icons/` — UI, brand i aplikacijske ikone, uključujući SVG/PNG/ICO kada nisu dio posebne domene poput alergena
- `translations/` — javni statički prijevodi koje dijele glavna stranica, `info` i druge aplikacije
- `qr/` — svi javni QR kodovi Pansiona Ana; trenutačno `info.png`, `menu.png` i `wifi.jpg`
- `brand/` — javni katalog i specifikacija ANA brenda; ne koristi verzionirani podfolder

Za novu veću cjelinu koristiti zaseban semantički folder samo kada ne pripada postojećim kategorijama i kada će je stvarno dijeliti više potrošača.

## Putanje i verzioniranje

- Javni URL mora biti apsolutan HTTPS URL, primjerice `https://assets.pansion-ana.com/icons/v1/example.svg`.
- Stabilne javne datoteke stavljati u verzionirane putanje. Početna verzija je `v1`; breaking promjena ide u `v2`, bez prepisivanja aktivnog `v1` sadržaja. Iznimke su QR kodovi, koji ostaju izravno u `qr/`, i javni katalog/specifikacija brenda, koji ostaju izravno u `brand/` bez verzijskih podfoldera.
- Za font-family, biblioteku ili veću imenovanu kolekciju dopuštena je dodatna razina, primjerice `fonts/inter/v1/` ili `js/calendar/v1/`.
- Ne koristiti `latest`, `final`, `new`, datume izmjene ili nejasne sufikse kao zamjenu za verziju.
- Nazivi datoteka i foldera moraju biti lowercase, ASCII i kebab-case. Bez razmaka, dijakritike i nejasnih kratica.
- Relativne veze unutar CSS-a moraju odgovarati stvarnoj javnoj strukturi nakon deploya.

## Što pripada na assets domenu

Dodati samo resurs koji je statičan, siguran za javno čitanje i koji ima barem jednog poznatog potrošača. Prednost imaju resursi koji se ponavljaju u više projekata ili poddomena, primjerice:

- zajednički logotipi, favikone, SVG/PNG ikone i slike
- webfontovi u WOFF2 formatu i pripadajući CSS
- zajednički CSS za dijeljene UI elemente
- zajednički browser JavaScript bez tajni i server-side ovisnosti
- javne JSON podatke za sidrene cijene u `gov/`
- javne, statičke podatkovne ugovore bez tajni i izvršne logike u `config/v1/`
- licencne datoteke koje se moraju distribuirati uz font, ikonu ili drugi asset
- javni statički prijevodi u neutralnom podatkovnom formatu, bez PHP-a, session logike i poslovne logike
- javni QR kodovi namijenjeni gostima, uključujući informacije, jelovnik i pristup gostujućoj Wi-Fi mreži

Ako resurs koristi samo jedna aplikacija, u pravilu ostaje u toj aplikaciji dok korisnik ne zatraži migraciju ili dok ne postoji jasan drugi potrošač.

## Što ne pripada na assets domenu

Nikada ne dodavati:

- PHP, SQL, konfiguraciju servera ili poslovnu logiku aplikacija
- interne ili administrativne lozinke, API ključeve, tokene, session podatke ili druge tajne; jedina dopuštena iznimka je izričito odobren QR za javnu gostujuću Wi-Fi mrežu
- korisničke uploadove, privatne dokumente, račune, rezervacije ili osobne podatke
- logove, cache, temp datoteke, backupove i ZIP arhive projekta
- razvojne ovisnosti, build cache ili cijele source repozitorije kada nisu nužni za javnu distribuciju
- source mapove koji otkrivaju privatni izvorni kod, osim ako je njihova javna objava izričito odobrena

### Iznimka za include-only template

Kada korisnik izričito zatraži zajednički PHP template za prikaz ili prijevode, on smije biti u `widgets/v1/` ili `translations/v1/` samo kao include-only izvor za susjedne aplikacije. Blokirati izravan HTTP pristup lokalnim `.htaccess` pravilom. Pozivatelj zadržava DB dohvat i prosljeđuje varijable; u template ne stavljati pristup bazi, tajne, session ni request logiku.

## Pravila migracije

1. Migracije raditi samo kroz konkretan korisnički zadatak; ne premještati masovno postojeće resurse iz drugih projekata.
2. Prije kopiranja pronaći sve aktivne pozivatelje i utvrditi koja je datoteka stvarni source of truth.
3. Provjeriti je li sadržaj identičan između duplikata. Ne zaključivati samo po nazivu datoteke.
4. Kopirati samo potreban distribucijski sadržaj i obavezne licence. Ne brisati staru lokalnu kopiju u istom koraku bez izričitog zahtjeva.
5. U potrošaču koristiti puni URL s `https://assets.pansion-ana.com/` i verzioniranom putanjom.
6. Prije uklanjanja stare kopije provjeriti sve aktivne potrošače, desktop i mobilni prikaz, print prikaz, cache, CSP, CORS i MIME tipove.
7. Za CSS i JavaScript provjeriti load order, ovisnosti i kompatibilnost. Zajednička lokacija nije razlog za automatsko spajanje ili refaktoriranje.
8. Svaki folder koji je prebačen na assets domenu i uspješno povezan u aktivnom siteu ili projektu mora se u tom aktivnom projektu preimenovati dodavanjem sufiksa `_safe2delete` na postojeći naziv foldera, primjerice `icons` u `icons_safe2delete`.
9. Sufiks `_safe2delete` dodati tek nakon provjere da aktivni pozivatelji koriste assets URL i da prikaz i funkcionalnost rade ispravno. Folder tada ne brisati; sufiks označava sačuvanu staru lokalnu kopiju koja čeka zasebno, izričito odobreno brisanje.
10. Ako folder već završava sufiksom `_safe2delete`, ne dodavati sufiks ponovno.

## Fontovi, ikone i licence

- Za webfontove preferirati WOFF2; druge formate dodati samo kada ih stvarno zahtijeva podržani klijent.
- Svaki `@font-face` mora koristiti ispravnu javnu putanju, deklarirati stvarne weight/style vrijednosti i imati razuman fallback.
- Fontovi i drugi cross-origin resursi moraju biti provjereni s CORS pravilima assets domene prije aktivacije u drugim poddomenama.
- SVG datoteke prije objave pregledati zbog skripti, vanjskih referenci, nepotrebnih metapodataka i sigurnosno problematičnog sadržaja.
- Ne mijenjati tuđe licence i ne uklanjati obaveznu atribuciju. Licencu držati uz odgovarajuću verzioniranu kolekciju kada to licenca traži.

## Prijevodi

- Zajedničke prijevode držati zajedno u jednoj verzioniranoj zbirci unutar `translations/`, primjerice `translations/v1/`. Ne dijeliti ih u zasebne datoteke po jeziku.
- Postojeći source model je niz s fiksnim numeričkim indeksima: `0` hrvatski, `1` engleski, `2` talijanski, `3` njemački i `4` slovenski. U postojećem kodu jezični kod za slovenski je `sl`.
- Vrijednost prijevoda dohvaća se pomoću aktualnog indeksa `$x`. Redoslijed jezika ne mijenjati i ne sortirati jer bi time svi postojeći pozivatelji dobili pogrešan jezik.
- Svaki prijevodni ključ mora sadržavati svih pet vrijednosti u istom redoslijedu. Nedostajuću vrijednost ne nadomještati pomicanjem indeksa.
- `dist/lib/translations.php` u projektima `info` i glavnom `site` projektu tretirati kao postojeće izvore prijevoda koje treba usporediti prije objedinjavanja. Jezični URL folderi u glavnom siteu nisu zaseban source prijevoda; njihov prikaz koristi vrijednosti iz translations zbirke.
- Ne spajati dva istoimena ključa samo prema nazivu. Prvo usporediti svih pet vrijednosti, značenje, HTML kontekst i aktivne pozivatelje.
- Budući zajednički format mora sačuvati strukturu `ključ => [0, 1, 2, 3, 4]`. Ne pretvarati ga u odvojene `hr`, `en`, `it`, `de` i `sl` datoteke bez izričitog zahtjeva i koordinirane izmjene svih potrošača.
- Datoteka mora biti UTF-8 bez BOM-a. HTML unutar prijevoda zadržati kada je dio postojećeg prikaza; ne escapati, čistiti ni mijenjati markup bez provjere pozivatelja.
- Session odabir jezika, izračun `$x` i druga izvršna logika ostaju u aplikacijama. Na assets domenu ide samo dogovoreni zajednički prijevodni skup, bez session i poslovne logike.
- Prije aktivacije provjeriti potpunost svih nizova, fiksni raspored pet jezika, sintaksu odabranog formata, cache/CORS i prikaz dijakritike.
- Postojeće prijevodne datoteke u potrošačkim projektima ne mijenjati ni uklanjati dok zajednički skup nije uspoređen, pregledan i uključen kroz zaseban korisnički zadatak.

## QR kodovi

- Sve QR kodove držati u `qr/`. Trenutačne kanonske datoteke su `qr/info.png`, `qr/menu.png` i `qr/wifi.jpg`.
- QR kodovi se ne verzioniraju i za njih se ne stvaraju `v1`, `v2` ili slični podfolderi.
- Postojeće nazive i URL-ove smatrati stabilnima jer mogu biti otisnuti na fizičkim materijalima. Ne preimenovati ih, premještati ni mijenjati format bez izričitog zahtjeva.
- Prije dodavanja ili zamjene QR koda provjeriti dekodirani sadržaj i potvrditi da vodi na očekivani HTTPS URL ili na izričito odobrene podatke gostujuće Wi-Fi mreže.
- Ne spremati QR kodove za interne sustave, administraciju, zaposleničke mreže, privatne dokumente ili jednokratne pristupne tokene.
- Nakon izmjene provjeriti čitljivost QR koda s prikaza i iz ispisa; zadržati dovoljan kontrast i slobodan rub oko koda.

## Cache i kompatibilnost

- Verzijske putanje smatraju se stabilnima: postojeću datoteku ne mijenjati na način koji neočekivano mijenja prikaz ili ponašanje aktivnih potrošača.
- Za breaking promjenu napraviti novu verziju i migrirati potrošače postupno.
- Ako se datoteka ipak mora zamijeniti bez nove verzije, prije isporuke provjeriti cache invalidaciju i navesti rizik.
- Ne pretpostavljati da su javna domena i lokalni projekt ista revizija; jasno navesti što je provjereno.

## Obavezna provjera prije isporuke

1. Pročitati aktualni korisnički prompt i pregledati povezane datoteke prije izmjene.
2. Potvrditi da svaka nova javna datoteka pripada ispravnoj kategoriji i verziji.
3. Provjeriti nazive, ekstenzije, MIME/CORS zahtjeve, relativne URL-ove i licence.
4. Za CSS i JavaScript napraviti barem sintaksnu provjeru; za slike, SVG i fontove potvrditi da datoteke nisu oštećene.
5. Kod migracije provjeriti stvarne pozivatelje i ne uklanjati stare kopije bez izričitog zahtjeva.
6. Pregledati sve promjene i potvrditi da nema tajni, privatnih podataka, backupova ni nepotrebnih source datoteka.
7. Isporučiti popis dodanih ili izmijenjenih resursa i njihove konačne javne URL-ove kada su poznati.

Za svaki novi zadatak: radi usko unutar traženog opsega, provjeri source of truth i aktivne potrošače, zadrži stabilne verzionirane URL-ove te ne uvodi regresije u drugim poddomenama.