gomag-vending/scripts/HANDOFF_MAPPING.md

Handoff: Matching GoMag SKU → ROA Articole pentru Mapari

Context

Vending (coffeepoint.ro) are ~429 comenzi GoMag importate in SQLite, din care ~393 SKIPPED (lipsesc mapari SKU). Facturile pentru aceste comenzi exista deja in Oracle ROA, create manual independent de import. Scopul: descoperim corespondenta SKU GoMag → id_articol ROA din compararea comenzilor cu facturile.

Ce s-a facut

1. Fix customer_name (COMPLETAT - commits pe main)

• Problema: customer_name in SQLite era shipping person, nu firma de facturare
• Fix: Cand billing e pe firma, customer_name = company_name (nu shipping person)
• Fix 2: customer_name nu se actualiza la upsert SQLite (doar la INSERT)
• Fix 3: Dashboard JS afisa shipping_name cu prioritate in loc de customer_name
• Commits: cc872cf, ecb4777, 172debd, 8020b2d

2. Matching comenzi → facturi (FUNCTIONEAZA)

• Metoda: Fuzzy match pe client name + total comanda + data (±3 zile)
• Rezultat: 428/429 comenzi matched cu facturi Oracle (1 nematched)
• Script: scripts/match_all.py, scripts/match_by_price.py

3. Matching linii comenzi → linii facturi (ESUAT - REZULTATE NESATISFACATOARE)

Ce s-a incercat:

1. Match pe CODMAT (SKU == CODMAT din vanzari_detalii) → Multe articole ROA nu au CODMAT completat
2. Match pe valoare linie (qty × pret) → Functioneaza cand comanda GoMag corespunde exact cu factura
3. Match pe pret unitar (pret fara TVA) → Idem, functioneaza doar cand articolele coincid

De ce nu merge:

• Articolele din factura ROA sunt COMPLET DIFERITE fata de comanda GoMag in multe cazuri
• Exemplu: comanda GoMag are "Lavazza Crema E Aroma" dar factura ROA are "CAFEA FRESSO BLUE"
• Asta se intampla probabil pentru ca vanzatorul ajusteaza comanda inainte de facturare (inlocuieste produse, adauga altele, modifica cantitati)
• Matching-ul pe pret gaseste corespondente FALSE (produse diferite care au intamplator acelasi pret)
• Rezultat: din 37 mapari "simple 1:1", unele sunt corecte, altele sunt nonsens
• Repackaging si seturi sunt aproape toate false

Ce a produs:

• scripts/output/update_codmat.sql — 37 UPDATE-uri nom_articole (TREBUIE VERIFICATE MANUAL, multe sunt gresite)
• scripts/output/repack_mappings.csv — 16 repackaging (majoritatea gresite)
• scripts/output/set_mappings.csv — 52 seturi (aproape toate gresite)
• scripts/output/inconsistent_skus.csv — 11 SKU-uri cu match-uri contradictorii

Ce NU a mers si de ce

Algoritmul actual face matching "in bulk" pe toate comenzile simultan, ceea ce produce prea mult zgomot. Cand o comanda are produse complet diferite fata de factura, algoritmul forteaza match-uri absurde pe baza de pret.

Strategie propusa pentru sesiunea urmatoare

Abordare: subset → confirmare → generalizare

Pas 1: Identificare perechi comanda-factura cu CERTITUDINE

• Foloseste perechile unde clientul se potriveste EXACT (score > 0.9) si totalul e identic
• Aceste perechi au sanse mai mari sa aiba si articole corespunzatoare

Pas 2: Comparare manuala pe un subset mic (5-10 perechi)

• Alege perechi unde numarul de articole GoMag == numarul de articole ROA (fara transport/discount)
• Afiseaza side-by-side: GoMag SKU+produs+qty vs ROA codmat+produs+qty
• User-ul confirma manual care corespondente sunt corecte

Pas 3: Validare croise

• Un SKU care apare in mai multe comenzi trebuie sa se mapeze mereu pe acelasi id_articol
• Daca SKU X → id_articol Y in comanda A dar SKU X → id_articol Z in comanda B → marcheaza ca suspect

Pas 4: Generalizare doar pe mapari confirmate

• Extinde doar maparile validate pe subset la restul comenzilor
• Nu forta match-uri noi — lasa unresolved ce nu se confirma

Alt approach posibil: match pe DENUMIRE (fuzzy name match)

• In loc de pret, compara denumirea produsului GoMag cu denumirea articolului ROA
• Exemplu: "Lavazza Crema E Aroma Cafea Boabe 1 Kg" vs "LAVAZZA BBE CREMA E AROMA"
• Ar putea fi mai precis decat match pe pret, mai ales cand preturile coincid accidental

Tools (nota: scripturile de matching au fost sterse din repo)

Scripturile match_all.py, compare_order.py, fetch_one_order.py au fost eliminate. Strategia de matching descrisa mai sus ramane valida ca referinta conceptuala.

Structura Oracle relevanta

• vanzari — header factura (id_vanzare, numar_act, serie_act, data_act, total_cu_tva, id_part)
• vanzari_detalii — linii factura (id_vanzare, id_articol, cantitate, pret, pret_cu_tva)
• nom_articole — nomenclator articole (id_articol, codmat, denumire)
• comenzi — header comanda ROA (id_comanda, id_part, nr_comanda)
• comenzi_elemente — linii comanda ROA
• nom_parteneri — parteneri (id_part, denumire, prenume)
• ARTICOLE_TERTI — mapari SKU → CODMAT (sku, codmat, cantitate_roa, procent_pret)

Server

• SSH: ssh -p 22122 gomag@79.119.86.134
• App: C:\gomag-vending
• SQLite: C:\gomag-vending\api\data\import.db
• Oracle user: VENDING / ROMFASTSOFT / DSN=ROA