Cutover Playbook — Upmind → Hostwebo Billing V2 #

Procedura passo-passo per la migrazione progressiva da Upmind al sistema V2. Fasi pensate per essere reversibili in ogni momento.

Filosofia #

• Mai un big-bang. Si passa per modalità intermedie testate.
• Rollback sempre disponibile. Click → “Solo Upmind” annulla qualsiasi cambio.
• Tutto loggato. Ogni transizione modalità è nel log + audit.
• Cliente non si accorge di nulla quando il cutover è ben fatto.

Stato attuale del sistema #

Verifica via wp-admin → Hostwebo Billing → Cutover:

• Modalità attuale
• Pre-flight checklist (14 check programmatici)
• Lista candidati migrazione

Le 5 modalità — quando usarle #

Procedura standard (1-3 mesi) #

Fase 1: Setup tecnico (0-7 giorni) #

Goal: ottenere TUTTI i pre-flight check PASS prima di toccare la modalità.

1. Impostazioni → Compila dati legali completi

• Ragione sociale, P.IVA, C.F., REA, indirizzo, PEC, codice SDI, IBAN

1. Crea account Stripe live + recupera sk_live_… + pk_live_…

• Crea webhook su https://dashboard.stripe.com/webhooks
• URL: https://www.hostwebo.it/wp-json/hostwebo-billing/v1/webhooks/stripe
• Eventi: checkout.session.completed, invoice.paid, invoice.payment_failed, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted
• Copia whsec_… → Impostazioni

1. Crea app PayPal live + recupera credentials

• Crea webhook su PayPal Developer Dashboard
• URL: https://www.hostwebo.it/wp-json/hostwebo-billing/v1/webhooks/paypal
• Eventi: PAYMENT.CAPTURE.COMPLETED, PAYMENT.SALE.COMPLETED, BILLING.SUBSCRIPTION.*
• Copia WH-… → Impostazioni

1. Piani → Importa dal tema → 12 piani caricati
2. Piani → “Sync to Stripe (all)” → tutti i Products/Prices creati
3. Piani → “Sync to PayPal (all)” → tutti i Products/Billing Plans creati
4. Verifica Plesk service plan mappati per ogni piano hosting
5. Vai su Cutover → checklist deve essere tutti PASS (warning OK)

Rollback se serve: semplicemente lascia modalità “Solo Upmind”. Niente è cambiato per i clienti.

Fase 2: Beta testing parallelo (7-21 giorni) #

Goal: validare il flow end-to-end con casi reali.

1. Cutover page → Promuovi a “Parallelo” (un click)
2. Impostazioni → Aggiungi tuo user_id alla lista beta tester
3. Esegui ordine test reale (carta vera, importo ridotto se possibile)

• Frontend cliente → /cloud-eco/ → click “Acquista”
• Sei rediretto a /v2-checkout/ (non Upmind)
• Compila billing + dominio → paga con Stripe (test mode = ok per inizio)
• Verifica /v2-grazie/ timeline si completa
• Verifica fattura su /v2-fattura/?numero=2026/0001
• Verifica Plesk subscription creato
• Verifica email benvenuto ricevuta

1. Aggiungi 2-3 amici/clienti fidati alla beta list → ripetere
2. Monitor: Hostwebo AI → Audit Log filtra per hwbi_* → cerca errori
3. Run cutover checks settimanalmente → tutti devono restare PASS

Rollback se serve: Cutover → “Solo Upmind”. Gli ordini V2 esistenti restano in DB ma il flow checkout torna a Upmind.

Fase 3: V2 per nuovi (21-60 giorni) #

Goal: tutti i nuovi clienti vanno su V2. Esistenti restano stabili.

1. PRIMA di cambiare modalità: Cutover page → click “⚡ Marca tutti come legacy Upmind”

• Imposta _upmind_account_id user_meta su tutti gli utenti con Plesk client_id mappato
• Idempotente. Audit customer_bulk_upmind_marked.

1. Cutover → Promuovi a “V2 per nuovi”
2. Da ora:

• Nuovi visitatori che fanno checkout → V2
• Clienti esistenti che entrano in dashboard → vedono Upmind data

1. Monitor 30+ giorni che:

• Nuovi clienti completano onboarding senza problemi
• Provisioning Plesk funziona per ogni nuovo ordine
• Webhook Stripe/PayPal arrivano e processano
• Fatture emesse + numerazione corretta

1. Audit log review settimanale

Rollback se serve: Cutover → “Solo Upmind”. Restano tutti i dati. Solo il flow per nuovi clienti torna a Upmind.

Fase 4: Migrazione clienti esistenti (60-90 giorni) #

Goal: spostare progressivamente ogni cliente esistente da Upmind a V2.

Per ora questa fase è manuale per cliente. La proceduratipica:

1. Per ogni cliente con subscription Upmind attiva:

• Contattali via email annunciando la migrazione (template fornito separatamente)
• Genera invoice manuale finale Upmind
• Crea nuova subscription V2 con il loro nuovo metodo di pagamento (Stripe o PayPal)
• Una volta confermata la prima fattura V2 → cancella Upmind subscription

1. Aggiorna _upmind_account_id user_meta a stringa vuota (così V2 li prende)
2. Strumento dedicato (Phase J2 — futuro): wizard customer-side per auto-migrazione

Quando hai migrato ≥80% clienti, vai a Fase 5.

Fase 5: Cutover totale (Day 90+) #

Pre-requisiti:

• ≥5 ordini V2 in stato paid/active
• Tutti i check Cutover devono essere PASS (no blocker)
• Zero errori critici in audit log negli ultimi 7 giorni
• Decisione consapevole: dopo questo passo Upmind è OFF

Passi:

1. Cutover → Promuovi a “V2 cutover totale”

• Sistema imposta automaticamente hwbi_upmind_enabled = false
• Tutti i checkout vanno a V2

1. Verifica frontend che pagine prezzi mostrino “Acquista” → /v2-checkout/
2. Verifica dashboard cliente che mostri tab “Fatturazione V2” come primaria
3. Monitor 7 giorni che non ci siano regressioni
4. Una volta sereno: vedi Fase 6

Fase 6: Decomissione Upmind (Day 97+) #

Pre-requisiti: 7+ giorni in V2 only senza problemi.

1. Backup completo del DB (Plesk → Database → Backup)
2. Plugin Upmind:

• Deattivare dal wp-admin
• NON cancellare ancora (mantieni per ~30gg per audit)

1. Cancella subscription Upmind dal loro pannello
2. Risparmio: €25/mese × 12 = €300/anno reinvestibili in altro
3. Dopo 30 giorni senza problemi → cancella plugin Upmind definitivamente

Edge cases #

Cliente paga con Upmind + ha problemi → rollback urgente #

1. Cutover → “Solo Upmind” (1 click, 5 secondi)
2. Cliente è subito sul flow legacy
3. Investiga via audit log

V2 cutover totale ma scopri un bug critico → rollback #

1. Cutover → “Solo Upmind”
2. I clienti che hanno già ordini V2 attivi: i loro rinnovi continuano a essere processati dai webhook (V2 NON deve essere disabilitata completamente, solo la modalità è solo_upmind ma il codice continua a girare per webhook in arrivo)
3. Importante: NON disattivare il plugin hostwebo-billing, solo cambiare la modalità

Pagamento webhook arriva quando il sistema è in “Solo Upmind” #

• Il WebhookController accetta sempre eventi (signature valida)
• Anche se BillingMode è upmind_only, eventuali ordini V2 già paid continuano a essere processati
• È SICURO

Riferimenti rapidi #