3. Análisis Inicial

STATUS: borrador (v1) Estimación: 5-6 páginas

3.1 Descripción del problema o necesidad

Las consultoras tecnológicas que han incorporado IA generativa en su día a día se enfrentan a un desajuste entre dos velocidades: la velocidad a la que la IA puede generar artefactos (código, documentación, planes) y la velocidad a la que un equipo humano puede revisarlos, integrarlos y mantenerlos sin acumular deuda técnica. Este desajuste es especialmente crítico cuando, además, la operativa diaria del equipo está repartida entre cinco o seis herramientas SaaS distintas que no comparten un modelo de datos común.

El problema se concreta en cuatro puntos:

Falta de un sistema único que centralice clientes, proyectos, tickets, comunicación interna, llamadas y control horario.
Falta de un mecanismo formal que transforme tareas de consultoría en planes de Pull Requests ejecutables, en lugar de descripciones libres asignadas a personas.
Falta de una capa de contexto validado que pueda alimentar a los modelos de lenguaje sin contaminarlos con información obsoleta o no aprobada.
Falta de un flujo Git estandarizado que permita escalar la incorporación de nuevos miembros (humanos o IA) sin perder trazabilidad.

Quetzy ERP nace para cubrir estas cuatro carencias en un único sistema desplegable en infraestructura propia, sin dependencia de SaaS de terceros para las piezas críticas.

3.2 Usuarios objetivos / públicos involucrados

El sistema está diseñado para los siguientes perfiles:

Consultor / desarrollador del equipo. Usuario primario. Crea tickets, los ejecuta a través de PRs, participa en llamadas, registra horas y consume contexto validado. Es quien interactúa diariamente con prácticamente todas las features del sistema.
PM o lead técnico. Usuario secundario. En la práctica, en consultoras pequeñas, suele ser el mismo consultor en un rol diferente. Aprueba context_items propuestos, revisa transiciones de tickets en gates críticos y mantiene la coherencia del contexto de cliente.
Cliente externo invitado (fuera del alcance v1, previsto para fases posteriores). Tendría acceso restringido a canales y proyectos específicos.
Sistemas externos: modelos de lenguaje. Consumen context_items validados a través de la capa de IA (AIProvider + Skill interfaces). No son usuarios humanos, pero son consumidores de primer nivel del sistema.

A lo largo del desarrollo del TFG, el sistema ha sido validado con dos casos de uso reales:

Recotex, un cliente real del entorno de prácticas, fue el primer caso de validación funcional. Durante la fase de desarrollo, el sistema se utilizó en modo mock (con la implementación mock-erp-repository) para modelar la información del cliente, sus proyectos y sus tickets sin riesgo sobre datos productivos. Esto permitió validar flujos completos antes de exponer ningún dato real a la base de datos productiva.
El propio repositorio de Quetzy ERP, gestionado dentro de Quetzy como un proyecto más, ha funcionado como meta-validación: el sistema se gestiona a sí mismo. Esta autorreferencia ha sido especialmente útil para extraer patrones arquitectónicos reutilizables —websockets en realtime, autenticación con JWT y cookie httpOnly, storage de archivos vía Insforge Storage, presencia con heartbeat— y para estandarizar procesos (convención de ramas, plantillas de PR, criterios de cierre de ticket) que ahora pueden trasladarse a futuros proyectos del equipo.

3.3 Requisitos del proyecto

Los requisitos se agrupan en cuatro bloques: comunicación y colaboración, gestión operativa, contexto y arquitectura técnica.

Bloque	Requisito
Comunicación	Chat en tiempo real con texto, audio, adjuntos y reacciones.
Comunicación	Llamadas WebRTC con audio y compartición de pantalla.
Comunicación	Indicadores de presencia y typing efímeros.
Operativa	Gestión de clientes y proyectos.
Operativa	Tickets con máquina de estados y transiciones auditadas.
Operativa	Control horario asociado a cliente / proyecto / ticket.
Operativa	Notificaciones internas y resumen de pendientes.
Contexto	CRUD de `context_items` con flujo de aprobación humana.
Contexto	Distinción explícita entre contexto crudo y contexto validado.
Contexto	Enlace N:M de contexto a entidades del ERP.
Arquitectura	Self-hosting completo (no SaaS de terceros para piezas críticas).
Arquitectura	CI/CD automático con tests obligatorios.
Arquitectura	Capa de contratos (Zod) compartida cliente/servidor.

3.4 Requisitos funcionales

Lista detallada de capacidades que el sistema debe ofrecer.

RF-01. Autenticación. El sistema permitirá el inicio de sesión mediante email y contraseña, gestionará la sesión con cookie httpOnly de 7 días y validará el JWT en cada petición server-side.

RF-02. Gestión de canales de chat. El sistema permitirá crear canales de tipo general, team y project. Los canales tipo project quedarán vinculados a un proyecto concreto.

RF-03. Mensajería de texto. El sistema permitirá enviar mensajes de texto con soporte para responder a un mensaje previo (reply-to) y embebido de tarjetas de proyecto.

RF-04. Mensajería de audio. El sistema permitirá grabar mensajes de audio y reproducirlos inline en el chat.

RF-05. Adjuntos. El sistema permitirá adjuntar archivos (imágenes JPG/PNG/WebP y documentos PDF) hasta 10 MB por archivo y 5 archivos por mensaje. Soportará pegado directo desde portapapeles (Ctrl+V) para imágenes.

RF-06. Reacciones. El sistema permitirá reaccionar a mensajes con emojis con toggle.

RF-07. Realtime. El sistema entregará mensajes nuevos, reacciones y cambios de presencia a los usuarios conectados sin recarga de página.

RF-08. Llamadas WebRTC. El sistema permitirá iniciar y unirse a una llamada de audio por canal, con compartición de pantalla opcional. El estado de la llamada se reflejará en base de datos vía webhook del servidor LiveKit.

RF-09. Tickets con máquina de estados. El sistema gestionará tickets con 14 estados explícitos y registrará cada transición con su evidencia. Las transiciones inválidas serán rechazadas a nivel de máquina de estados pura.

RF-10. Gestión de clientes y proyectos. El sistema mantendrá CRUD de clientes y proyectos con relación 1:N entre cliente y proyecto.

RF-11. Control horario. El sistema permitirá iniciar, pausar, reanudar y detener un timer asociado a cliente / proyecto / ticket. Las entradas de tiempo serán consultables por filtros.

RF-12. Context items. El sistema mantendrá una tabla de context_items con flujo de aprobación humana, soporte para revalidación, marcado como obsoleto, ingestión de raw context y extracción asistida por IA.

RF-13. Notificaciones. El sistema generará notificaciones internas, mostrará un contador de no leídas y permitirá marcarlas como leídas individualmente o en bloque.

RF-14. Presencia. El sistema mantendrá un heartbeat de presencia online y mostrará la lista de usuarios conectados.

3.5 Requisitos no funcionales

RNF-01. Rendimiento. El tiempo de respuesta de las API REST debe ser inferior a 300 ms en peticiones estándar (no incluye streaming ni operaciones de IA). El bundle inicial del cliente debe permitir un Time to Interactive aceptable en conexiones residenciales españolas medias.

RNF-02. Escalabilidad. La arquitectura debe permitir alojar el sistema en un VPS de gama media (4 vCPU, 8 GB RAM) sirviendo a un equipo de hasta 20 personas concurrentes sin degradación.

RNF-03. Disponibilidad. Deploy con health check automático, rollback manual disponible y CI/CD que rechaza despliegues con tests rojos.

RNF-04. Seguridad. TLS automático en todos los dominios, sesiones con cookie httpOnly + secure, validación de input con Zod en todas las API routes, secretos fuera del repositorio.

RNF-05. Mantenibilidad. Cobertura mínima del 80 % en código de negocio. Arquitectura limpia con separación de capas: contrato, repositorio, dominio, presentación. Convención Git estricta (Conventional Commits + ramas tipo/scope-descripción).

RNF-06. Testabilidad. Doble implementación de cada repositorio (mock + producción) que permite testear la lógica sin depender del backend real.

RNF-07. Portabilidad. Despliegue completo mediante Docker Compose. Capacidad de migrar el VPS a otro proveedor sin cambios de código.

RNF-08. Observabilidad básica. Logs estructurados de servicios (LiveKit, ERP, Caddy) accesibles vía docker logs, health endpoint en /api/health.

RNF-09. Privacidad. Self-hosting completo de las piezas críticas (auth, BD, realtime, WebRTC). Ningún dato sensible se entrega a SaaS de terceros.

RNF-10. Compatibilidad navegadores. Soporte para navegadores modernos basados en Chromium y Firefox (versiones recientes). El soporte WebRTC requiere navegador con Web Audio API y getUserMedia.

3.6 Alcance y limitaciones

Dentro del alcance del TFG (v1).

El sistema entregado en este trabajo incluye las diez features funcionales del módulo principal del ERP: autenticación, chat completo (texto, audio, adjuntos, reacciones, typing, presencia), llamadas WebRTC con audio y compartición de pantalla, sistema de tickets con máquina de estados de 14 estados, gestión de contexto técnico validado, gestión de clientes y proyectos, control horario, notificaciones internas y shell común del ERP.

Se incluye también el despliegue en producción real bajo el dominio erp.quetzy.eu, con CI/CD automático mediante GitHub Actions, TLS gestionado vía Caddy y dos casos de validación reales: el cliente piloto Recotex modelado durante el desarrollo en modo mock, y el propio repositorio de Quetzy ERP gestionado dentro del sistema como meta-proyecto.

Forma parte del alcance conceptual la landing pública en quetzy.eu como puerta de entrada del producto, aunque su implementación final se realizará en una fase posterior al TFG.

Fuera del alcance del TFG, deuda priorizada para fases posteriores.

Las siguientes capacidades han sido diseñadas, parcialmente prototipadas o documentadas, y se mantienen como deuda explícita:

Triage formal de issues GitHub. Tras el cierre del TFG, está prevista una sesión de triage para asignar labels (tipo, prioridad, plataforma, feature), milestones y fechas a las 15 issues abiertas durante el desarrollo. Esta tarea es prioritaria post-TFG porque consolida la propia metodología que el sistema valida.
Acceso de cliente externo invitado a canales y proyectos específicos, con permisos restringidos.
Llamadas WebRTC v2 con vídeo y grabación en servidor.
Servidor TURN propio. El protocolo WebRTC requiere, en escenarios de NAT restrictivo (algunas redes corporativas, móviles 4G/5G con NAT carrier-grade), un servidor intermedio TURN que retransmita los paquetes cuando la conexión peer-to-peer directa no es posible. En v1 se confía en la conectividad UDP directa contra el VPS de LiveKit. En fases posteriores se evaluará desplegar un servidor TURN propio (por ejemplo coturn) para garantizar el funcionamiento en entornos de red más restrictivos.
Capa completa de Skills de IA más allá del extractor de contexto actual (M-Skills v1).
Dashboard de meetings y métricas operativas (v1.5).
Implementación final de la landing pública quetzy.eu con enfoque comercial.

Explícitamente fuera del proyecto.

Aplicación móvil nativa. Queda descartada por el coste de desarrollo y mantenimiento de dos plataformas (iOS y Android) en relación al beneficio aportado. La estrategia de movilidad pasa por mejorar la experiencia responsive del propio ERP web, no por construir una app nativa.

Limitaciones conocidas.

El sistema asume un equipo pequeño (de 2 a 20 personas). No se ha probado a mayor escala.
No incluye sistema de roles granular (RBAC). Todos los usuarios autenticados tienen acceso completo al ERP, salvo a sus propios datos privados.
No incluye internacionalización (i18n). Toda la interfaz está en castellano.
La capa de Tailwind CSS planificada inicialmente fue sustituida por CSS Modules + CSS Custom Properties durante el desarrollo. Esta decisión se justifica en el capítulo 5.
La tabla time_entry está creada directamente en la consola de Insforge y no aparece en data_model.sql. Esta discrepancia quedará documentada y corregida en mantenimiento.
Bug residual identificado en el módulo de llamadas: audio asimétrico tras reconnect en LiveKit, debido a un comportamiento del SDK livekit-client@2.18.9 con transceivers recvonly durante la renegociación SDP. La causa está diagnosticada con datos del servidor, pero la corrección definitiva queda fuera del alcance v1.