Modulo di estrazione dati e matching competitor

Documento di progetto per la validazione di un modulo indipendente che recupera prezzi competitor, verifica la corrispondenza dei prodotti e produce risultati auditabili prima dell'integrazione con una piattaforma di repricing.

Versione: 1.0 | Ambito: MVP tecnico e validazione su catalogo WooCommerce demo

Obiettivo

Il modulo non ha il compito di decidere il prezzo finale. Il suo ruolo e' fornire al sistema di repricing dati competitor affidabili, verificabili e ordinati per prodotto.

Per ogni prodotto del catalogo cliente, il modulo deve individuare competitor che vendono lo stesso articolo, estrarre prezzo, spedizione e disponibilita', e assegnare un livello di confidenza al match.

Principio guida: il sistema deve favorire match verificabili ed evitare falsi positivi. I casi senza segnali sufficienti vengono classificati come candidati o scartati, non usati automaticamente.

Perimetro del modulo

Incluso Non incluso nell'MVP
Lettura catalogo da WooCommerce API Calcolo del prezzo consigliato finale
Discovery competitor da Google Shopping e risultati organici Integrazione diretta nella piattaforma Next del cliente
Estrazione dati da pagine competitor Automazione completa su cataloghi grandi senza fase di tuning
Matching con score, livello e motivazione Accettazione automatica di match privi di evidenze
Dashboard/report verificabile Copertura garantita quando i competitor non espongono dati riconducibili

Flusso dati

WooCommerce cliente demo
        |
        v
Catalog Adapter
        |
        v
Formato prodotto standard
        |
        v
Discovery competitor
Google Shopping / Google organic / link manuali
        |
        v
Estrazione pagina competitor
title / meta title / JSON-LD / rich snippet / prezzo / spedizione
        |
        v
Normalizzazione
SKU, EAN, brand, titolo, modello, variante, colore, finitura
        |
        v
Matching e scoring
        |
        v
Report verificabile / API / dashboard

Dati prodotto in ingresso

Il catalogo cliente viene letto tramite WooCommerce API e convertito in un formato interno standard. L'Excel iniziale viene usato solo come dataset di validazione.

Campo Descrizione Origine tipica WooCommerce
sku Codice prodotto cliente o produttore product.sku
ean / gtin Identificatore univoco, se disponibile meta_data, attributi o plugin GTIN/EAN
title Nome prodotto cliente product.name
brand Marca attributo, tassonomia o campo custom
attributes Modello, colore, finitura, misura, variante product.attributes e meta_data
url URL prodotto cliente product.permalink

Matching e livelli di confidenza

Il matching non si basa su un solo campo. Il modulo raccoglie segnali multipli dalla pagina competitor e li normalizza per gestire differenze di punteggiatura, spazi, separatori e formulazioni commerciali.

Livello Descrizione Uso consigliato
EXACT EAN/GTIN uguale oppure SKU produttore verificato nella pagina competitor. Utilizzabile automaticamente dal repricer.
STRONG Brand, modello e variante coincidono dopo normalizzazione; mancano identificatori forti ma le evidenze sono coerenti. Utilizzabile sopra soglia o dopo validazione iniziale.
CANDIDATE Possibile corrispondenza, ma segnali incompleti o ambigui. Da inviare a revisione manuale.
REJECTED Prodotto diverso, variante diversa o segnali insufficienti. Escluso dal repricing.

Esempio di normalizzazione

I codici 115.629.SJ.1, 115629SJ1 e 115 629 SJ 1 vengono ricondotti alla stessa forma normalizzata. Lo stesso approccio viene applicato a brand, modello, colore e finitura.

Evidenze per ogni match

Ogni risultato deve essere auditabile. Il cliente deve poter controllare non solo il prezzo trovato, ma anche il motivo per cui il competitor e' stato associato al prodotto.

Elemento Contenuto
URL competitor Pagina prodotto o scheda venditore trovata.
Fonte Google Shopping, Google organic o link manuale.
Dati estratti Titolo, meta title, JSON-LD, rich snippet, prezzo, spedizione, disponibilita'.
Segnali di match EAN, SKU, brand, modello, variante, colore, finitura e token titolo.
Decisione Livello di confidenza, score numerico e motivazione.
Scarti Motivo dell'esclusione dei candidati non validi.

Ambiente di validazione

La validazione puo' essere realizzata su un ambiente separato gia' disponibile sul server Hetzner esistente.

project2209.com
  WooCommerce demo con prodotti test

matcher.project2209.com
  Dashboard e API del modulo matching

/opt/price-matcher
  Servizi applicativi isolati
  Database
  Code di lavoro
  Evidenze estratte

Il sottodominio matcher.project2209.com ospita il modulo e la documentazione, mentre project2209.com resta il catalogo WooCommerce demo da cui leggere i prodotti tramite API.

Architettura MVP

Componente Responsabilita'
WooCommerce Adapter Legge i prodotti dal catalogo demo via REST API e mappa i campi nel formato interno.
Discovery Worker Recupera candidati competitor da DataForSEO, Google Shopping, risultati organici e link manuali.
Extractor Scarica o visita le pagine competitor ed estrae dati strutturati e visibili.
Matcher Normalizza segnali, calcola score e genera spiegazione del match.
Storage Salva prodotti, candidati, risultati, log ed evidenze.
Dashboard Permette di verificare prodotto per prodotto match, candidati, scarti e prezzi.

Milestone proposte

  1. Setup ambiente demo: sottodominio, protezione accesso, runtime applicativo, database e struttura progetto.
  2. Catalogo WooCommerce: caricamento dei prodotti test, configurazione SKU, EAN, brand e attributi.
  3. Import prodotti: lettura via API WooCommerce e normalizzazione in formato interno.
  4. Prima discovery competitor: ricerca candidati da Google Shopping/organic o fonti equivalenti.
  5. Estrazione e matching: raccolta segnali, scoring, classificazione e motivazione.
  6. Report verificabile: dashboard o export con match, prezzi, spedizione, confidence ed evidenze.
  7. Valutazione: precisione, falsi positivi, copertura automatica e costi di esecuzione.

Criteri di successo MVP

Criterio Misura
Verificabilita' Ogni match mostra segnali, score e motivazione.
Riduzione falsi positivi I prodotti con variante diversa vengono scartati o classificati come candidati.
Copertura automatica Il modulo recupera un numero utile di competitor senza inserimento manuale.
Gestione casi dubbi I match ambigui non entrano automaticamente nel repricing.
Scalabilita' iniziale La pipeline e' compatibile con cataloghi da centinaia o migliaia di SKU tramite batching e code.

Prossimi passi operativi

  1. Attivare il sottodominio matcher.project2209.com.
  2. Preparare una cartella separata sul server, per esempio /opt/price-matcher.
  3. Proteggere il sottodominio con autenticazione base o accesso ristretto.
  4. Caricare il catalogo demo su WooCommerce usando i prodotti test.
  5. Creare chiavi WooCommerce REST API in sola lettura.
  6. Implementare il primo import da WooCommerce.
  7. Generare il primo report verificabile sui prodotti test.