Hostwebo Billing — Architecture #

Sistema custom di fatturazione, pagamenti, abbonamenti e provisioning automatico. Sostituisce Upmind in 10 fasi sequenziali con cutover sicuro.

Obiettivo strategico #

Eliminare la dipendenza da Upmind mantenendo (e migliorando) tutte le sue funzioni:

• Catalogo piani hosting + domini + addon
• Carrello e checkout
• Pagamenti Stripe + PayPal
• Abbonamenti ricorrenti
• Fatture italiane SDI-compatibili (Aruba)
• Provisioning automatico Plesk
• Programma affiliazione
• Pacchetti crediti AI extra

Benefici:

• ~€300/anno risparmiati su Upmind
• Controllo totale UX e features
• Integrazione nativa con Plesk + WP Toolkit + AI Assistant
• Dashboard cliente più veloce (no API esterne)
• Libertà di iterare senza vincoli vendor

Principi architetturali #

1. Feature flag master + per-azione #

Due toggle indipendenti in admin:

• hwbi_billing_v2_enabled (default OFF)
• hwbi_upmind_enabled (default ON)

Più un selettore di modalità runtime:

• upmind_only — comportamento attuale (default)
• parallel — V2 attivo per beta-testers, Upmind per gli altri
• v2_new_only — V2 per nuovi clienti, Upmind per esistenti (target migrazione)
• v2_only — V2 totale (cutover finale)
• maintenance — entrambi OFF (solo per upgrade critici)

La classe HWBillingBillingBillingMode è la single source of truth che decide a runtime quale sistema gestisce ogni azione (checkout, fatturazione, provisioning).

2. Plugin separato, non monolitico #

hostwebo-billing è isolato da hostwebo-ai, hostwebo-dashboard, hostwebo-toolkit-pro. Vantaggi:

• Activate/deactivate indipendente
• Test in staging senza toccare AI/Dashboard
• Versionamento dedicato
• Migrazione/rollback chirurgica

3. State machine esplicita per ordini #

pending_payment → paid → provisioning → active
                                      ↓
                              suspended → cancelled → deleted

4. Idempotency webhook #

Stripe event_id + PayPal id salvati in wp_hwbi_payments.webhook_event_id con UNIQUE constraint. Riprocessare lo stesso evento non duplica nulla.

5. PCI/PSD2 compliance by delegation #

Usiamo Stripe Checkout (hosted page) + PayPal Orders v2 redirect. I dati carta MAI passano per il nostro server → zero compliance PCI-DSS richiesta.

6. Italian tax compliance from day 1 #

Tutte le fatture:

• Numerazione sequenziale per anno (immutabile)
• IVA 22% (override per regime forfettario)
• Snapshot dati cliente+fornitore al momento emissione
• PDF generato server-side (tcpdf)
• Trasmissione SDI via Aruba per B2B

Roadmap (10 fasi) #

Componenti chiave #

HWBillingBillingBillingMode #

Decision class. Riceve un context array e ritorna se l’azione va a V2 o Upmind.

if ( BillingMode::should_use_v2( ['action' => 'checkout', 'user_id' => $uid] ) ) {
    // route to V2 checkout
} else {
    // route to Upmind
}

HWBillingModelsPlanRepository #

CRUD per il catalogo prodotti. Usato da:

• Admin UI (AdminPlans)
• Theme importer (ThemePlanImporter)
• Checkout (Fase B)
• Stripe sync (Fase B)
• PayPal sync (Fase C)

HWBillingCoreInstaller #

DB schema completo creato al primo activate. 10 tabelle prefisso wp_hwbi_*:

• plans, orders, order_items, subscriptions, invoices, payments,

provisioning_jobs, coupons, affiliates, affiliate_commissions

HWBillingImporterThemePlanImporter #

Bulk import dei 12 piani esistenti dal tema hostwebo. Reads:

• hostwebo_defaults_cloud_eco() → categoria cloud_eco
• hostwebo_defaults_wp() → categoria wp
• hostwebo_defaults_ecommerce() → categoria ecommerce

Preserva upmind_pid in metadata.upmind_pid per audit durante cutover.

HWBillingCutoverCutoverReadiness (Phase J) #

14 pre-flight check programmatici prima di ogni transizione modalità:

• legal_data, stripe_config, paypal_config, at_least_one_gateway
• plans_imported, plans_synced_stripe, plans_synced_paypal
• plesk_plans_mapped, plesk_bridge_reachable, pages_exist
• v2_orders_count, no_failed_provisioning_jobs, aruba_sdi_configured, recent_audit_no_critical

Ogni check ritorna {status: pass|warn|fail, label, detail, blocker, meta}. recommend_next_mode() suggerisce la modalità target safe in base allo stato corrente.

HWBillingCutoverCustomerMigration (Phase J) #

• list_candidates() — utenti con hwdash_plesk_client_id (clienti Plesk esistenti)
• mark_user_as_upmind_legacy(int $user_id) — set _upmind_account_id user_meta a sentinel (legacy-pre-v2-{id})
• bulk_mark_existing_as_upmind() — chiama mark su tutti i candidates (idempotente)
• prefill_billing_meta(int $user_id) — popola hwbi_billing_* da WP profile

Da eseguire PRIMA di promuovere a MODE_V2_NEW così esistenti restano su Upmind.

HWBillingSubscriptionSubscriptionEngine (Phase E) #

State machine for recurring subscriptions:

active ─ payment_failed ──▶ past_due
past_due ─ payment_received ▶ active
past_due ─ 7d expires ──▶ suspended (Plesk suspend)
suspended ─ 14d expires ▶ cancelled

• mark_past_due(), mark_active(), mark_suspended(), mark_cancelled()
• Daily cron hwbi_subscription_renewal_check (04:00): drift detection + 7-day-ahead reminders
• Auto-reactivate Plesk service when subscription returns to active

HWBillingSubscriptionDunningManager (Phase E) #

Failed-payment escalation:

• Day 0: Reminder #1 (friendly tone) — fires immediately via hwbi_subscription_past_due action
• Day 3: Reminder #2 (urgent tone, “sospensione tra 4 giorni”)
• Day 7: Reminder #3 + Plesk suspend
• Day 14: Cancellation notice + subscription terminal

Daily cron hwbi_dunning_check (09:00). Resets fully when subscription returns to active.

HWBillingNotificationsDunningEmail (Phase E) #

4 branded HTML templates (amber → orange → red → gray) matching the WelcomeEmail visual system. Filterable via hwbi_dunning_schedule and hwbi_update_payment_method_url.

HWBillingDomainsDomainProvider interface (Phase H) #

Abstract registrar contract:

• check_availability(domain) → {available, premium, price_eur}
• register(domain, contact, years) → {transaction_id, registered_at, expires_at}
• set_nameservers(domain, [ns1, ns2])
• renew(domain, years)
• get_tld_pricing() → {tld: {register, renew, transfer}}

Implementations: NamecheapProvider (XML API, sandbox+live), StubProvider (no-op fallback). Selected via hwbi_domain_provider option + hwbi_domain_provider_slug filter.

HWBillingDomainsDomainManager (Phase H) #

Facade: resolves provider, runs operation, persists via DomainRepository, fires audit events. Auto-applies hwbi_default_nameservers filter (defaults: ns1.hostwebo.it, ns2.hostwebo.it).

HWBillingModelsDomainRepository (Phase H) #

Stores registered domains in single wp_options key hwbi_registered_domains. Keyed by lowercase FQDN. Methods: all(), get(), get_by_user(), get_by_subscription(), expiring_soon($days), upsert(), update_status(), stats().

HWBillingAdminAdminCutover (Phase J) #

Dashboard wp-admin → Hostwebo Billing → Cutover:

• Pre-flight checklist UI con status badges
• Modalità attuale + modalità consigliata (cards affiancate)
• Mode switcher manuale (V2_ONLY gated by can_promote_to_v2_only)
• Transition log (last 20 entries in wp_option hwbi_cutover_log)
• Customer migration section (lista candidates + bulk_mark_upmind button)
• Rollback instructions box inline

Vedi docs/cutover-playbook.md per la procedura step-by-step e docs/rollback-procedures.md per ogni scenario di emergenza.

Sicurezza #

• Capability custom manage_hwbi (concessa ad administrator)
• Tutti i admin-post.php handler verificano current_user_can() + check_admin_referer()
• Tutti i campi POST sanitizzati (sanitize_text_field, sanitize_key, esc_url_raw)
• Tutti gli output escapati (esc_html, esc_attr, esc_url)
• API keys in wp_options con autoload=false (no esposizione su ogni page load)
• Webhook signature verification (Stripe stripe-signature header, PayPal paypal-transmission-sig)
• Idempotency tramite UNIQUE constraint su webhook_event_id

Performance #

• Tutti gli wp_options del plugin con autoload=false (load solo quando serve)
• Tabelle con index su query patterns (user_id+status, status+created_at, gateway+reference)
• Provisioning queue async (worker cron) — l’utente non aspetta sul checkout
• Webhook handler veloce: accetta evento, enqueue async processing, restituisce 200 in <1s

Manutenzione automatica #

Fase E aggiungerà:

• Cron hwbi_subscription_renewal_check (daily): verifica abbonamenti in scadenza, invio reminder
• Cron hwbi_invoice_dunning_check (daily): retry pagamenti falliti con escalation (7d → 14d → suspend)
• Cron hwbi_provisioning_worker (1min): processa la coda provisioning con retry exponential backoff

Ecosistema Hostwebo — comunicazione inter-plugin #

┌─────────────────────────────────────────────────────────────────────┐
│  TEMA hostwebo                                                       │
│  • page-cloud-eco.php, page-wordpress-hosting.php, page-ecommerce   │
│  • hostwebo_render_plan_card() → CTA "Acquista ora"                 │
│  • hostwebo_checkout_url() → filter hostwebo_checkout_base_url      │
└──────────────────────────────┬──────────────────────────────────────┘
                               │ filter (B.2)
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│  hostwebo-billing (V2 — questo plugin)                              │
│  • BillingMode::should_use_v2() → decide se V2 o Upmind             │
│  • CheckoutController POST /checkout/stripe/create-session          │
│  • WebhookController POST /webhooks/stripe                          │
│  • ProvisioningWorker cron 1min                                     │
│  • Action hooks: hwbi_order_paid, hwbi_subscription_renewed, ...   │
└─────────┬───────────────┬───────────────────────────────────────────┘
          │               │
          │ PleskBridge   │ enqueue
          ▼               ▼
┌─────────────────┐   ┌──────────────────────────────────────────────┐
│ hostwebo-       │   │  hostwebo-ai                                  │
│ dashboard       │   │  • PackageRegistry::get_for_user             │
│ • Plesk_Api     │   │  • credits_charged_this_month                │
│ • Customer_     │   │  • add_action('hwbi_order_paid', ...)         │
│   Mapper        │   │    (Phase E: assegna pacchetto AI dopo pay) │
│ • client_create │   └──────────────────────────────────────────────┘
│ • domain_create │
│ • clients_list  │
└─────────────────┘
          ▲
          │ HMAC signed
          │
┌─────────────────┐
│ hostwebo-       │
│ toolkit-pro     │ (sui siti clienti)
│ • /theme/install│
│ • /diagnostic   │
│ • /backup       │
└─────────────────┘
          ▲
          │ external API
          │
   ╔═══════════════════════════════════╗
   ║ Plesk Server (srv1.hostwebo.cloud) ║
   ║ • REST v2 API                      ║
   ║ • Service plans                    ║
   ║ • Customer accounts                ║
   ║ • Domain provisioning              ║
   ╚═══════════════════════════════════╝

Punti di contatto chiave #

1. Tema → Billing (filter)

• hostwebo_checkout_base_url (filter): tema chiede al billing l’URL checkout corretto
• Billing risponde /v2-checkout/ SE BillingMode::should_use_v2() TRUE per l’utente
• Altrimenti restituisce default (path Upmind)

2. Billing → Dashboard (direct class consumption)

• HWBillingIntegrationsPleskBridge consuma HWDash_Customer_Mapper + HWDash_Plesk_Api
• Zero duplicazione: il plugin dashboard resta source of truth per config + encryption Plesk
• Bridge degrade gracefully se dashboard inattivo (WP_Error)

3. Billing → AI (action hooks)

• Quando hwbi_order_paid fires, hostwebo-ai (Phase E) può:
• Assegnare il pacchetto AI corrispondente al piano hosting
• Resettare crediti AI del mese
• Pre-popolare lista beta tester per Theme Studio
• hwbi_subscription_cancelled → revoca privilegi AI

4. Stripe → Billing (webhook HMAC)

• POST /wp-json/hostwebo-billing/v1/webhooks/stripe
• Signature v1=hmac_sha256(secret, ts.payload) con tolerance 5min
• Idempotency via UNIQUE constraint su webhook_event_id

5. Billing → Plesk (via Dashboard bridge)

• Sul hwbi_order_paid → enqueue provisioning_jobs job create_plesk_subscription
• Cron hwbi_provisioning_worker lo processa:

1. PleskBridge::auto_detect_client_id() (cerca per email)
2. Se non trova → PleskBridge::create_client() (POST /clients)
3. Phase D: create_domain($domain, $service_plan) (POST /domains)
4. Email credenziali al cliente

Riferimenti #

• Stripe Checkout docs
• Stripe Webhooks
• PayPal Orders v2 API
• PayPal Subscriptions API
• Plesk REST API
• Aruba SDI API
• Agenzia Entrate — specifiche tecniche fattura elettronica