Documentazione - GEM WooCommerce Integration

Introduzione

Il plugin GEM WooCommerce Integration consente di importare, generare e gestire prodotti in WooCommerce utilizzando un file CSV e una directory di immagini. È progettato per automatizzare l'aggiornamento di prodotti, prezzi, quantità di magazzino e immagini, ottimizzando il flusso di lavoro per negozi online.

Prerequisiti

• WordPress con WooCommerce attivo.
• Permessi di amministratore per accedere alla pagina di amministrazione del plugin.
• Un file CSV con i dati dei prodotti (SKU, nome, descrizione, prezzi, categorie, immagine, ecc.).
• Immagini dei prodotti nella directory /wp-content/uploads/gem_img/ con permessi di lettura/scrittura (755 per la directory, 644 per i file).
• PHP 8.2+ con debug abilitato per il monitoraggio degli errori (wp-config.php):

  define('WP_DEBUG', true);
  define('WP_DEBUG_LOG', true);
  define('WP_DEBUG_DISPLAY', false);

Funzioni Base

Il plugin offre una pagina di amministrazione (Integrazione GEM) con le seguenti azioni manuali:

Azione	Descrizione
Azzera Tabella Transito	Elimina tutti i dati dalla tabella temporanea wp_transito_prodotti.
Importa Prodotti da CSV	Carica i dati dei prodotti da un file CSV nella tabella wp_transito_prodotti.
Genera Prodotti WooCommerce	Crea o aggiorna i prodotti in WooCommerce basandosi sui dati della tabella.
Aggiorna Prezzi e Quantità	Aggiorna i prezzi e le quantità di magazzino dei prodotti esistenti.
Aggiorna Immagini Prodotti	Associa le immagini dalla directory gem_img ai prodotti in base agli SKU.
Elimina Prodotti con Disponibilità 0	Rimuove i prodotti con quantità di magazzino pari a 0.
Azzera Prodotti e Categorie	Elimina tutti i prodotti e le categorie da WooCommerce.

Ogni azione registra un log visibile nella sezione Log Operazioni della pagina di amministrazione.

Flusso di Lavoro Consigliato

Per utilizzare il plugin in modo efficace, segui questi passaggi:

1. Prepara il file CSV:
   • Includi colonne come: sku, name, description, short_description, categories (separate da virgole), stock_quantity, image_main (nome del file immagine, es. prodotto123.jpg), listino6, listino7, listino8, listino9, weight, lunghezza, larghezza, altezza, preordine (1 per abilitare), offerta (1 per prodotto in evidenza).
   • Esempio di riga CSV:

     sku,name,description,short_description,categories,stock_quantity,image_main,listino9,listino8
     ABC123,Prodotto Esempio,Descrizione completa,Descrizione breve,Categoria1,Categoria2,10,prodotto123.jpg,99.99,89.99

2. Carica le immagini:
   • Copia le immagini nella directory /wp-content/uploads/gem_img/.
   • Assicurati che i nomi dei file corrispondano esattamente ai valori nella colonna image_main del CSV.
3. Azzera la tabella transito (opzionale):
   • Clicca su Azzera Tabella Transito per pulire i dati precedenti.
4. Importa il CSV:
   • Clicca su Importa Prodotti da CSV e carica il file CSV.
   • Controlla il log per confermare che i dati siano stati importati correttamente.
5. Genera i prodotti:
   • Clicca su Genera Prodotti WooCommerce per creare o aggiornare i prodotti in WooCommerce.
   • Le immagini vengono automaticamente associate e cancellate dalla directory dopo l'upload.
6. Aggiorna prezzi e quantità (se necessario):
   • Se aggiorni solo prezzi o magazzino, clicca su Aggiorna Prezzi e Quantità.
7. Aggiorna immagini (se necessario):
   • Per aggiornare solo le immagini, clicca su Aggiorna Immagini Prodotti.
8. Gestisci prodotti esauriti:
   • Clicca su Elimina Prodotti con Disponibilità 0 per rimuovere i prodotti con magazzino a 0.
9. Pulizia completa (opzionale):
   • Per rimuovere tutti i prodotti e categorie, clicca su Azzera Prodotti e Categorie.

Funzionalità nel Dettaglio

Azzera Tabella Transito

Elimina tutti i record dalla tabella wp_transito_prodotti, utilizzata come buffer per i dati importati dal CSV.

• Quando usarla: Prima di importare un nuovo CSV per evitare dati duplicati.
• Risultato: Tabella vuota, pronta per una nuova importazione.

Importa Prodotti da CSV

Carica i dati da un file CSV nella tabella wp_transito_prodotti.

• Formato CSV: Deve includere colonne specifiche (es. sku, image_main).
• Validazione: I dati vengono sanitizzati per prevenire errori o problemi di sicurezza.
• Log: Mostra il numero di righe importate e eventuali errori.

Genera Prodotti WooCommerce

Crea o aggiorna i prodotti in WooCommerce utilizzando i dati della tabella wp_transito_prodotti.

• Funzionalità:
  • Crea nuovi prodotti o aggiorna quelli esistenti in base allo SKU.
  • Imposta nome, descrizione, prezzi, categorie, magazzino, peso, dimensioni, preordini e stato di evidenza.
  • Associa le immagini dalla directory gem_img e le cancella dopo l'upload.
  • Salva i listini (listino6, listino7, listino8, listino9) come metadati.
• Log: Mostra i prodotti creati, aggiornati e eventuali errori.

Aggiorna Prezzi e Quantità

Aggiorna solo i prezzi e le quantità di magazzino dei prodotti esistenti in WooCommerce.

• Quando usarla: Dopo aver importato un nuovo CSV con prezzi o quantità aggiornati.
• Risultato: Prezzi regolari, prezzi in offerta e quantità di magazzino aggiornati.

Aggiorna Immagini Prodotti

Associa le immagini ai prodotti in base ai nomi dei file nella directory gem_img.

• Funzionalità:
  • Scansiona la directory delle immagini.
  • Cerca il nome del file nella colonna image_main della tabella.
  • Associa l'immagine al prodotto corrispondente allo SKU.
  • Cancella l'immagine dalla directory dopo l'upload (opzionale, configurabile).
• Log: Mostra il numero di immagini associate e eventuali errori.

Elimina Prodotti con Disponibilità 0

Rimuove permanentemente i prodotti con quantità di magazzino pari a 0.

• Quando usarla: Per pulire il catalogo da prodotti esauriti.
• Risultato: I prodotti con _stock = 0 vengono eliminati.
• Attenzione: Questa azione è irreversibile.

Azzera Prodotti e Categorie

Elimina tutti i prodotti e le categorie da WooCommerce.

• Quando usarla: Per ripartire da zero con un nuovo catalogo.
• Risultato: Catalogo vuoto.
• Attenzione: Usa con cautela, azione irreversibile.

Risoluzione dei Problemi

Problema: Nessuna immagine viene associata

• Causa possibile: I nomi dei file in image_main non corrispondono ai file in /wp-content/uploads/gem_img/.
• Soluzione:
  • Verifica i valori di image_main:

    SELECT sku, image_main FROM wp_transito_prodotti WHERE image_main IS NOT NULL LIMIT 10;

  • Elenca i file nella directory:

    ls /var/www/html/wp-content/uploads/gem_img/

  • Assicurati che i nomi siano identici (inclusi maiuscole/minuscole).

Problema: Prodotti non creati o aggiornati

• Causa possibile: SKU non validi o dati mancanti nel CSV.
• Soluzione:
  • Controlla il log delle operazioni nella pagina di amministrazione.
  • Verifica i dati nella tabella:

    SELECT sku, name, stock_quantity FROM wp_transito_prodotti LIMIT 10;

  • Assicurati che il CSV contenga tutte le colonne richieste.

Problema: Errori di caricamento immagini

• Causa possibile: Permessi errati o formato immagine non supportato.
• Soluzione:
  • Verifica i permessi:

    chmod -R 755 /var/www/html/wp-content/uploads/gem_img/
    chmod -R 644 /var/www/html/wp-content/uploads/gem_img/*

  • Assicurati che le immagini siano in formato JPG, PNG, GIF o BMP.
  • Controlla il log di debug:

    cat /var/www/html/wp-content/debug.log

Problema: Immagini non cancellate dalla directory

• Causa possibile: Permessi di scrittura mancanti o file non esistente.
• Soluzione:
  • Verifica i permessi della directory (vedi sopra).
  • Controlla il log per errori specifici (es. Impossibile cancellare immagine...).

Problema: Prodotti con stock 0 non eliminati

• Causa possibile: Gestione del magazzino non attiva per alcuni prodotti.
• Soluzione:
  • Verifica i prodotti con stock 0:

    SELECT p.post_title, pm.meta_value AS stock
    FROM wp_posts p
    JOIN wp_postmeta pm ON p.ID = pm.post_id
    WHERE p.post_type = 'product' AND pm.meta_key = '_stock' AND pm.meta_value = 0;

  • Controlla il log per confermare l'eliminazione.

Torna all'inizio

Per ulteriori domande o supporto, contatta l'amministratore del sistema o consulta il log di debug in /var/www/html/wp-content/debug.log.