Katalog i zalihe

Katalog objedinjuje tri vrste u jednoj tablici: artikle, usluge i digitalne proizvode. Artikl nosi zalihu, dok je usluga uvijek dostupna. Dodatne usluge (npr. zamatanje poklona) mogu se ponuditi kao odvojeni checkbox na blagajni. Baza dopušta add-on samo uz vrstu "usluga", pa se slučajno ne može proglasiti običan artikl za dodatak.

Varijante, zalihe i EAN

Varijante (veličina, boja, model) imaju svoj SKU, cijenu koja prebija osnovnu ako je unesena i vlastitu zalihu. Ako je jedna varijanta rasprodana, a druge imaju zalihe, artikl ostaje u prodaji. Oznaka "Nema na zalihi" se pojavljuje tek kad su SVE varijante prazne. Kod artikla bez varijanti gleda se izravno njegovo stanje.

Zaliha se spušta atomskim SQL upitom: ako nema dovoljno, a nije uključeno "dozvoli prodaju u minus", blagajna odbija narudžbu.

Taj isti mehanizam štiti i ručne narudžbe unesene telefonom ili WhatsAppom.

Uz SKU svaki artikl može nositi i EAN te internu šifru artikla. Te oznake ulaze u automatski feed za Google Merchant čim dućan radi na vlastitoj domeni, pa ih nije potrebno ručno dodavati na drugom mjestu.

Zaliha se može pratiti po više skladišta ili poslovnica, popunjenih kroz Arges sinkronizaciju. Svaka lokacija ima vlastitu količinu s tri decimale, pa podržava i vagu (kg, litre, metražu). Jedna lokacija određuje prodajnu zalihu weba za sinkronizirane artikle bez varijanti — prebacivanje u tzv. "web skladište" odrađuje se jednim klikom i preslikava stanje, uz broj ažuriranih artikala u odgovoru. Artikli s varijantama tu postavku ne prate: njihova prodajna zaliha ostaje zbroj svih poslovnih prostora (vidi Varijante).

Kad nastane narudžba, njezin naziv, naziv varijante i cijena se snimaju u stavke narudžbe. Kasnija promjena ili brisanje artikla ne dira povijesnu narudžbu. Digitalni proizvodi primaju datoteku do 100 MiB, nemaju javnu rutu, a token za preuzimanje izdaje se tek nakon plaćanja. Svaka poveznica vrijedi 5 puta, pa preuzimanje postane nedostupno s jasnom porukom. Ako je u košarici isključivo digitalna roba, blagajna automatski preskače adresu i dostavu.

Slug se postavlja samo pri kreiranju artikla i ne mijenja se prilikom sinkronizacije s vanjskim ERP-om, pa URL-ovi kategorija i artikala ostaju stabilni. Kategorije imaju ručni redoslijed i vlastita SEO polja (naslov i opis) koja se mogu uređivati u CMS-u.

Uvoz i izvoz

Uvoz kataloga prihvaća CSV iz WooCommercea, Shopifyja ili generički WebShopHR format. Sustav prepoznaje format po headeru, sam otkriva delimiter (zarez ili točka-zarez), uklanja Excelov UTF-8 BOM i čita hrvatske cijene oblika 1.234,56 € kao i engleske 1234.56. Shopifyjev HTML opis se automatski čisti u čisti tekst, a slug se gradi iz naziva ili SKU-a. Istoimeni slugovi unutar istog uploada rješavaju se dodavanjem -2, -3 itd.

Cijeli uvoz je atomski: sve ili ništa. Prije bilo kakvog upisa provjeri se kvota paketa (maksimalan broj artikala), pa ako CSV prelazi limit, ne uveze se ništa, a trgovac dobije poruku koliko još artikala stane. Redovi bez naziva ili s neispravnom cijenom se preskaču, a API vraća broj uvezenih i preskočenih redaka te do 10 konkretnih primjera grešaka. Nakon uspješnog uvoza katalog se sam reindeksira za pretraživanje.

Izvoz ide s jednog endpointa: /api/v1/export. JSON izlaz je ugniježđen: artikli nose varijante, a narudžbe nose stavke. CSV izlaz stiže kao ZIP arhiva s četiri datoteke: items.csv, customers.csv, orders.csv i order_items.csv. Svaki CSV ima UTF-8 oznaku na početku tako da Excel na Windowsu ne poremeti hrvatska slova.

Cijeli izvoz čita podatke iz jedne transakcije, pa je snapshot konzistentan. Datumi su u standardnom ISO obliku, iznosi u centima, a prazne vrijednosti ostaju prazne.

Narudžbe u izvozu uključuju R1 podatke, subtotal, dostavu, popust, kupon, total i iznos povrata. Kupci se izvoze bez lozinke, s dodatnim stupcem koji bilježi datum anonimizacije. Izvoz je ograničen na 10 pokretanja po satu po trgovini. Ako cache za limit padne, sustav nastavi raditi (fail-open) umjesto da potajno blokira pristup vlastitim podacima.

Slike

Slike artikala idu kroz servis za prilagodbu koji u zahtjevu generira WebP i resize. URL-ovi su kriptografski potpisani, pa se ne mogu izmijeniti izvana. Ako taj servis nije konfiguriran, slika se automatski poslužuje izravno putem /slike/{ključ} bez greške. U produkciji aplikacija odbija startati ako je postavljen URL servisa, a nedostaju ključ i salt. Nikad se ne koriste javno poznati razvojni ključevi u produkciji.

Upload podržava JPEG, PNG i WebP do 5 MiB po slici. Slike se spremaju u zasebni prostor po trgovini, a ključ sadrži identifikatore trgovine, artikla i jedinstveni UUID. Ako zapis slike ne uspije u bazi nakon uploada, objekt se odmah briše iz spremišta, tako da ne ostaju siročići. Brisanjem slike u CMS-u oslobađa se prostor u skladišnoj kvoti u istoj transakciji.

Slike se serviraju s javnim, tjednom keširanjem i oznakom da se više ne mijenjaju, što pogoduje CDN-u. Resize se koristi u ovisnosti o kontekstu: detaljna slika artikla ide na 800 px, sličice u popisima na 400 px. Svaka slika ima polje za alt tekst i redni broj, a alat za potpunost kataloga upozorava ako postoji aktivni artikl sa slikom, ali bez alt teksta.