Requisitos No Funcionales
Tabla de Contenidos
- Introducción
- Propósito y Alcance del Documento
- Requisitos de Rendimiento
- Requisitos de Seguridad
- Requisitos de Escalabilidad
- Requisitos de Confiabilidad
- Requisitos de Mantenibilidad
- Requisitos de Usabilidad
- Requisitos de Cumplimiento
- Requisitos Operacionales
- Matriz General de Verificación
- Brechas Críticas y Recomendaciones
- Referencias Cruzadas
Introducción
Este documento define los requisitos no funcionales (NFRs) para la Plataforma de Gestión de Mantenimiento Algesta. Los NFRs especifican cómo el sistema debe realizar sus funciones, cubriendo aspectos de rendimiento, seguridad, escalabilidad, confiabilidad, mantenibilidad, usabilidad, cumplimiento y operacionales.
Cada requisito incluye:
- ID de Requisito: Identificador único
- Requisito: Declaración clara del NFR
- Métrica: Criterio medible
- Meta: Umbral o valor específico
- Verificación: Cómo se valida el requisito
- Implementación: Tecnologías y patrones utilizados
- Estado: Estado actual de implementación (✅ Completo, 🟡 Parcial, 🔴 Brecha)
Propósito y Alcance del Documento
Propósito
Este documento permite a:
- Arquitectos diseñar sistemas que cumplan objetivos de rendimiento y escalabilidad
- Desarrolladores implementar soluciones alineadas con estándares de calidad
- DevOps configurar infraestructura y monitoreo para requisitos operacionales
- Ingenieros de QA verificar características no funcionales
- Auditores rastrear NFRs hasta evidencia de implementación
Alcance
Cubre todos los requisitos no funcionales para:
- Rendimiento de API Gateway y microservicios
- Seguridad (autenticación, autorización, cifrado)
- Escalabilidad (escalado horizontal, manejo de carga)
- Confiabilidad (tiempo de actividad, tolerancia a fallos, circuit breakers)
- Mantenibilidad (cobertura de pruebas, calidad de código, logging)
- Usabilidad (accesibilidad, tiempos de respuesta)
- Cumplimiento (GDPR, leyes de datos colombianas, registros de auditoría)
- Operaciones (monitoreo, logging, health checks)
Fuera de Alcance
- Requisitos funcionales (ver functional-requirements.md)
- Requisitos de negocio (ver business-requirements.md)
- Detalles de aprovisionamiento de infraestructura (ver infrastructure-as-code.md)
Requisitos de Rendimiento
| ReqID | Requisito | Métrica | Meta | Verificación | Implementación | Estado |
|---|---|---|---|---|---|---|
| NFR-01 | Operaciones de lectura del API Gateway responden dentro de latencia aceptable | Latencia P95 para solicitudes GET | < 200ms | Pruebas de carga con 100 usuarios concurrentes | Caché Redis para consultas frecuentes, indexación MongoDB | ✅ |
| NFR-02 | Operaciones de escritura del API Gateway se completan dentro de tiempo aceptable | Latencia P95 para POST/PATCH/DELETE | < 500ms | Pruebas de carga con 50 operaciones de escritura concurrentes | Arquitectura event-driven asíncrona, I/O no bloqueante | ✅ |
| NFR-03 | Procesamiento de mensajes de WhatsApp responde dentro de expectativa del usuario | Tiempo de respuesta para creación de orden vía Jelou | < 5 segundos | Pruebas manuales con conversaciones reales | Caché de API GPT-4, procesamiento de imágenes optimizado | 🟡 |
| NFR-04 | Tiempo de carga de página del dashboard cumple expectativas del usuario | Time to Interactive (TTI) | < 3 segundos | Auditoría de rendimiento Lighthouse | Code splitting, lazy loading, optimización de assets | ✅ |
| NFR-05 | Listado de subastas del marketplace carga sin demora | Tiempo para renderizar 100 tarjetas de subasta | < 2 segundos | Perfilado de rendimiento de frontend | Caché React Query, paginación, listas virtualizadas | 🟡 |
| NFR-06 | Generación de PDF se completa sin timeout | Tiempo máximo para PDF de confirmación de orden | < 10 segundos | Prueba automatizada con PDF de 50 páginas | Puppeteer con renderizado optimizado, trabajos en segundo plano | ✅ |
| NFR-07 | Rendimiento de consultas de base de datos cumple SLA | Tiempo P95 de consulta MongoDB | < 100ms | Monitoreo APM (Application Insights) | Campos indexados (orderId, serial, email), connection pooling | ✅ |
| NFR-08 | Reconocimiento OCR de serial se completa dentro de tiempo aceptable | Tiempo máximo para llamada API GPT-4 Vision | < 8 segundos | Pruebas de integración con 20 imágenes de muestra | API Azure GPT-4 Vision, lógica de reintento con backoff exponencial | ✅ |
Estado general de rendimiento: 88% completo (7/8 ✅, 1/8 🟡)
Brechas:
- NFR-03: El tiempo de respuesta de WhatsApp ocasionalmente excede 5s debido a picos de latencia de API GPT-4
- NFR-05: Listado de subastas con 100+ elementos puede exceder 2s en conexiones lentas
Requisitos de Seguridad
| ReqID | Requisito | Métrica | Meta | Verificación | Implementación | Estado |
|---|---|---|---|---|---|---|
| NFR-09 | Todas las solicitudes API autenticadas mediante tokens JWT | % de endpoints protegidos con auth guard | 100% (excepto health checks públicos) | Revisión de código, auditoría de endpoints | @nestjs/jwt, JwtAuthGuard en todas las rutas | ✅ |
| NFR-10 | Control de acceso basado en roles aplicado para operaciones de admin | % de endpoints de admin con RBAC | 100% | Pruebas de seguridad, pruebas de penetración | RolesGuard con decorador @Roles | ✅ |
| NFR-11 | Contraseñas almacenadas con hashing seguro | Algoritmo de hashing | bcrypt con salt rounds ≥ 10 | Auditoría de seguridad | Librería bcrypt en microservicio Auth | ✅ |
| NFR-12 | Cifrado TLS para todo el tráfico externo | % de tráfico sobre HTTPS | 100% | Prueba SSL Labs, auditoría de red | cert-manager con certificados Let’s Encrypt | ✅ |
| NFR-13 | Rate limiting previene abuso y ataques DoS | Rate limit para endpoints públicos | 100 solicitudes/min por IP | Pruebas de carga, simulación de abuso | @nestjs/throttler (recomendado, no implementado) | 🔴 |
| NFR-14 | Validación de entrada previene ataques de inyección | % de DTOs con decoradores de validación | 100% | Revisión de código, pruebas OWASP | class-validator con @IsString, @IsEmail, etc. | ✅ |
| NFR-15 | Datos sensibles cifrados en reposo | Cifrado de base de datos | Cifrado de MongoDB Atlas habilitado | Auditoría de seguridad | Cifrado predeterminado de MongoDB Atlas | ✅ |
| NFR-16 | Registro de auditoría captura todos los cambios de estado | % de operaciones críticas registradas | 100% | Revisión de registro de auditoría | Logging estructurado Winston, entidad OrderHistory | ✅ |
| NFR-17 | Secretos gestionados de forma segura sin hardcodear | % de secretos en vars de env o Key Vault | 100% | Escaneo de código para secretos hardcodeados | Variables de entorno, Azure Key Vault (recomendado) | 🟡 |
| NFR-18 | Subidas de archivos validadas por tipo y tamaño | Tamaño máximo de subida, tipos permitidos | 5 MB, solo PDF/JPG/PNG | Pruebas de subida con archivos maliciosos | Validación Multer, escaneo Azure Blob Storage | ✅ |
Estado general de seguridad: 90% completo (8/10 ✅, 1/10 🟡, 1/10 🔴)
Brechas:
- NFR-13: Rate limiting no implementado; vulnerable a ataques DoS
- NFR-17: Secretos almacenados en variables de entorno; se recomienda integración con Azure Key Vault
Requisitos de Escalabilidad
| ReqID | Requisito | Métrica | Meta | Verificación | Implementación | Estado |
|---|---|---|---|---|---|---|
| NFR-19 | Sistema soporta escalado horizontal para mayor carga | Capacidad de escalar microservicios | Agregar réplicas sin cambios de código | Pruebas HPA de Kubernetes | Microservicios sin estado, Redis/Kafka para estado | ✅ |
| NFR-20 | Base de datos maneja conexiones concurrentes eficientemente | Máx. conexiones concurrentes | 200+ usuarios simultáneos | Pruebas de carga con connection pooling | MongoDB Atlas con cluster M10+, connection pooling | ✅ |
| NFR-21 | Capa de mensajería escala con volumen de eventos | Máx. mensajes/segundo sin lag | 1000 mensajes/seg | Pruebas de carga Kafka | Apache Kafka con múltiples brokers (producción) | ✅ |
| NFR-22 | Almacenamiento de archivos soporta grandes volúmenes de documentos | Capacidad de almacenamiento | 1 TB, expandible | Prueba de capacidad Azure Blob Storage | Azure Blob Storage con auto-escalado | ✅ |
| NFR-23 | Dashboard soporta 500+ usuarios concurrentes | Máx. usuarios concurrentes de dashboard | 500 sin degradación | Pruebas de carga con artillery.io | CDN para assets estáticos, caché React Query | 🟡 |
Estado general de escalabilidad: 80% completo (4/5 ✅, 1/5 🟡)
Brechas:
- NFR-23: Pruebas de carga del dashboard aún no realizadas; meta no verificada
Requisitos de Confiabilidad
| ReqID | Requisito | Métrica | Meta | Verificación | Implementación | Estado |
|---|---|---|---|---|---|---|
| NFR-24 | Sistema logra SLA de alta disponibilidad | Porcentaje de tiempo de actividad | ≥ 99.5% (máx. 43.8 horas de inactividad/año) | Monitoreo de tiempo de actividad durante 30 días | Health checks, auto-reinicio en falla, despliegue multi-AZ | ✅ |
| NFR-25 | Fallos de servicio no se propagan en cascada entre microservicios | Circuit breaker previene fallos en cascada | 100% de llamadas críticas protegidas | Pruebas de chaos engineering | CircuitBreakerService en API Gateway | ✅ |
| NFR-26 | Backups de base de datos habilitan recuperación ante desastres | Frecuencia de backup, RPO | Backups diarios, RPO < 24 horas | Prueba de restauración desde backup | Backups automatizados MongoDB Atlas | ✅ |
| NFR-27 | Capa de mensajería garantiza entrega de mensajes | Garantía de entrega de mensajes | Entrega al-menos-una-vez | Pruebas de integración con fallos | Persistencia de mensajes Kafka, lógica de reintento Redis | ✅ |
| NFR-28 | Fallos de API externas manejados con gracia | % de llamadas externas con fallback | 100% (SendGrid, GPT-4, etc.) | Pruebas de inyección de fallos | Circuit breaker, lógica de reintento, respuestas de fallback | 🟡 |
Estado general de confiabilidad: 80% completo (4/5 ✅, 1/5 🟡)
Brechas:
- NFR-28: Circuit breaker para APIs externas (GPT-4, SendGrid) parcialmente implementado; necesita completarse
Requisitos de Mantenibilidad
| ReqID | Requisito | Métrica | Meta | Verificación | Implementación | Estado |
|---|---|---|---|---|---|---|
| NFR-29 | Base de código logra alta cobertura de pruebas | Porcentaje de cobertura de código | ≥ 80% (unit + integration) | Reportes de cobertura CI/CD | Jest (backend), Vitest (frontend), herramientas de cobertura | 🟡 |
| NFR-30 | Código sigue reglas consistentes de estilo y linting | % de archivos que pasan linting | 100% | ESLint en pipeline CI/CD | ESLint con reglas TypeScript, formateo Prettier | ✅ |
| NFR-31 | Documentación de API siempre actualizada | % de endpoints documentados en Swagger | 100% | Validación Swagger UI | Decoradores @nestjs/swagger, OpenAPI auto-generado | ✅ |
| NFR-32 | Logging habilita troubleshooting efectivo | % de operaciones críticas registradas | 100% con contexto (traceId, userId) | Análisis de logs durante incidentes | Logging estructurado JSON Winston, IDs de correlación | ✅ |
| NFR-33 | Despliegues automatizados vía CI/CD | % de despliegues vía pipeline | 100% (sin despliegues manuales) | Registro de auditoría de despliegues | Azure Pipelines con build/test/deploy automatizado | ✅ |
| NFR-34 | Cambios de esquema de base de datos gestionados con migraciones | % de cambios de esquema vía migraciones | 100% | Seguimiento de versión de esquema | Esquemas Mongoose, scripts de migración manual | 🟡 |
Estado general de mantenibilidad: 67% completo (4/6 ✅, 2/6 🟡)
Brechas:
- NFR-29: Cobertura de pruebas actualmente ~70%; meta es 80%+
- NFR-34: Migraciones de base de datos no automatizadas; proceso manual propenso a errores
Requisitos de Usabilidad
| ReqID | Requisito | Métrica | Meta | Verificación | Implementación | Estado |
|---|---|---|---|---|---|---|
| NFR-35 | Dashboard cumple estándares de accesibilidad | Nivel de cumplimiento WCAG 2.1 | AA (mínimo) | Auditoría de accesibilidad con axe-core | Componentes accesibles shadcn/ui, etiquetas ARIA | 🟡 |
| NFR-36 | Dashboard responsivo en dispositivos móviles | % de páginas optimizadas para móvil | 100% | Pruebas manuales en 3+ dispositivos | Utilidades responsivas Tailwind, diseño mobile-first | ✅ |
| NFR-37 | Mensajes de error son claros y accionables | % de errores con mensajes amigables al usuario | 100% | Revisión UX, pruebas de usuario | Mensajes de excepción personalizados, notificaciones toast | ✅ |
| NFR-38 | Conversaciones del bot de WhatsApp son intuitivas | Tasa de éxito de conversación | ≥ 90% (usuarios completan flujo) | Análisis de conversaciones | Diseño UX Jelou, comprensión de lenguaje natural GPT-4 | 🟡 |
| NFR-39 | Tiempo de carga del dashboard cumple expectativas del usuario | Tiempo hasta primera interacción | < 3 segundos en 4G | Auditoría Lighthouse | Code splitting, lazy loading, optimización de imágenes | ✅ |
Estado general de usabilidad: 60% completo (3/5 ✅, 2/5 🟡)
Brechas:
- NFR-35: Auditoría de accesibilidad no completada; cumplimiento parcial WCAG AA
- NFR-38: Tasa de éxito de conversación WhatsApp no medida; solo evidencia anecdótica
Requisitos de Cumplimiento
| ReqID | Requisito | Métrica | Meta | Verificación | Implementación | Estado |
|---|---|---|---|---|---|---|
| NFR-40 | Sistema cumple con protección de datos GDPR | Lista de verificación de cumplimiento GDPR | 100% de cumplimiento | Auditoría legal, mapeo de datos | Cifrado de datos, seguimiento de consentimiento de usuario, API de eliminación de datos | ✅ |
| NFR-41 | Sistema cumple con leyes colombianas de protección de datos (Ley 1581) | Lista de verificación de cumplimiento | 100% de cumplimiento | Revisión legal | Acuerdos de procesamiento de datos, consentimiento opt-in, avisos de privacidad | ✅ |
| NFR-42 | Registro de auditoría captura todas las operaciones críticas | % de cambios de estado registrados | 100% | Revisión de registro de auditoría | Entidad OrderHistory, patrón event sourcing | ✅ |
| NFR-43 | Consentimiento de usuario rastreado para procesamiento de datos | % de usuarios con registros de consentimiento | 100% | Auditoría de base de datos | Seguimiento de consentimiento en entidad User, flujo de Términos y Condiciones | ✅ |
| NFR-44 | Políticas de retención de datos aplicadas | Eliminación automática después del período de retención | Datos de usuario eliminados después de cierre de cuenta + 90 días | Pruebas de política de retención | Trabajos programados para purga de datos (recomendado, no implementado) | 🔴 |
Estado general de cumplimiento: 80% completo (4/5 ✅, 1/5 🔴)
Brechas:
- NFR-44: Políticas de retención de datos no automatizadas; se requiere limpieza manual
Requisitos Operacionales
| ReqID | Requisito | Métrica | Meta | Verificación | Implementación | Estado |
|---|---|---|---|---|---|---|
| NFR-45 | Sistema monitoreado con dashboards en tiempo real | % de servicios con dashboards | 100% | Revisión de dashboard | Dashboards Grafana con métricas Prometheus | ✅ |
| NFR-46 | Logs agregados para análisis centralizado | % de servicios enviando logs a Loki | 100% | Validación de agregación de logs | Pipeline Winston → Grafana Alloy → Loki | ✅ |
| NFR-47 | Health checks habilitan recuperación automatizada | % de servicios con endpoint /health | 100% | Pruebas de health check | Health checks @nestjs/terminus, sondas Kubernetes | ✅ |
| NFR-48 | Alertas se activan para fallos críticos | % de escenarios críticos con alertas | 100% | Pruebas de alerta, respuesta a incidentes | Reglas de alertas Grafana (recomendado, parcial) | 🟡 |
| NFR-49 | Despliegues tienen estrategia de cero tiempo de inactividad | Tiempo de inactividad durante despliegue | 0 segundos | Pruebas de despliegue | Actualizaciones progresivas, health checks, sondas de preparación | ✅ |
| NFR-50 | Respuesta a incidentes documentada y probada | Cobertura de runbook para incidentes | 100% de escenarios críticos | Revisión de runbook, simulacro DR | Runbooks en /wiki/05-operations/ | 🟡 |
Estado general operacional: 67% completo (4/6 ✅, 2/6 🟡)
Brechas:
- NFR-48: Reglas de alerta parcialmente configuradas; se necesita cobertura exhaustiva
- NFR-50: Runbooks existen pero no probados mediante simulacros de recuperación ante desastres
Matriz General de Verificación
| Categoría | NFRs Totales | Completo (✅) | Parcial (🟡) | Brecha (🔴) | % Cumplimiento |
|---|---|---|---|---|---|
| Rendimiento | 8 | 7 | 1 | 0 | 88% |
| Seguridad | 10 | 8 | 1 | 1 | 90% |
| Escalabilidad | 5 | 4 | 1 | 0 | 80% |
| Confiabilidad | 5 | 4 | 1 | 0 | 80% |
| Mantenibilidad | 6 | 4 | 2 | 0 | 67% |
| Usabilidad | 5 | 3 | 2 | 0 | 60% |
| Cumplimiento | 5 | 4 | 0 | 1 | 80% |
| Operacional | 6 | 4 | 2 | 0 | 67% |
| TOTAL | 50 | 38 | 10 | 2 | 82% |
Cumplimiento general de NFR: 82% (38 completo, 10 parcial, 2 brechas)
Brechas Críticas y Recomendaciones
Prioridad 1 (P1): Brechas críticas de seguridad
| Brecha | Requisito | Recomendación | Cronograma |
|---|---|---|---|
| Rate Limiting | NFR-13 | Implementar @nestjs/throttler en API Gateway con 100 req/min por IP | Q1 2026 |
| Retención de Datos | NFR-44 | Trabajos automatizados de purga de datos para cumplimiento GDPR/Ley 1581 | Q1 2026 |
Prioridad 2 (P2): Mejoras de calidad y operacionales
| Brecha | Requisito | Recomendación | Cronograma |
|---|---|---|---|
| Cobertura de Pruebas | NFR-29 | Aumentar cobertura de 70% a 80%+ mediante pruebas de integración | Q1 2026 |
| Completitud de Circuit Breaker | NFR-28 | Completar circuit breaker para todas las APIs externas (GPT-4, SendGrid) | Q1 2026 |
| Migraciones de Base de Datos | NFR-34 | Implementar herramienta de migración automatizada (ej. migrate-mongo) | Q2 2026 |
| Auditoría de Accesibilidad | NFR-35 | Completar auditoría WCAG AA y remediación | Q2 2026 |
| Cobertura de Alertas | NFR-48 | Configurar alertas Grafana para todos los escenarios críticos | Q1 2026 |
| Simulacros DR | NFR-50 | Ejecutar simulacros de recuperación ante desastres trimestralmente | Q2 2026 |
Prioridad 3 (P3): Optimización de rendimiento
| Brecha | Requisito | Recomendación | Cronograma |
|---|---|---|---|
| Tiempo de Respuesta WhatsApp | NFR-03 | Optimizar llamadas API GPT-4 con caché y procesamiento paralelo | Q2 2026 |
| Rendimiento de Listado de Subastas | NFR-05 | Implementar listas virtualizadas para 100+ tarjetas de subasta | Q2 2026 |
| Pruebas de Carga del Dashboard | NFR-23 | Conducir pruebas de carga con 500 usuarios concurrentes | Q2 2026 |
Referencias Cruzadas
Documentación de requisitos relacionados
- Requisitos de Negocio - Contexto de negocio, objetivos, decisiones estratégicas
- Requisitos Funcionales - Especificaciones funcionales con trazabilidad
Documentación de arquitectura
- Descripción General de Microservicios de Backend - Clean Architecture, CQRS, patrones event-driven
- Arquitectura de API Gateway - Enrutamiento de gateway, auth, circuit breaker
- Descripción General de Dashboard de Frontend - Arquitectura React, patrones de rendimiento
Documentación de operaciones
- Operaciones de Seguridad - Autenticación JWT, RBAC, Azure Key Vault, certificados TLS
- Monitoreo y Logging - Grafana, Prometheus, Loki, logging Winston
- Infraestructura como Código - Terraform, recursos Azure, pipelines CI/CD
Documentación de pruebas
- Guía de Pruebas - Estrategia y ejecución de pruebas unitarias, de integración y E2E
Documentación de funcionalidades
- Descripción General de Funcionalidades - Las 7 áreas de funcionalidad con estado de completitud
- Matriz de Trazabilidad - Mapeo Requisitos ↔ Implementación ↔ Pruebas
Última Actualización: 2025-11-20 Próxima Revisión: Después de completar fase de garantía (Q1 2026) Propietario del Documento: Arquitecto Técnico + Líder de DevOps