ZIP Code Manager

ZIP Code Manager este un plugin WordPress construit pentru un flux operațional WooCommerce în care codurile poștale din comenzi trebuie verificate sau completate pe baza unui nomenclator local. Administratorul încarcă un fișier Excel din WordPress Admin, vede o previzualizare a primelor rânduri și confirmă importul; procesarea continuă prin cereri AJAX succesive, astfel încât un fișier mare nu este tratat ca o singură cerere web de lungă durată.

Importul folosește PhpSpreadsheet și un IReadFilter care citește numai coloanele necesare din sursă: cod poștal, localitate și stradă. Fluxul AJAX procesează câte 500 de rânduri, iar UI-ul primește pentru fiecare chunk numărul de intrări procesate, inserate, actualizate și deja existente. Pentru preview sunt citite maximum 50 de rânduri. Snapshot-ul permite selectarea .xls și .xlsx, însă procesorul de chunk-uri folosește explicit readerul Xlsx; de aceea suportul legacy XLS trebuie considerat incomplet.

Înainte de persistență, localitatea este separată de abrevierea județului printr-o hartă completă a județelor din România, cu tratament separat pentru București și sectoare. Strada este apoi analizată pentru segmente de tip nr., intervale precum 13-17, capete deschise de forma 26-T, numere singulare și sufixe de tip bis/A/B. Când o stradă conține mai multe intervale, fiecare interval devine un rând utilizabil pentru lookup, iar structura completă poate fi păstrată ca JSON în multiple_ranges.

Datele sunt salvate într-o tabelă WordPress dedicată, wp_*_zip_codes, cu cod poștal, localitate, județ, stradă, început și sfârșit de interval, flag pentru interval infinit, metadata pentru intervale multiple și created_at. Schema are index compus pe cod poștal + stradă și un index pe capetele intervalului. Importul încearcă să identifice o înregistrare existentă prin combinația cod poștal, stradă, number_start și number_stop; intrările noi sunt grupate într-un INSERT comun, iar cele existente primesc update pentru localitate, județ și metadata de interval. Nu există însă constrângere UNIQUE în DB, deci integritatea împotriva duplicatelor se bazează pe logica aplicației.

Integrarea WooCommerce este orientată către operator. În lista de comenzi și în ecranul de editare apare acțiunea «Actualizează cod poștal». La apăsare, pluginul citește separat adresa de facturare și cea de livrare, normalizează diacriticele și abrevierile de județ, extrage numărul stradal, sectorul și blocul și încearcă să găsească un cod poștal în tabela importată. Căutarea are trei trepte: potrivire pe localitate/județ + stradă și interval numeric, apoi un LIKE mai relaxat pe stradă, apoi fallback la primul cod distinct pentru localitate/județ. Dacă găsește rezultate, actualizează billing_postcode și, când este cazul, shipping_postcode prin obiectul WooCommerce Order și salvează comanda.

Pluginul declară compatibilitate WooCommerce HPOS și verifică prezența WooCommerce și PhpSpreadsheet înainte de utilizare. AJAX-ul pentru import și acțiunea de actualizare a comenzilor folosesc nonce WordPress. Totuși, snapshot-ul are câteva puncte de hardening: formularul inițial de upload nu are nonce propriu, handler-ele AJAX nu fac un current_user_can explicit, fișierul temporar de import nu este șters la final, MIME-ul uploadului este verificat direct din request, iar logarea de debug scrie adrese și query-uri în error_log. Acestea sunt observații de cod, nu funcționalități prezentate ca avantaje.

Frontend-ul proiectului este intenționat nativ WordPress Admin, nu o aplicație separată. Uploadul și preview-ul folosesc componentele vizuale WordPress, iar jQuery conduce procesarea chunk-urilor și mesajele de progres. Există un fișier CSS pentru butonul de actualizare a codului poștal, însă snapshot-ul nu îl înregistrează prin wp_enqueue_style; progresul importului este în principal textual, fără un design system propriu. Repository-ul conține un singur commit de backup pentru portofoliu și nu include teste, workflow-uri GitHub, Docker sau scripturi de deployment.