Zip Code Platform

Zip Code Platform este o aplicație Laravel construită pentru a transforma un fișier operațional de coduri poștale într-o bază de date interogabilă și într-un API reutilizabil de aplicații e-commerce sau alte sisteme care au nevoie de validarea și completarea adreselor. Repository-ul include o suprafață publică simplă, conturi de utilizator, un panou administrativ și API-ul protejat prin chei.

Fluxul de date pornește din admin, unde poate fi încărcat un fișier Excel .xlsx/.xls. Controllerul îl salvează local, determină numărul de rânduri și lansează un Laravel Job pe queue-ul configurat în baza de date. Importul citește fișierul în ferestre de câte 500 de rânduri și limitează coloanele procesate la cod poștal, localitate/județ și stradă. Pentru fiecare rând sunt separate localitatea și județul, sunt interpretate sectoarele Bucureștiului și sunt transformate expresiile de numere în intervale sau valori individuale. Scrierea se face în batch-uri, după verificarea combinațiilor deja existente. Progresul este păstrat temporar în Laravel Cache și interfața admin îl interoghează periodic fără a ține request-ul de upload deschis pe toată durata procesării.

API-ul expune patru operații dedicate: căutarea codului poștal pornind de la adresă, lista localităților, validarea unui cod poștal și normalizarea unei adrese. Căutarea normalizează diacriticele și abrevierile județelor, încearcă variante ale denumirii străzii și aplică o succesiune de fallback-uri: potrivire cu număr, potrivire pe stradă, potrivire fuzzy și, în final, localitate + județ. Accesul este filtrat de un middleware de API key care verifică existența, starea activă și data de expirare.

Panoul administrativ acoperă trei zone principale: coduri poștale, utilizatori și chei API. Tabelele permit filtrare, sortare și paginare, iar administratorul poate genera chei pentru un utilizator, poate seta expirarea și le poate activa sau dezactiva. Utilizatorul autentificat are propriul dashboard pentru datele contului și cheile asociate. UI-ul este server-rendered cu Blade și Tailwind, cu Alpine.js pentru interacțiunile de navigație/modal și JavaScript simplu pentru polling-ul progresului de import.

Codul conține și începutul unui flux comercial cu Stripe Checkout, un webhook care ar genera o cheie temporară după checkout și o rută de download pentru un plugin. Aceste zone nu sunt complete în snapshotul analizat: configurația Stripe lipsește din services.php, webhook-ul este plasat în grupul web autentificat, formularul de plată nu apelează ruta de procesare, plățile nu sunt persistate de acest flux, iar arhiva pluginului nu există în repository. Din acest motiv ele sunt tratate ca direcție de produs, nu ca rezultat livrat.

Pentru producție, următoarele îmbunătățiri importante sunt hardening-ul API-ului și al importului: validare explicită pentru request-uri, rate limiting per cheie, stocarea hash-uită a cheilor cu afișare o singură dată, parametrizarea completă a fallback-ului fuzzy, constrângeri unique/upsert pentru deduplicare concurentă, indexuri aliniate cu interogările reale și retry/cleanup explicit pentru jobul de import. Repository-ul nu conține workflow-uri CI/CD, Docker sau configurație de deployment reproductibilă; există însă endpointul standard Laravel /up și scripturile locale pentru build, test și worker de queue.