Stati di abbonamento recuperabili per un SaaS

Un provider di pagamenti può confermare un addebito in ritardo, inviare lo stesso evento più di una volta o lasciare un'operazione elaborata solo a metà. Per questo, «pagato» e «con accesso» non sono equivalenti. Se il permesso di un account dipende direttamente dall'ultima risposta ricevuta da una API di pagamenti, un guasto transitorio può bloccare un cliente che ha effettivamente pagato o abilitare un altro il cui addebito è poi fallito.

Negli stati di abbonamento in SaaS PHP, l'obiettivo non è memorizzare un'unica etichetta in una tabella. È costruire un processo recuperabile: ogni decisione deve avere un'evidenza, un responsabile, una transizione valida e un modo per riconciliarsi quando arrivano nuovi dati.

Definire le regole di prodotto prima del modello tecnico

Il modello dati non risolve le ambiguità commerciali. Prima di progettare entità o webhook, prodotto, finanza e operations devono concordare cosa accade in ogni situazione rilevante.

• Attivazione: l'accesso viene concesso prima che il primo pagamento sia confermato, dopo un'autorizzazione o solo dopo il regolamento?
• Rinnovo: quando inizia il periodo di grazia e quali capacità vengono mantenute durante tale periodo?
• Mancato pagamento: sono previsti tentativi automatici, avvisi, restrizioni parziali o sospensione completa?
• Cancellazione: l'accesso termina immediatamente o alla fine del periodo già sottoscritto?
• Rimborso o contestazione: richiede un blocco immediato, una revisione manuale o la revoca alla conferma di un esito?
• Riattivazione: ripristina esattamente il piano precedente, crea un nuovo ciclo commerciale o richiede una convalida operativa?

È inoltre opportuno distinguere una cancellazione richiesta dal cliente da una cancellazione effettiva. La prima esprime un'intenzione; la seconda modifica il diritto futuro di accesso. Confonderle provoca interfacce poco chiare e automazioni difficili da correggere.

Separare contratto, addebito e accesso effettivo

Un'architettura manutenibile rappresenta almeno quattro concetti. L'account identifica il titolare e i suoi membri. Il contratto commerciale descrive piano, prezzo concordato, data di rinnovo e decisione di cancellare. Il ciclo di addebito rappresenta un'obbligazione concreta per un periodo, il suo importo e il suo esito. Infine, le capacità abilitate materializzano ciò che l'account può fare all'interno del prodotto.

Questa separazione evita di trasformare un provider di pagamenti nell'unica fonte di verità dell'intero SaaS. Un ciclo può essere in sospeso mentre il contratto resta valido per il periodo di grazia. Al tempo stesso, un account può mantenere l'accesso in lettura, ma non poter creare nuove risorse. Le capacità consentono di esprimere questa decisione senza forzare una falsa dicotomia tra attivo e inattivo.

In PHP, un'applicazione può esporre un servizio di autorizzazione che consulta una proiezione locale delle capacità, per esempio canCreateProject o canExportData. Tale proiezione viene aggiornata quando cambiano i fatti commerciali o di addebito; non deve invocare il provider a ogni richiesta. In questo modo si riducono latenza, dipendenza esterna e dispersione di condizionali tra controller, code e attività pianificate.

Modellare transizioni, responsabili ed evidenze

Eviti un unico campo status con valori aggiunti man mano che emergono incidenti. È preferibile dichiarare stati per aggregato e transizioni consentite. Per esempio, un ciclo di addebito può passare da open a payment_pending, paid, failed, refunded o disputed. Non ogni transizione è reversibile né qualsiasi attore può eseguirla.

Ogni modifica deve conservare data, origine, identificatore esterno quando presente ed evidenza. L'origine può essere un ordine interno, un webhook convalidato, una query di riconciliazione o un'azione manuale autorizzata. Una correzione del supporto non deve sovrascrivere silenziosamente la cronologia: deve essere registrata come una decisione distinta, con motivazione e operatore responsabile.

Priorità in caso di informazioni contraddittorie

Definisca quale prova prevale. Una schermata di reindirizzamento dopo il pagamento non dovrebbe confermare un ciclo: serve a informare l'utente, non come evidenza finale. Un webhook firmato e verificato fornisce di norma un segnale migliore, ma può arrivare tardi. Una query autenticata al provider durante la riconciliazione può chiarire eventi assenti. Se due fonti discordano, il sistema deve passare alla revisione o a uno stato di attesa definito, non scegliere arbitrariamente il dato più recente.

Elaborare eventi tardivi, duplicati e incompleti

La ricezione di un evento deve essere idempotente. Conservi un identificatore stabile dell'evento esterno e un hash o un riferimento del payload rilevante. Se viene ricevuto di nuovo, risponda senza ripetere l'effetto di business. Questo è particolarmente importante se un evento di pagamento attiva l'emissione di un documento, l'estensione del periodo o una notifica.

L'elaborazione deve separare ricezione e applicazione. Prima, convalidi firma, schema e provenienza; poi, memorizzi in modo persistente l'evento ricevuto; infine, elabori un'attività che tenta di applicare la transizione. Se il processo si interrompe dopo aver persistito l'evento, una coda o un processo di recupero può riprenderlo. Se fallisce prima di persistere, la riconciliazione dovrà rilevare la differenza confrontando i cicli interni con la fonte esterna.

evento ricevuto → convalida → registrazione persistente → applicazione idempotente
                                      ↓
                              nuovo tentativo o riconciliazione

Non presuma un ordine di consegna. Un rimborso può arrivare prima di una conferma tardiva del pagamento originale. Le regole devono valutare lo stato corrente, i riferimenti dell'operazione e la sequenza nota, lasciando i casi impossibili o ambigui in una coda di revisione. Applicare ciecamente «l'ultimo evento ricevuto» è una causa comune di permessi errati.

Riconciliazione e permessi come proiezione controllata

La riconciliazione periodica non è una toppa; è parte del design. Deve individuare cicli aperti da troppo tempo, pagamenti confermati al di fuori del sistema, eventi registrati ma non elaborati, riferimenti esterni duplicati e capacità che non corrispondono al contratto vigente. Quando rileva una differenza, registra il riscontro e applica una transizione tracciabile, invece di aggiornare direttamente i campi.

La proiezione delle capacità deve avere regole esplicite. Per esempio, un contratto vigente con un ciclo scaduto ma ancora nel periodo di grazia può mantenere funzioni essenziali; al termine della grazia, può rimuovere le operazioni di scrittura. Quando viene confermato un pagamento tardivo, il sistema riattiva le capacità previste dal piano e conserva la cronologia della restrizione precedente.

Una cache dei permessi può essere utile, ma richiede invalidazione quando cambia la proiezione e un limite di validità. L'autorizzazione critica non deve neppure basarsi soltanto sui dati memorizzati nel browser. Il server deve decidere in base alla capacità vigente e al corretto ambito di account, utente e risorsa.

Backoffice, audit e test di recupero

Il team di supporto deve poter vedere, senza modificare record del database, il contratto, i cicli, gli eventi esterni, le transizioni applicate, le capacità correnti e le azioni manuali. Deve poter richiedere una riconciliazione, ritentare un evento sicuro e aprire una revisione. Le correzioni che alterano accesso o saldo richiedono permessi differenziati, motivazione obbligatoria e registro di audit.

Verifichi il flusso come una sequenza di guasti, non solo come un pagamento corretto. Includa rinnovo confermato, pagamento incerto, duplicati, eventi fuori ordine, rimborso, cancellazione alla fine del periodo e riattivazione. Verifichi sia il risultato finale sia che nessun nuovo tentativo crei due periodi, due documenti o una doppia estensione dei permessi.

Un caso ipotetico: un ciclo scade, l'addebito resta in sospeso e l'account entra nel periodo di grazia con capacità limitate. Il webhook di conferma non viene elaborato a causa di un'interruzione temporanea, ma l'evento resta registrato. Un nuovo tentativo idempotente conferma il ciclo, estende il contratto e ricompone le capacità. Se l'evento non fosse arrivato, la riconciliazione individuerebbe l'operazione esterna confermata e genererebbe la stessa transizione con la propria evidenza.

Segnali di allerta e checklist

Misura gli account con contratto e capacità incoerenti, i cicli scaduti senza decisione, gli eventi non elaborati, i tentativi esauriti, le differenze rilevate dalla riconciliazione e la frequenza delle modifiche manuali. Un aumento delle correzioni manuali indica di norma regole insufficienti, non soltanto un problema operativo.

• Contratto, ciclo di addebito e capacità sono entità separate?
• Ogni transizione ha attore, evidenza, data e motivazione?
• Gli eventi esterni sono idempotenti e vengono salvati prima di essere applicati?
• Esiste una riconciliazione in grado di recuperare operazioni incomplete?
• I permessi vengono calcolati da una proiezione locale e non da una risposta di pagamento in tempo reale?
• Il supporto può indagare e correggere con audit, senza modifiche dirette in produzione?
• I test coprono ritardi, duplicati, disordine e contraddizioni?

Un modello recuperabile non elimina i guasti esterni. Li rende rilevabili, circoscritti e correggibili senza trasformare un incidente di addebito in una perdita di controllo sull'accesso al prodotto.