Panel klienta VulCode

VulCode es nuestra propia marca, así que construimos este panel para nosotros mismos, y resultó ser el cliente más difícil posible. Cuando construyes algo para ti mismo, no hay nadie detrás de quien esconderse: cada atajo, cada número que no cuadra, te vuelve directamente. Por eso, desde el principio, este proyecto debía ser la plantilla de cómo es un panel de cliente en nuestra casa, y no un apaño para uso interno.

La tarea sonaba sencilla: dar al cliente un único lugar donde vea todo lo que le concierne y resuelva por sí mismo los asuntos que antes requerían un correo. En la práctica significaba conectar varios mundos a la vez - el estado de los proyectos, las facturas, los tickets de soporte y un programa de afiliados que cuenta dinero real - en una única pantalla coherente que funciona igual en el escritorio y en el bolsillo. Este caso de estudio muestra dónde estaban las verdaderas trampas y cómo las sorteamos.

Antes del panel, cada pregunta sobre una fase de proyecto o un documento terminaba en un correo, y la respuesta dependía de quién lo leía y de si recordaba el contexto. Eso no escala ni siquiera con una docena de clientes: la misma información vivía en la bandeja de entrada de una sola persona, y el cliente esperaba en lugar de simplemente mirar.

El panel le da la vuelta. El cliente inicia sesión y tiene de inmediato ante sí sus proyectos con el estado de los trabajos, una lista de facturas con lo pagado y lo pendiente, y el historial de todos los tickets que haya abierto alguna vez. No hay que rebuscar nada en los correos, porque la fuente de verdad es una única vista, y no la memoria de alguien.

El efecto se nota en ambos lados. El cliente deja de esperar a una persona para enterarse de cosas que el sistema ya conoce. El equipo deja de responder las mismas preguntas por centésima vez, porque la respuesta ya está en pantalla antes de que nadie la escriba.

Un programa de afiliados parece inocente hasta que empiezas a calcular comisiones sobre importes con grosze. Ahí empiezan los dramas clásicos: el diez por ciento de 19.99 zł calculado sobre un número de coma flotante puede dar tres resultados ligeramente distintos en la lista de comisiones, en el monedero y en el pago, y entonces los saldos dejan de cuadrar y nadie se fía del panel.

Por eso en todo el panel mantenemos el dinero como números enteros en grosze y calculamos cada comisión sobre enteros. Nunca hay aquí una fracción de złoty que pudiera redondearse una vez hacia un lado y otra vez hacia el otro. Una operación, una regla de redondeo a la baja, el mismo resultado en todos los sitios donde aparece ese importe.

Un panel de cliente muestra dinero y documentos, así que la pregunta "quién tiene derecho a ver esto" no es cosmética. El cliente debe ver únicamente sus propios datos, el equipo solo aquello a lo que está autorizado, y la frontera entre ellos no puede depender de que el frontend haya ocultado un botón.

Lo construimos sobre un control de acceso basado en roles y una autenticación segura, pero la decisión clave es arquitectónica: el alcance de lo que se puede ver y hacer lo comprueba el backend a la entrada de la API, no la interfaz. El frontend puede mostrar u ocultar lo que quiera, pero si una petición afecta a datos ajenos, la API la rechaza antes incluso de llegar a la base de datos.

Es el mismo principio que aplicamos en todas partes: se vigila la frontera donde entran los datos desde fuera, es decir, en la API, y no se cuenta con que el usuario no cambie un identificador en la dirección.

El cliente no está todo el tiempo ante el ordenador. La factura la revisa en el tranvía, a una notificación de ticket reacciona desde el teléfono. Construir una app móvil aparte para eso significaría un segundo código que mantener y la certeza de que tarde o temprano las dos versiones se separan.

En su lugar, el panel es una app web que se instala en el teléfono como PWA, con un manifiesto y un service worker. El mismo código, el mismo backend, la misma lógica de comisiones. En el ordenador es un escritorio completo, en el teléfono un icono en la pantalla de inicio y una ventana sin barra de navegador, que se comporta como una app nativa.

Lo más fácil es construir un panel que se vea bien sobre números preparados de antemano. Se ve bien hasta que alguien hace clic y resulta que debajo no hay nada. Nosotros fuimos por el camino contrario: desde el primer día el panel se apoya en un backend real, y cada pantalla muestra lo que hay realmente en la base de datos.

Esa elección cuesta más al principio, porque hace falta una API funcional antes de dibujar nada. Pero se amortiza de inmediato, porque no hay un momento de "los datos los conectamos luego" en el que suelen aflorar todas las suposiciones que no sobrevivieron al contacto con la realidad. Lo que se ve en el panel es lo que el sistema sabe de verdad.

El cliente obtiene un único lugar donde ve su estado y resuelve por sí mismo los asuntos que antes requerían un correo al equipo. Entra, revisa un proyecto, descarga una factura, responde en un ticket, mira el saldo de comisión del programa de afiliados, y si va de camino hace lo mismo desde el teléfono, porque es la misma app. Nada de esto depende de que alguien del equipo esté en la bandeja de entrada.

En nuestro lado la ganancia es igual de concreta. El programa de afiliados funciona sin que nadie recalcule nada a mano, porque lo vigila código sobre números enteros, y no una hoja de cálculo que alguien tenga que cuadrar. Los saldos coinciden, porque no hay ningún punto donde pudiera nacer un error de redondeo. El equipo recupera el tiempo que antes se iba en responder las mismas preguntas.

Lo más importante, sin embargo, es que este panel se convirtió en nuestra plantilla. El núcleo sobre el que se apoya - roles, monederos, comisiones, tickets, i18n, modo app - es lo bastante limpio como para haberse trasladado a otras marcas sin reescribir desde cero. Empezamos por el cliente más difícil, nosotros mismos, y de ahí salió una arquitectura que luego solo vestimos con nuevos colores.