Sistema de Adquisiciones de Telegram: Caso de Desarrollo Agentico Sin Código

# # Cómo un Tech Lead Construyó un Sistema de Compras en Telegram Sin Escribir Código: Un Caso de Estudio de Desarrollo Agentivo

Cuando las compras internas en el equipo se convirtieron en un caos con solicitudes perdidas y consultas descoordinadas, el tech lead decidió crear un sistema basado en Telegram. Sin escribir una sola línea de código, usando sistemas agentivos y una arquitectura clara, construyó una solución con OCR, moderación y despliegue seguro. Aquí te contamos cómo hacerlo sin perder el control sobre la calidad.

Problema: Caos en Lugar de un Proceso de Compras

En equipos pequeños, las compras suelen empezar con acuerdos informales. Primero hay papeles sueltos, luego notas, luego un hilo dedicado en Telegram. Surge un proceso: deja el enlace, precio, cantidad y justificación. Pero en la práctica, algunas solicitudes se pierden, otras se cuelan, algunas carecen de precio o justificación, y la gente olvida sus propias solicitudes. Como resultado, el tech lead pierde tiempo luchando contra el caos en vez de gestionar las compras. Lección clave: si un proceso implica dinero, no debería ser un chat libre.

Requisitos de Infraestructura: De "Botecito" a Sistema Completo

La idea inicial —un simple bot de Telegram— pronto se topó con desafíos de infraestructura. Debido a la inestabilidad de Telegram sin VPN, requería:

• VPS extranjero
• Configuración personalizada de VPN
• Reinicio automático fiable
• Despliegue conveniente
• Mecanismo de rollback para lanzamientos fallidos

Esto ya no es un "guion rápido de una tarde", sino una tubería de ingeniería completa. La experiencia demuestra: la "automatización simple" a menudo esconde una infraestructura compleja debajo.

Desarrollo Agentivo: Acelerador, No Sustituto del Pensamiento

El proyecto se implementó usando ChatGPT y un sistema agentivo, pero la participación activa del tech lead fue esencial. El proceso incluyó:

• Formular la tarea y asignar roles
• Aclarar la lógica de negocio
• Pruebas manuales de escenarios
• Identificar contradicciones y errores
• Iterar en correcciones dirigidas
• Repruebas

El agente aceleró el ciclo: acortando el tiempo entre detectar un problema y verificar una nueva implementación. Lección clave: puedes delegar la sintaxis del código, pero el pensamiento de sistemas y la arquitectura siguen siendo críticos. Sin un modelo de proceso claro, el agente solo acelera la implementación de lógica defectuosa.

Deshaciéndose de la "Magia": Cambio a un Flujo de Asistente

La primera hipótesis —extracción automática de datos de enlaces— resultó inviable debido a:

• Diversidad de sitios
• Estructuras de página inestables
• Precios ambiguos
• Renderizado complejo de datos
• Lógica hostil de marketplaces

En su lugar, se implementó un flujo de asistente:

• Adjuntar captura de pantalla
• Proporcionar enlace
• Escribir justificación
• Especificar cantidad
• Ingresar precio manualmente si es necesario (si el OCR falló)
• Revisar la tarjeta final antes de confirmar

Este enfoque es menos "impresionante", pero garantiza controlabilidad —el factor clave para procesos operativos.

Por Qué el LLM No Fue el Núcleo del Sistema

Aunque era tentador usar LLM para procesar solicitudes, se eligió una pila simple:

• Python
• Framework de bots de Telegram
• SQLite
• OCR local
• Informes HTML en plantillas
• systemd para servicios y temporizadores

Razones:

• Funciona en VPS de especificaciones bajas
• Sin dependencias en tiempo de ejecución de APIs externas
• Sin inferencia pagada por solicitud
• Depuración fácil
• Comportamiento predecible

Esta elección resalta un principio clave: no todas las tareas se benefician de la IA. A veces, un FSM estricto y validaciones entregan más valor que modelos complejos.

Máquina de Estados: Fundación de la Fiabilidad

Una solicitud es una entidad con un ciclo de vida que incluye estados:

• Borrador
• Esperando imagen
• Esperando enlace
• Esperando justificación
• Esperando confirmación
• Pendiente de moderación
• Devuelta para revisión
• Diferida al próximo período
• Urgente
• Enviada

Se usó FSM para gestionar este ciclo. Ejemplo de código:

class PurchaseWizard(StatesGroup):
    waiting_for_image = State()
    waiting_for_link = State()
    waiting_for_reason = State()
    waiting_for_qty_lots = State()
    waiting_for_lot_size = State()
    waiting_for_manual_price = State()
    waiting_for_confirmation = State()

y estados del dominio:

class PurchaseStatus(str, Enum):
    DRAFT = "draft"
    AWAITING_IMAGE = "awaiting_image"
    AWAITING_LINK = "awaiting_link"
    AWAITING_REASON = "awaiting_reason"
    AWAITING_QTY = "awaiting_qty_lots"
    AWAITING_CONFIRMATION = "awaiting_confirmation"
    COMPLETE = "complete"
    PENDING_MODERATION = "pending_moderation"
    RETURNED_FOR_REVISION = "returned_for_revision"
    APPROVED = "approved"
    CANCELLED = "cancelled"
    SENT = "sent"

Cuando hay roles, dinero y plazos de por medio, pasa de manejar mensajes a gestionar estados.

Arquitectura: Simplicidad como Señal de Madurez

Diagrama del sistema:

Telegram user
    ↓
Bot handlers / FSM
    ↓
Purchase service
    ├── SQLite
    ├── OCR service
    ├── Moderation logic
    ├── HTML report builder
    └── Reminder / maintenance jobs
            ↓
        systemd service + timers

Estructura del proyecto:

purchase_bot/
├── app/
│   ├── bot/
│   ├── db/
│   ├── services/
│   ├── templates/
│   └── main.py
├── data/
│   ├── uploads/
│   ├── reports/
│   └── bot.db
├── scripts/
├── deploy/
└── README.md

Omitir Docker y bases de datos pesadas en la primera versión permitió enfocarse en la funcionalidad. Para herramientas internas, una arquitectura simple es señal de madurez, no de debilidad.

UX de Telegram: Interfaz Sobre Flujo de Mensajes

Trabajar con Telegram reveló desafíos:

• Botones antiguos persistentes
• Tarjetas superpuestas
• Versiones paralelas de solicitudes antiguas y nuevas
• Retrasos en notificaciones
• Comportamiento inconsistente del botón "Atrás"
• Bucles en pantalla
• Desorden en el chat

Solución: diseñar el bot como un sistema de estados basado en pantallas. Principios centrales:

• Una sola pantalla activa
• Eliminar mensajes obsoletos
• Manejo seguro de botones de callback antiguos
• Reglas separadas para menús, notificaciones y tarjetas de trabajo

Este enfoque, aunque no es llamativo, garantiza usabilidad diaria.

Procesos Reales Rompen la Simetría

Implementar moderación, solicitudes urgentes y diferimientos por período mostró que los procesos reales no encajan en diagramas pulcros. Por ejemplo, una segunda etapa de moderación puede añadir fricción innecesaria si la primera ya manejó la solicitud por completo. La lógica tuvo que reconstruirse para necesidades reales, no para diagramas. Los tech leads conocen este patrón: si el esquema frena el flujo, rompe el esquema.

Errores Más Insidiosos en los Límites de Capas

Errores críticos surgieron no en funciones centrales, sino en intersecciones de capas. Por ejemplo:

• Botón "Confirmar" colgado por comparación de objetos con y sin zona horaria
• Desajustes de formato de datos entre módulos
• Problemas de sincronización de estados en actualizaciones

Estos errores subrayan la importancia del diseño cuidadoso de interfaces de componentes.

Lecciones Clave

• Arquitectura sobre agentes: Incluso con sistemas agentivos, una arquitectura clara y pensamiento de sistemas son obligatorios. Los agentes aceleran la implementación pero no reemplazan el diseño.
• Controlabilidad sobre "inteligencia": Para procesos operativos, la fiabilidad y simplicidad superan la automatización compleja. Los flujos de asistente suelen superar intentos de automatización total.
• Estados, no mensajes: Con roles, dinero y plazos, diseña como un ciclo de vida gestionado con estados explícitos.
• Simplicidad como estrategia: Para herramientas internas, evita hinchazón arquitectónica. Una pila mínima en hardware modesto garantiza fiabilidad y mantenimiento fácil.
• UX de Telegram exige disciplina: Los bots deben diseñarse como sistemas de pantallas, no flujos de mensajes. Eliminar elementos obsoletos y una sola pantalla son críticos para la experiencia de usuario.

— Editorial Team