11. Conclusiones

STATUS: borrador (v1) Estimacion: 3-4 paginas

11.1 Logros alcanzados

Quetzy ERP se entrega como un sistema en produccion real, desplegado bajo erp.quetzy.eu, con 116 commits en main, 46.755 lineas de TypeScript repartidas en 311 archivos, 827 tests pasando con un 82,22 % de coverage en sentencias, 10 features funcionales integradas, 22 tablas en base de datos, 44 endpoints API y un pipeline CI/CD que valida automaticamente cada merge antes de desplegar a produccion.

El proyecto se construyo en dos fases claramente diferenciadas: cuatro meses de investigacion previa (flujos de trabajo con IA generativa, evaluacion de tooling, definicion de convenciones Git, analisis de stacks BaaS y diseño del modelo de datos) seguidos de tres semanas de implementacion intensiva (16 de abril al 8 de mayo de 2026) con un desarrollador principal y la incorporacion de un segundo en la fase final. El CI/CD se desplego el primer dia, antes que cualquier feature funcional, y toda la iteracion se hizo contra produccion real: no existe entorno de staging. Esta concentracion temporal no es una limitacion a esconder, sino prueba empirica directa de la tesis del proyecto: una metodologia bien definida, con Git estandarizado, tickets ejecutables y contexto validado, permite producir un sistema completo de esta envergadura en un plazo comprimido sin acumular deuda tecnica inmanejable.

Respuesta a la pregunta-tesis

La pregunta de investigacion planteada en el Cap 2.2 —cual es la manera mas optima de gestionar productos digitales potenciando el desarrollo por IA sin desplazar el rol del programador, sino integrandolo en el flujo convencional de versionado y revision por pares— se responde empiricamente con tres pilares demostrados en funcionamiento a lo largo del desarrollo del propio sistema:

1. Estandarizacion Git extrema. Conventional Commits, ramas tipadas (tipo/scope-descripcion), squash merge a main y CI/CD obligatorio (lint + test + build + deploy) hacen que humanos y agentes IA operen sobre el mismo flujo sin perder coherencia. El agente no necesita instrucciones especiales para producir un commit valido: la convencion esta lo suficientemente bien definida como para que cualquier participante (humano o maquina) la siga sin ambiguedad. Los 116 commits del historial de main mantienen un formato consistente independientemente de quien los produjo.

2. Tickets transformados en planes de PRs. Cada ticket no se cierra con una descripcion libre y una asignacion a persona; se cierra con un plan de Pull Requests concreto, sus dependencias, los archivos afectados y los criterios de aceptacion. Esto convierte la planificacion en un artefacto ejecutable: un agente IA puede tomar el plan y producir los commits necesarios sin necesidad de interpretacion libre. La ambiguedad se elimina en la fase de planificacion, no en la de implementacion.

3. context_items validados por humanos. En lugar de conectar un LLM a toda la documentacion del proyecto (con el riesgo de contaminar respuestas con borradores obsoletos o ideas descartadas), Quetzy mantiene una capa explicita de contexto validado. Solo los context_items aprobados por un humano son consumibles por la IA. Este enfoque sustituye la dependencia de bases vectoriales, GraphRAG o embeddings con menos infraestructura, mayor control y un flujo de validacion auditable. Cada item tiene trazabilidad completa: quien lo propuso, quien lo aprobo, a que entidades esta enlazado y si ha sido marcado como obsoleto.

La combinacion de estos tres pilares produce un resultado que ninguno aislado conseguiria: el programador no es desplazado por la IA, sino que opera como decision-maker en un flujo donde la IA amplifica la velocidad de ejecucion. Las cuatro gates humanas obligatorias de la maquina de estados (clasificacion, aprobacion de diseño, validacion de PR, cierre con evidencia) formalizan esta separacion de responsabilidades en el propio sistema.

Validacion empirica de escalabilidad metodologica (OE8)

La incorporacion de Manu en la fase final del proyecto funciono como prueba de concepto del OE8. Su primera contribucion (PR #70) siguio el flujo establecido sin necesidad de onboarding extenso: rama con convencion correcta, commits atomicos, squash merge tras aprobacion. El hecho de que un segundo desarrollador pueda operar productivamente sobre el sistema sin formacion ad hoc demuestra que la metodologia no depende del conocimiento tacito del autor original. Los estandares estan explicitados en el codigo (Decision/Reason/Alternative), en las convenciones Git y en el propio sistema de tickets.

Cumplimiento de objetivos especificos

Los ocho objetivos especificos definidos en el Cap 2.4 se cumplen:

OE1 (chat en tiempo real): cumplido. 18 componentes, 7 hooks, 2 contextos, realtime via WebSocket.
OE2 (llamadas WebRTC): cumplido con deuda. Funciona; subsiste bug de audio asimetrico tras reconnect (D-01).
OE3 (tickets con maquina de estados): cumplido. 14 estados, 5 guards funcionales, tests puros sin mocks de infra.
OE4 (context_items con aprobacion humana): cumplido. 3 tablas, flujo completo propuesto-aprobado-obsoleto.
OE5 (arquitectura limpia): cumplido. 18 schemas Zod, doble implementacion de repositorios, 7 contextos React.
OE6 (CI/CD + coverage >= 80 %): cumplido. Pipeline de 4 jobs, 82,22 % statements coverage.
OE7 (self-hosting): cumplido con matiz. Auth, BD, realtime y WebRTC autoalojados. CI depende de GitHub Actions (deuda documentada).
OE8 (validacion metodologica): cumplido como prueba de concepto. Manu opero sobre el flujo sin onboarding extenso.

Los OE2 y OE7 se reportan con honestidad: cumplen su objetivo funcional pero mantienen deudas explicitas. No se infla el cumplimiento.

11.2 Dificultades encontradas

Bug de audio asimetrico en LiveKit

El diagnostico consumio varios dias de investigacion. El problema: tras una reconexion del cliente al room de LiveKit, los tracks de audio remoto dejaban de reproducirse en uno de los participantes. La causa identificada es un comportamiento del SDK livekit-client@2.18.9 que crea transceivers en modo recvonly durante la renegociacion SDP post-reconnect, pero no los asocia correctamente a los tracks remotos existentes. Se desplego un fix parcial (pre-registro de listener TrackPublished antes de connect() + catch-up loop), que resuelve el caso de primera conexion pero no el de reconexion. La correccion definitiva queda como deuda D-01. El aprendizaje principal: los bugs de WebRTC solo se manifiestan bajo condiciones de red reales y no son reproducibles de forma fiable en localhost.

Incidente de seguridad PostgreSQL expuesto (BSI aleman)

El 6 de mayo de 2026, el BSI (Bundesamt fur Sicherheit in der Informationstechnik) notifico que los puertos 5432 y 5430 del VPS eran accesibles publicamente. La causa: Docker inserta reglas iptables propias que preceden a las de UFW, por lo que la politica general DENY de UFW no bloqueaba los puertos mapeados por Docker. La correccion fue inmediata (reglas UFW DENY explicitas), pero el incidente demostro que los defaults de seguridad de Docker + UFW no son suficientes sin verificacion explicita. Este no fue un fracaso: fue un aprendizaje operativo legitimo que refuerza la importancia de auditorias externas, incluso involuntarias.

Deploys redundantes por desconocimiento del CI/CD activo

Durante varias semanas, el desarrollador hizo deploys manuales via SSH sin saber que GitHub Actions ya estaba aplicando los cambios automaticamente tras cada merge a main. El hallazgo revelo que la documentacion interna del flujo de deploy era insuficiente y motivo una mejora explicita. El aprendizaje: CI/CD desde el dia 1 es correcto, pero requiere que todo el equipo (incluso si es unipersonal) tenga visibilidad clara de que esta activo y funcionando.

Schema drift entre consola Insforge y `data_model.sql`

Las tablas time_entry y notification se crearon directamente en la consola web de Insforge durante el desarrollo rapido, sin añadirlas al archivo data_model.sql versionado. Esto rompe el principio de Git como fuente de verdad y genera discrepancias entre lo que el codigo espera y lo que la documentacion describe. El aprendizaje: toda tabla debe crearse primero en el archivo SQL versionado y luego ejecutarse contra la BD, no al reves.

El SDK de Insforge en server mode (isServerMode: true) envia client_type=mobile al backend, lo que hace que los tokens se devuelvan en el body JSON en lugar de establecerse como cookies automaticamente. La solucion fue persistir la cookie manualmente (documentada como “Plan B” en actions.ts:39-46). Funciona, pero es fragil ante cambios internos del SDK. El aprendizaje: cuando un SDK no cubre un caso de uso, la solucion manual debe quedar explicitamente documentada con Decision/Reason/Alternative para que futuros mantenedores entiendan por que existe.

Race condition en `TrackPublished` de LiveKit

El listener de tracks remotos registrado despues de connect() perdia tracks que el servidor ya habia comenzado a negociar durante la fase de conexion. Solo detectable bajo carga real con multiples participantes, nunca en pruebas locales con un solo peer. La solucion (registro pre-connect + catch-up loop) se implemento tras diagnostico con logs del servidor LiveKit y analisis de la secuencia SDP.

Stack muy reciente con poca documentacion comunitaria

Trabajar con Next.js 16, React 19 y livekit-client@2.18 implica que gran parte de los problemas encontrados no tienen respuesta en Stack Overflow ni en foros. La resolucion requirio lectura directa del codigo fuente de las librerias y experimentacion. Esto es un coste real del early adoption que se acepta conscientemente a cambio de trabajar con las APIs mas modernas.

Equilibrio memoria vs implementacion bajo presion de calendario

La redaccion de la memoria del TFG se solapa temporalmente con la estabilizacion de features y el onboarding de Manu. Gestionar las dos actividades en paralelo sin que ninguna degrade la calidad de la otra requirio disciplina de bloques de trabajo dedicados y la decision explicita de aparcar el milestone Dev View / Git View para no comprometer ninguno de los dos frentes.

11.3 Aprendizajes tecnicos y personales

Tecnicos

Ingenieria de contexto como disciplina. El cuello de botella de la IA generativa aplicada al desarrollo no es la calidad del modelo, sino la calidad del contexto que recibe. Los context_items de Quetzy formalizan esta intuicion: contexto validado, con scope, con enlace a entidades y con ciclo de vida explicito (propuesto, aprobado, obsoleto). Este patron es mas robusto que conectar un LLM a una base vectorial de documentacion sin curar.

Patron Repository con doble implementacion. La decision de mantener una implementacion mock completa en memoria (no un mock parcial de test) permite ejecutar los 827 tests sin conexion a ningun backend real. Esto es lo que hace posible un CI/CD de 19 segundos de ejecucion de tests. El coste es mantener dos implementaciones sincronizadas; el beneficio es testabilidad real, no testabilidad simulada.

Compensacion manual cuando no hay transacciones. El SDK de Insforge no expone transacciones multi-tabla. El patron de compensacion implementado en sendMessage (DELETE del mensaje huerfano + cleanup de storage si falla el INSERT de attachments) es la solucion pragmatica cuando el backend no ofrece atomicidad. No es ideal, pero es honesto y esta documentado.

CI/CD desde el dia 1. Desplegar el pipeline antes que cualquier feature garantiza que nunca se acumula deuda de integracion. Cada commit que llega a main esta validado por lint, tests y build. El coste de configuracion inicial se amortiza desde el primer merge.

Decisiones documentadas en codigo. El patron Decision / Reason / Alternative (135 comentarios en 94 archivos del repositorio) convierte el codigo en un registro de decisiones arquitectonicas consultable. Cualquier persona que retome el codigo entiende no solo que hace, sino por que se decidio hacerlo asi y que alternativas se descartaron.

Personales

Disciplina externa para TDAH. Trabajar con TDAH requiere compensar la dificultad de mantenimiento de atencion con estructura externa rigida: bloques de trabajo de 90 minutos con objetivo cerrado, prompts estructurados que fuerzan investigacion previa antes de implementar, decisiones cerradas escritas en Drive en lugar de mantenidas en memoria de trabajo. El flujo de Quetzy (investigacion obligatoria, plan aprobado, implementacion acotada) no es solo una buena practica de ingenieria: es una estrategia de compensacion funcional.

Respetar la decision de no terminar. La tentacion de añadir el milestone Dev View / Git View (diseñado, planificado, con arquitectura pensada) fue fuerte. La decision de aparcarlo para priorizar la estabilidad de v1 y la calidad de la memoria es un aprendizaje de madurez profesional: lo casi terminado se queda casi cuando completarlo compromete otros entregables.

Valor del voto firme de un colaborador. La incorporacion de Manu no solo valido el OE8; tambien introdujo un segundo criterio en decisiones que un desarrollador solitario tiende a postergar. El “depende” se sustituye por un voto concreto cuando hay dos personas que deben alinear.

Sobre IA generativa en el desarrollo

Claude Code y agentes similares no sustituyen al programador: lo amplifican cuando el flujo Git, los contratos y el contexto estan bien definidos. Sin estandarizacion Git, la IA produce commits con formatos inconsistentes que contaminan el historial. Sin contratos Zod, la IA inventa tipos que no validan. Sin context_items validados, la IA genera codigo basado en informacion obsoleta o incorrecta. Los tres pilares de la tesis no son requisitos burocraticos: son la infraestructura minima para que la IA sea un amplificador y no un generador de deuda tecnica.

La conclusion mas contraintuitiva del proyecto es que hacer que la IA funcione bien requiere mas estructura, no menos. La inversion en estandares, convenciones y validacion humana no es un lastre que la IA elimina: es el sustrato que la IA necesita para producir resultados de calidad mantenible.