Panel klienta VulCode

VulCode è il nostro marchio, quindi abbiamo costruito questo pannello per noi stessi, e si è rivelato il cliente più difficile possibile. Quando costruisci qualcosa per te stesso, non c'è nessuno dietro cui nasconderti: ogni scorciatoia, ogni numero che non torna, ti ricade addosso direttamente. Per questo, fin dall'inizio, questo progetto doveva essere il modello di come appare un pannello cliente da noi, e non un ripiego per uso interno.

Il compito sembrava semplice: dare al cliente un unico posto in cui vede tutto ciò che lo riguarda e sbriga da solo le questioni che prima richiedevano un'e-mail. In pratica significava collegare più mondi in una volta sola - lo stato dei progetti, le fatture, i ticket di supporto e un programma di affiliazione che conta denaro reale - in un'unica schermata coerente che funziona allo stesso modo sulla scrivania e in tasca. Questo caso di studio mostra dove erano le vere trappole e come le abbiamo aggirate.

Prima del pannello, ogni domanda su una fase di progetto o su un documento finiva in un'e-mail, e la risposta dipendeva da chi la leggeva e se ricordava il contesto. Questo non scala nemmeno con una dozzina di clienti: la stessa informazione viveva nella casella di posta di una sola persona, e il cliente aspettava invece di guardare semplicemente.

Il pannello ribalta questo. Il cliente accede e ha subito davanti i suoi progetti con lo stato dei lavori, un elenco di fatture con ciò che è pagato e ciò che è dovuto, e la cronologia di tutti i ticket che ha mai aperto. Non c'è bisogno di scavare nulla nelle e-mail, perché la fonte di verità è un'unica vista, non la memoria di qualcuno.

L'effetto si sente da entrambe le parti. Il cliente smette di aspettare una persona per sapere cose che il sistema conosce già. Il team smette di rispondere alle stesse domande per la centesima volta, perché la risposta è già sullo schermo prima che qualcuno la digiti.

Un programma di affiliazione sembra innocuo finché non inizi a calcolare le commissioni su importi con i grosze. È lì che iniziano i drammi classici: il dieci per cento di 19.99 zł calcolato su un numero in virgola mobile può dare tre risultati leggermente diversi nell'elenco delle commissioni, nel portafoglio e sul pagamento, e allora i saldi non tornano più e nessuno si fida del pannello.

Per questo in tutto il pannello teniamo il denaro come numeri interi in grosze e calcoliamo ogni commissione su interi. Non c'è mai qui una frazione di złoty che potrebbe arrotondarsi una volta in un senso e una volta nell'altro. Un'operazione, una regola di arrotondamento per difetto, lo stesso risultato ovunque compaia questo importo.

Un pannello cliente mostra denaro e documenti, quindi la domanda "chi ha il diritto di vederlo" non è cosmetica. Il cliente deve vedere solo i propri dati, il team solo ciò a cui è autorizzato, e il confine tra loro non può dipendere dal fatto che il frontend abbia nascosto un pulsante.

L'abbiamo costruito su un controllo degli accessi basato sui ruoli e su un'autenticazione sicura, ma la decisione chiave è architetturale: l'ambito di ciò che si può vedere e fare è verificato dal backend all'ingresso dell'API, non dall'interfaccia. Il frontend può mostrare o nascondere ciò che vuole, ma se una richiesta riguarda i dati altrui, l'API la respinge prima ancora che raggiunga il database.

È lo stesso principio che applichiamo ovunque: si presidia il confine dove entrano i dati dall'esterno, cioè all'API, e non si conta sul fatto che l'utente non sostituisca un identificatore nell'indirizzo.

Il cliente non è sempre al computer. La fattura la controlla sul tram, a una notifica di ticket reagisce dal telefono. Costruire un'app mobile separata per questo significherebbe un secondo codice da mantenere e la certezza che prima o poi le due versioni divergano.

Invece il pannello è un'app web che si installa sul telefono come PWA, con un manifest e un service worker. Lo stesso codice, lo stesso backend, la stessa logica delle commissioni. Sul computer è un desktop completo, sul telefono un'icona sulla schermata iniziale e una finestra senza barra del browser, che si comporta come un'app nativa.

La cosa più facile è costruire un pannello che appaia bene su numeri preparati in anticipo. Appare bene finché qualcuno non clicca e si scopre che sotto non c'è nulla. Noi abbiamo preso la strada opposta: dal primo giorno il pannello poggia su un backend reale, e ogni schermata mostra ciò che è effettivamente nel database.

Questa scelta costa di più all'inizio, perché serve un'API funzionante prima che venga disegnato qualcosa. Ma ripaga subito, perché non c'è alcun momento "colleghiamo i dati più tardi" in cui di solito emergono tutte le ipotesi che non hanno superato il contatto con la realtà. Ciò che si vede nel pannello è ciò che il sistema sa davvero.

Il cliente ottiene un unico posto in cui vede il proprio stato e sbriga da solo le questioni che prima richiedevano un'e-mail al team. Entra, controlla un progetto, scarica una fattura, risponde a un ticket, guarda il saldo delle commissioni del programma di affiliazione, e se è in movimento fa lo stesso dal telefono, perché è la stessa app. Niente di tutto ciò dipende dal fatto che qualcuno del team sia alla casella di posta.

Dalla nostra parte il guadagno è altrettanto concreto. Il programma di affiliazione funziona senza che nessuno ricalcoli nulla a mano, perché è presidiato da codice su numeri interi, e non da un foglio di calcolo che qualcuno deve riconciliare. I saldi tornano, perché non c'è alcun punto in cui possa nascere un errore di arrotondamento. Il team recupera il tempo che prima andava nel rispondere alle stesse domande.

La cosa più importante, però, è che questo pannello è diventato il nostro modello. Il nucleo su cui poggia - ruoli, portafogli, commissioni, ticket, i18n, modalità app - è abbastanza pulito da essere stato trasferito su altri marchi senza riscrivere da zero. Abbiamo iniziato dal cliente più difficile, noi stessi, e ne è uscita un'architettura che poi abbiamo solo vestito di nuovi colori.