Dos fases en un sistema en producción: pipeline, documentos y financiero en JV Elétrica

JV Elétrica trabaja con proyectos de micro generación distribuida — energía solar — y ya tenía un sistema propio en el aire, con 137 proyectos registrados y clientes usando el portal a diario. El pedido no era construir algo nuevo. Era corregir lo que estaba roto y extender lo que faltaba, sin parar la operación.

La decisión de entrada

Ninguna stack nueva fue introducida. No recreamos la autenticación, no recreamos el schema, no propusimos migración de plataforma. Todo el trabajo fue incremental sobre el sistema que ya corría en producción.

Esa es una decisión de riesgo, no de pereza. Un sistema con 137 proyectos activos y clientes finales enviando documentos no es ambiente para reescritura. Y antes de cualquier alteración de schema, backup completo de la base — compromiso asumido con el cliente en la primera conversación y cumplido en todas las rondas.

Fase 1: los bugs que nadie había encontrado

El alcance original tenía cuatro bugs mapeados. Uno de ellos era un documento técnico que se trababa: después de que el cliente final enviaba el PDF firmado, el registro entraba en estado de validación y ya no podía ser borrado ni corregido por nadie. Si el archivo estaba equivocado, el flujo simplemente paraba.

Otro era más sutil: el servidor corría en huso de Berlín, y todos los horarios exhibidos en el sistema estaban desplazados — no solo en la pantalla de auditoría, sino en todos lados. Fue corregido en el origen, no maquillado pantalla por pantalla.

Durante la ejecución aparecieron dos problemas que no estaban en la lista. El enlace de descarga de archivos expiraba en una hora y fallaba en silencio — quien intentara abrirlo después no recibía error, simplemente no funcionaba. Y el formato de números no seguía el estándar brasileño, lo que solo se hizo visible a través de una captura enviada por el cliente después de la entrega.

El formulario de datos del proyecto

La entrega central de la primera fase fue un formulario completo en modal, con cinco bloques: tipo de proyecto, datos del cliente, unidad generadora, informaciones de la generadora y unidades beneficiarias. Cargas de documento, factura de energía, foto del tablero de medición, disyuntor y fachada.

Dos detalles definieron su calidad. La potencia total del generador y de los inversores se calcula en tiempo real conforme el usuario escribe cantidad y potencia — sin botón de calcular, sin recargar. Y la suma de los porcentajes de las unidades beneficiarias debe cerrar exactamente en 100%, con el envío bloqueado mientras no cierre. Es una regla del dominio, no una validación genérica de formulario.

Qué apareció en el soporte

Durante los siete días de soporte, el cliente reportó que un usuario final había enviado el documento equivocado y no lograba removerlo. La causa raíz era la misma regla del bug original: después de firmado, el registro desaparecía de las opciones de corrección tanto para el admin como para el cliente. Existía un rodeo por el panel administrativo, pero no era self-service ni obvio.

La corrección fue un botón de cancelar envío y reenviar, disponible al cliente final mientras el documento aguarda validación. Al confirmar, el archivo equivocado se descarta, el registro vuelve al estado anterior y el cliente reenvía de inmediato, sin depender del admin — que recibe notificación in-app de la cancelación. Migration aditiva en la base, con backup antes.

Corregir el síntoma habría sido devolver el botón de borrar al admin. Corregir el problema fue devolver la autonomía a quien cometió el error.

Fase 2: panel, pipeline y financiero

La segunda fase entró por contrato directo, con cinco ítems. Panel de usuarios en el admin, con cambio de foto, teléfono, redefinición de contraseña y exclusión. Nuevo estadio de inspección reprobada en el pipeline de proyectos. Formulario simplificado de creación de proyecto — solo nombre y observación — manteniendo el formulario completo intacto.

Y la parte financiera: dashboard con sistema de colores para lectura rápida de saldo y estado, filtro de proyectos con saldo deudor, visualización del saldo total por el propio usuario, y un botón de cobranza que dispara un correo con el resumen consolidado de la cuenta del cliente.

Qué encontró la prueba del cliente

El cliente probó el mismo día de la entrega y señaló seis ítems. Vale registrarlo, porque es donde aparece el trabajo real.

La carga de foto de usuario fallaba por dos motivos en secuencia: primero un encabezado de protección ausente en la petición; después de corregir eso, una carpeta de almacenamiento en el servidor con dueño equivocado, que impedía al servicio escribir. El correo del nuevo estadio de inspección reprobada no disparaba porque el estado recién creado nunca había sido mapeado en el sistema de notificaciones — sin evento, sin correo.

Y la foto del usuario no aparecía en el encabezado del portal por un bug bastante más antiguo: la sesión nunca cargaba el campo de imagen, lo que afectaba a todos los usuarios desde siempre y no tenía relación con la Fase 2. Fue corregido junto.

Proceso

Todo el trabajo fue hecho por acceso directo al servidor, sin clone local. Backup de la base antes de cada ronda de alteración. QA con usuarios administrador y cliente de prueba descartables, borrados después. Build y verificación de tipos limpios en cada ronda, con despliegue confirmado por respuesta del servidor antes de avisar al cliente.

Stack

Next.js · TypeScript · NextAuth · PostgreSQL · VPS Contabo