From 09a5403f835a4d439880f3bd5bd707a332d2ad06 Mon Sep 17 00:00:00 2001 From: Claude Agent Date: Tue, 17 Mar 2026 12:06:23 +0000 Subject: [PATCH] add: handoff notes for SKU mapping discovery session MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents what was tried, what worked (order-invoice matching), what failed (line item matching by price), and proposed strategy for next session (subset → confirm → generalize). Co-Authored-By: Claude Opus 4.6 (1M context) --- scripts/HANDOFF_MAPPING.md | 94 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 scripts/HANDOFF_MAPPING.md diff --git a/scripts/HANDOFF_MAPPING.md b/scripts/HANDOFF_MAPPING.md new file mode 100644 index 0000000..73344e3 --- /dev/null +++ b/scripts/HANDOFF_MAPPING.md @@ -0,0 +1,94 @@ +# 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 utile deja existente: +- `scripts/compare_order.py ` — comparare detaliata o comanda vs o factura +- `scripts/fetch_one_order.py ` — fetch JSON complet din GoMag API +- `scripts/match_all.py` — matching bulk (de refacut cu strategie noua) + +## 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