VavaStone - Inventario, ventas y entrega para la industria de la piedra natural

Desafío

VavaStone es una plataforma internacional de inventario, ventas y entrega de piedra natural, un dominio con logística compleja: existencias en múltiples almacenes, envíos calculados por peso, precios en varias divisas y flujos de trabajo de clientes multinacionales. El equipo de ingeniería estaba distribuido en varios países. Para cuando me incorporé, la arquitectura de microservicios en Go + React era funcional pero había acumulado fricción: los límites entre servicios eran implícitos, el desarrollo local requería una configuración considerable y la incorporación de nuevos ingenieros tomaba demasiado tiempo.

La contratación llevó un solo día: hicimos una llamada por WhatsApp, lo hablamos y esa misma tarde firmamos el contrato y empezamos a trabajar.

En el Slack del equipo figuraba simplemente como DEV, pero en la práctica era desarrollador full-stack y trabajaba tanto en el frontend como en el backend en Go.

Descubrimiento

Unas semanas de exploración del código y conversaciones con el equipo identificaron tres causas raíz. Primera: los servicios se comunicaban mediante JSON sin tipar y sin esquema compartido, lo que hacía que los errores de integración fueran sutiles y difíciles de detectar antes de producción. Segunda: el entorno local de Kubernetes requería pasos manuales que no estaban documentados, así que cada ingeniero tenía una configuración ligeramente distinta. Tercera: el proceso de contratación e incorporación era informal. El conocimiento vivía en la cabeza de las personas, no en documentación.

Opciones consideradas

1. Introducir un service mesh y clientes autogenerados, demasiado pesado para el tamaño del equipo; habría tomado meses migrar los servicios existentes.
2. Añadir especificaciones OpenAPI y generar clientes tipados por servicio: elegida como el punto medio pragmático. Contratos explícitos, tipos generados, sin nueva infraestructura.
3. Migrar a un monorepo con paquetes de tipos compartidos, aplazada; viable a largo plazo pero demasiado disruptiva a corto plazo.

Decisión

Introducir contratos de API tipados de forma incremental a medida que se tocan los servicios, en lugar de una migración de una sola vez. En paralelo: documentar el entorno de desarrollo local en un script de configuración repetible, y formalizar el proceso de incorporación con una lista de verificación escrita y un compañero designado para los nuevos ingenieros.

Implementación

Añadí definiciones OpenAPI a los servicios en los que trabajé y generé tipos de cliente TypeScript usados por el frontend en React. Esto capturaba una clase de errores en tiempo de compilación que antes solo aparecían en staging. Refactoricé la configuración local de Kubernetes en un flujo de trabajo documentado basado en Makefile, `make dev-up` en lugar de seis comandos manuales. Los nuevos ingenieros podían ejecutar toda la pila localmente desde el primer día.

Del lado del producto, entregué mejoras al módulo de gestión de inventario y pedidos: visualización de niveles de stock entre almacenes, seguimiento de estado de pedidos y flujos de cálculo de coste de envío. Participé activamente en la contratación: escribí descripciones de puesto, realicé entrevistas técnicas y dirigí la primera incorporación estructurada para dos nuevos ingenieros.

Resultado

Los errores de integración entre servicios se redujeron de forma medible, ya que los contratos tipados detectaban discrepancias en tiempo de compilación. El tiempo de adaptación de los nuevos ingenieros se acortó de semanas a días gracias al entorno de desarrollo documentado. El equipo entregó funcionalidades a una velocidad notablemente mayor en los trimestres posteriores a las mejoras de herramientas.

Demo

Reforzar los tipos entre backend y frontend se redujo a una opción práctica: generar una anotación para cada llamada de la API. Hacerlo a mano en toda la superficie es un trabajo largo, así que probé las herramientas de IA disponibles entonces, todavía crudas, y las elegí para acelerar esa parte. Esta es la grabación de I+D de ese enfoque.

La segunda mitad de la misma historia: una utilidad de OpenAPI lee esas anotaciones de las llamadas y genera a partir de ellas los tipos del frontend. Desde ahí una discrepancia de tipos aparece sola como error de compilación, lo que elimina toda una categoría de errores de integración en tiempo de ejecución.

El enfoque no se quedó en algo mío: grabé una explicación y se la presenté al resto del equipo. Recibió el visto bueno del teamlead y se adoptó como estándar para el desarrollo posterior, de modo que los endpoints nuevos y los reformados pasaron por el mismo flujo de anotar y generar.

Alfa temprana del prototipo del sistema de reportes, analítica de pedidos e inventario construida sobre la capa de datos con seguridad de tipos.

Presentación al cliente de una de las pantallas implementadas en una videollamada, junto con el código que hay detrás: la generación del informe corre bajo el depurador en VS Code, detenida en un punto de interrupción en el paso que carga desde la base de datos las entidades seleccionadas. La cámara del cliente está difuminada.

Opinión del cliente sobre el módulo terminado en el canal de informes. Acordamos mostrar primero el informe en la web y llevar la exportación a XLS o PDF a un botón, y la respuesta fue «Good progress!!». La foto del cliente y un comentario personal están ocultos.