Requisitos Funcionales
Tabla de Contenidos
- Introducción
- Propósito y Alcance del Documento
- Requisitos por Área de Funcionalidad
- Matriz de Trazabilidad
- Resumen de Verificación
- Referencias Cruzadas
Introducción
Este documento define los requisitos funcionales para la Plataforma de Gestión de Mantenimiento Algesta. Cada requisito es trazable a:
- Sprint donde fue implementado (S1-S8)
- Historias de usuario del backlog
- Archivos de implementación en el código base
- Evidencia de pruebas de notas de pruebas
- Estado (✅ Completo, 🟡 En Progreso, 🔴 Pendiente)
Los requisitos están organizados por las 7 áreas principales de funcionalidad de la plataforma.
Propósito y Alcance del Documento
Propósito
Este documento sirve como la fuente autorizada para todos los requisitos funcionales de la plataforma Algesta. Permite:
- A los propietarios de producto verificar completitud de funcionalidades
- A los desarrolladores entender comportamientos esperados
- Ingenieros QA para crear planes de prueba y verificar implementación
- Auditores para trazar requisitos a implementación y pruebas
Alcance
Cubre todos los requisitos funcionales para:
- Ciclo de vida de gestión de órdenes (15+ estados)
- Sistema de marketplace y subastas
- Registro y gestión de proveedores
- Seguimiento del ciclo de vida de activos
- Flujos de trabajo de cotización y aprobaciones
- Reportes y dashboards de KPIs
- Integraciones con sistemas externos
Fuera de Alcance
- Requisitos no funcionales (ver non-functional-requirements.md)
- Requisitos de infraestructura (ver infrastructure-as-code.md)
- Requisitos de negocio (ver business-requirements.md)
Requisitos por Área de Funcionalidad
RF-01: Gestión de Órdenes
La gestión de órdenes es el núcleo de la plataforma, manejando el ciclo de vida completo desde la creación hasta la ejecución y cierre.
RF-01.01: Captura de Órdenes por WhatsApp
| ID Req | RF-01.01 |
|---|---|
| Descripción | El cliente puede crear una orden de mantenimiento enviando un mensaje de WhatsApp al bot Jelou |
| Prioridad | P0 (Crítico) |
| Sprint | S2 |
| Historias | Integración Canal WhatsApp Business |
| Implementación | algesta-ms-orders-nestjs/src/application/commands/create-order/, Jelou bot skills |
| Evidencia | Notas de pruebas Sprint 2 |
| Estado | 🟡 Implementado con bugs por corregir |
Criterios de Aceptación:
- El cliente envía mensaje de WhatsApp al bot Jelou
- El bot clasifica el tipo de servicio usando GPT-4 (13 categorías: Plomería, Electricidad, Aires-Refrigeración, etc.)
- El bot extrae información del activo de las fotos usando GPT-4 Vision (serial, modelo, S/N)
- El bot recopila: descripción del problema, ubicación, ciudad, fotos, preferencia de horario
- La orden se crea en el MS de Órdenes con estado “CREATED”
- El cliente recibe confirmación con ID de orden
RF-01.02: Máquina de Estados de Órdenes
| ID Req | RF-01.02 |
|---|---|
| Descripción | El sistema debe aplicar una máquina de estados válida con 15+ estados y transiciones controladas |
| Prioridad | P0 (Crítico) |
| Sprint | S2-S8 |
| Historias | Definición de estados de órdenes (S2-S3), Estado transaccional (S7-S8) |
| Implementación | algesta-ms-orders-nestjs/src/domain/order.entity.ts, state handlers |
| Evidencia | Notas de pruebas de todos los Sprints |
| Estado | ✅ Implementado |
Estados (15+):
- CREATED - Estado inicial desde WhatsApp
- PENDIENTE - Pendiente revisión del agente
- PUBLICADA_SUBASTA - Publicada en marketplace
- EN_SUBASTA - Subasta activa
- SUBASTA_CERRADA - Subasta cerrada
- PROVEEDOR_ASIGNADO - Proveedor seleccionado
- COTIZACION_ENVIADA - Cotización enviada por el proveedor
- COTIZACION_APROBADA - Cotización aprobada por el cliente
- PROGRAMADA - Fecha de ejecución confirmada
- EN_EJECUCION - Trabajo en progreso
- TRABAJO_FINALIZADO - Proveedor reporta trabajo completo
- PENDIENTE_APROBACION_CLIENTE - Esperando aprobación final del cliente
- APROBADA_CLIENTE - Cliente aprobó
- CERRADA - Orden cerrada
- CANCELADA - Orden cancelada
Criterios de Aceptación:
- Solo se permiten transiciones válidas (aplicadas por lógica de dominio)
- El historial de estados se rastrea para auditoría
- Cada transición dispara las notificaciones apropiadas
RF-01.03: Gestión de Detalles de Orden
| ID Req | RF-01.03 |
|---|---|
| Descripción | Agentes y proveedores pueden ver y actualizar detalles de orden según su rol y estado de orden |
| Prioridad | P0 (Crítico) |
| Sprint | S2-S8 |
| Historias | Gestión de órdenes (S2-S3), Edición de orden (S7) |
| Implementación | algesta-ms-orders-nestjs/src/application/commands/update-order/, Componentes dashboard órdenes |
| Evidencia | Historia 16502 (Gestión de Solicitudes) |
| Estado | ✅ Implementado |
Criterios de Aceptación:
- Agentes pueden editar: tipo de servicio, urgencia, ubicación, asignar técnico, publicar en marketplace
- Proveedores pueden editar: notas de ejecución, estado de completitud (campos limitados)
- Clientes pueden ver estado de orden solo lectura
- Rastro de auditoría para todos los cambios
- La validación previene actualizaciones inválidas basadas en el estado
RF-01.04: Búsqueda y Filtrado de Órdenes
| ID Req | RF-01.04 |
|---|---|
| Descripción | Los usuarios pueden buscar y filtrar órdenes por múltiples criterios |
| Prioridad | P1 (Alto) |
| Sprint | S2-S8 |
| Historias | Gestión de solicitudes, Listado de órdenes |
| Implementación | algesta-ms-orders-nestjs/src/application/queries/get-all-orders/, Componente lista de órdenes |
| Evidencia | Historia 16502 |
| Estado | ✅ Implementado |
Criterios de Filtro:
- Rango de fechas (fecha de creación, fecha de ejecución)
- Estado (cualquiera de los 15+ estados)
- Prioridad (EMERGENCIA, PRIORITARIO, NORMAL)
- Tipo de servicio (13 categorías)
- Agente asignado
- Proveedor asignado
- Nombre/ID del cliente
- Número de serie del activo
- Ubicación/ciudad
Criterios de Aceptación:
- Los filtros se pueden combinar
- Resultados paginados (10/25/50/100 por página)
- Ordenar por: fecha, Prioridad, Estado
- Exportar a CSV/PDF
RF-01.05: Asignación de Órdenes
| ID Req | RF-01.05 |
|---|---|
| Descripción | Los agentes pueden asignar órdenes a técnicos internos o publicar en marketplace para proveedores externos |
| Prioridad | P0 (Crítico) |
| Sprint | S2-S4 |
| Historias | Asignación de técnico (S2), Publicación en marketplace (S4) |
| Implementación | algesta-ms-orders-nestjs/src/application/commands/assign-technician/, publish-to-marketplace/ |
| Evidencia | Notas de pruebas Sprint 4 |
| Estado | ✅ Implementado |
Modos de Asignación:
- Asignación Directa (técnico interno)
- Seleccionar técnico interno
- El técnico es notificado por email
- Estado → PROVEEDOR_ASIGNADO
- Publicación en Marketplace (proveedor externo)
- Configurar duración de subasta
- Agregar preguntas opcionales
- Estado → PUBLICADA_SUBASTA
- Proveedores elegibles notificados
Criterios de Aceptación:
- El agente selecciona el modo de asignación
- La validación asegura datos mínimos para marketplace (ubicación, urgencia, tipo de servicio)
- Se envían notificaciones a la parte asignada
RF-01.06: Notificaciones de Órdenes
| ID Req | RF-01.06 |
|---|---|
| Descripción | El sistema envía notificaciones multicanal para cambios de estado de órdenes |
| Prioridad | P0 (Crítico) |
| Sprint | S2-S8 |
| Historias | Notificaciones (S2-S8), Recordatorios (S6-S8) |
| Implementación | algesta-ms-notifications-nestjs/src/application/event-handlers/, Plantillas de notificación |
| Evidencia | Notas de pruebas de todos los Sprints |
| Estado | ✅ Email implementado, ✅ WhatsApp completamente integrado |
Disparadores de Notificación:
- Orden creada → Confirmación al cliente (WhatsApp)
- Publicada en marketplace → Proveedores elegibles (Email + WhatsApp)
- Proveedor seleccionado → Confirmación al proveedor (Email + WhatsApp)
- Cotización enviada → Solicitud de aprobación al cliente (WhatsApp)
- Cotización aprobada → Aviso de inicio al proveedor (Email + WhatsApp)
- Fecha de ejecución confirmada → Recordatorio al cliente (WhatsApp)
- Trabajo completado → Solicitud de aprobación al cliente (WhatsApp)
- Orden cerrada → Confirmación a todas las partes (Email)
Canales:
- ✅ Email (SendGrid)
- ✅ WhatsApp (Jelou) - completamente integrado
- 🔴 Notificaciones push (futuro)
Criterios de Aceptación:
- Notificaciones enviadas asincrónicamente
- Lógica de reintento para fallos (3 reintentos con backoff exponencial)
- Fallback a email si WhatsApp falla
- Historial de notificaciones rastreado
RF-01.07: Historial de Órdenes y Rastro de Auditoría
| ID Req | RF-01.07 |
|---|---|
| Descripción | El sistema mantiene historial transaccional completo de todos los cambios de orden para auditoría y cumplimiento |
| Prioridad | P1 (Alto) |
| Sprint | S2-S8 |
| Historias | Historial transaccional (S7-S8) |
| Implementación | algesta-ms-orders-nestjs/src/domain/order-history.entity.ts, Patrón Event sourcing |
| Evidencia | Notas de pruebas Sprint 7-8 |
| Estado | ✅ Implementado |
El Historial Captura:
- Transiciones de estado con timestamp
- Cambios de campos (valores antes/después)
- Actor (ID de usuario, rol)
- Metadatos del evento (dirección IP, user agent)
Criterios de Aceptación:
- Registros de historial inmutables
- Consultable por ID de orden, rango de fechas, actor
- Mostrar en vista de línea de tiempo del dashboard
- Exportar a PDF para cumplimiento
RF-01.08: Gestión de Urgencia y Prioridad
| ID Req | RF-01.08 |
|---|---|
| Descripción | El sistema soporta 3 niveles de urgencia con objetivos de SLA e indicadores visuales |
| Prioridad | P1 (Alto) |
| Sprint | S1-S4 |
| Historias | Manejo de urgencia (S4) |
| Implementación | Campo urgencia en entidad Order, lógica de cálculo de SLA |
| Evidencia | Notas de pruebas Sprint 4 |
| Estado | ✅ Implementado |
Niveles de Urgencia:
- EMERGENCIA (Rojo)
- SLA de respuesta: 2 horas
- SLA de resolución: 24 horas
- Visual: Insignia roja, arriba de la lista
- PRIORITARIO (Amarillo)
- SLA de respuesta: 8 horas
- SLA de resolución: 72 horas
- Visual: Insignia amarilla
- NORMAL (Verde)
- SLA de respuesta: 24 horas
- SLA de resolución: 5 días hábiles
- Visual: Insignia verde
Criterios de Aceptación:
- La urgencia se establece durante la creación de orden (clasificación por IA o anulación del agente)
- Cuenta regresiva de SLA visible en el dashboard
- El incumplimiento del SLA dispara notificación de escalamiento
- Las órdenes vencidas se resaltan
RF-01.09: Programación de Visita Técnica
| ID Req | RF-01.09 |
|---|---|
| Descripción | El sistema soporta programación y gestión de visitas técnicas (virtuales o presenciales) |
| Prioridad | P1 (Alto) |
| Sprint | S6-S8 |
| Historias | Visita técnica (S6-S8), Informe de visita técnica (S6) |
| Implementación | algesta-ms-orders-nestjs/src/application/commands/schedule-visit/, Entidad Visit |
| Evidencia | Notas de pruebas Sprint 6-8 |
| Estado | ✅ Implementado |
Tipos de Visita:
- Virtual (Liderada por agente)
- Videollamada o teléfono
- El agente captura los detalles
- Fotos subidas por el agente
- Presencial (Liderada por proveedor)
- El proveedor visita el sitio
- El proveedor captura detalles y fotos
Criterios de Aceptación:
- Programar visita con fecha/hora, tipo, parte asignada
- El informe de visita captura: hallazgos, recomendaciones, fotos, costo estimado
- El informe dispara el flujo de cotización
- El historial de visitas está vinculado a la orden
RF-01.10: Confirmación de Ejecución
| ID Req | RF-01.10 |
|---|---|
| Descripción | El proveedor confirma la fecha de ejecución, el sistema envía recordatorio al cliente vía WhatsApp |
| Prioridad | P1 (Alto) |
| Sprint | S6-S8 |
| Historias | Confirmar fecha de ejecución (S6-S8) |
| Implementación | algesta-ms-orders-nestjs/src/application/commands/confirm-execution-date/, Notificación WhatsApp |
| Evidencia | Notas de pruebas Sprint 8 |
| Estado | 🟡 Implementado con bugs |
Criterios de Aceptación:
- El proveedor selecciona fecha de ejecución del calendario
- El sistema valida que la fecha sea futura, dentro de la validez de la cotización
- El cliente recibe confirmación por WhatsApp con la fecha
- El proveedor recibe invitación de calendario (email)
- Estado → PROGRAMADA
RF-02: Marketplace y Subastas
El marketplace permite licitación competitiva para órdenes de mantenimiento a través de un sistema de subasta inversa.
RF-02.01: Publicación de Subasta
| ID Req | RF-02.01 |
|---|---|
| Descripción | El agente publica orden en marketplace como subasta con parámetros configurables |
| Prioridad | P0 (Crítico) |
| Sprint | S4 |
| Historias | Historia 16544 - Publicación de órdenes en marketplace |
| Implementación | algesta-ms-provider-nestjs/src/application/commands/publish-auction/, Entidad Auction |
| Evidencia | Notas de pruebas Sprint 4, Historia 16544 |
| Estado | ✅ Implementado |
Parámetros de Subasta:
- Duración: 24h, 48h, 72h (configurable)
- Proveedores mínimos: 3 (requerido para subasta válida)
- Preguntas opcionales para proveedores
- Visibilidad: Ofertas anónimas
Criterios de Aceptación:
- El agente configura parámetros de subasta
- El sistema valida datos mínimos (tipo de servicio, ubicación, urgencia, fotos)
- El sistema identifica proveedores elegibles (ubicación, documentación válida, activo)
- Si no hay proveedores elegibles → error “No hay proveedores disponibles”
- Subasta creada en MS de Proveedores
- Estado → PUBLICADA_SUBASTA
- Proveedores elegibles notificados vía email + WhatsApp
RF-02.02: Ofertas Anónimas
| ID Req | RF-02.02 |
|---|---|
| Descripción | Los proveedores envían ofertas anónimas visibles solo para agentes, no para otros proveedores |
| Prioridad | P0 (Crítico) |
| Sprint | S4 |
| Historias | Ofertas anónimas (S4) |
| Implementación | algesta-ms-provider-nestjs/src/application/commands/submit-offer/, Entidad Offer |
| Evidencia | Notas de pruebas Sprint 4 |
| Estado | ✅ Implementado |
Componentes de la Oferta:
- Precio propuesto (total o itemizado)
- Duración estimada
- Fecha de disponibilidad de inicio
- Comentarios opcionales
- Respuestas a preguntas opcionales
Criterios de Aceptación:
- Los proveedores ven detalles de la orden (tipo de servicio, ubicación, urgencia, fotos) sin nombre del cliente
- Los proveedores envían oferta antes de que cierre la subasta
- Las ofertas son visibles solo para agentes
- Otros proveedores no pueden ver ofertas de competidores
- El proveedor puede actualizar oferta antes del cierre
- El conteo de ofertas es visible para todos (ej. “3 ofertas recibidas”)
RF-02.03: Selección de Proveedor
| ID Req | RF-02.03 |
|---|---|
| Descripción | El agente selecciona proveedor ganador de las ofertas recibidas basado en precio, calidad y elegibilidad |
| Prioridad | P0 (Crítico) |
| Sprint | S4 |
| Historias | Selección de proveedor ganador (S4) |
| Implementación | algesta-ms-provider-nestjs/src/application/commands/select-winner/, Flujo de selección |
| Evidencia | Notas de pruebas Sprint 4 |
| Estado | ✅ Implementado |
Criterios de Selección (El agente decide):
- Precio más bajo (no seleccionado automáticamente)
- Documentación del proveedor válida
- Historial de desempeño del proveedor
- Disponibilidad
Criterios de Aceptación:
- El agente ve todas las ofertas ordenadas por precio
- El agente puede ver el puntaje de desempeño del proveedor
- El agente selecciona la oferta ganadora
- El sistema valida elegibilidad del proveedor (documentación no expirada)
- Si la documentación expiró → advertencia “Documentación vencida”
- El proveedor seleccionado es notificado
- Los proveedores no seleccionados son notificados
- Estado → PROVEEDOR_ASIGNADO
- La orden se asigna al proveedor seleccionado en el MS de Órdenes
RF-02.04: Cierre de Subasta
| ID Req | RF-02.04 |
|---|---|
| Descripción | Las subastas cierran automáticamente después de la duración configurada o cierre manual por agente |
| Prioridad | P1 (Alto) |
| Sprint | S4 |
| Historias | Cierre de subasta (S4) |
| Implementación | algesta-ms-provider-nestjs/src/application/scheduled-tasks/close-expired-auctions.task.ts |
| Evidencia | Notas de pruebas Sprint 4 |
| Estado | ✅ Implementado |
Modos de Cierre:
- Automático - Tarea programada verifica subastas expiradas cada hora, cierra si la duración se cumplió
- Manual - El agente cierra la subasta anticipadamente
Criterios de Aceptación:
- La tarea programada se ejecuta cada hora
- Si no se cumplen las ofertas mínimas (3) → subasta marcada “Sin suficientes ofertas”
- Estado → SUBASTA_CERRADA
- Los proveedores ya no pueden enviar ofertas
- El agente puede seleccionar ganador o republicar
RF-02.05: Visibilidad y Filtros del Marketplace
| ID Req | RF-02.05 |
|---|---|
| Descripción | Proveedores y agentes pueden ver órdenes del marketplace con filtros y ordenamiento |
| Prioridad | P1 (Alto) |
| Sprint | S4-S8 |
| Historias | Vista pública anonimizada (S4), Marketplace UX (S8) |
| Implementación | Queries MS Provider, Componente dashboard Marketplace |
| Evidencia | Notas de pruebas Sprint 4-8 |
| Estado | 🟡 Implementado, mejoras de UX pendientes |
Vista del Proveedor (Anónima):
- Tipo de servicio
- Ubicación (general, no dirección exacta)
- Nivel de urgencia
- Fotos del activo/problema
- Duración estimada
- Conteo de ofertas
- Oculto: Nombre del cliente, dirección exacta
Vista del Agente (Completa):
- Todos los detalles de la orden
- Conteo de ofertas y precios
- Identidades de proveedores
Filtros:
- Tipo de servicio
- Ubicación/ciudad
- Urgencia
- Estado (abierta, cerrada)
- Rango de fechas
Mejoras de UX Pendientes (backlog S8):
- Marcar mejor oferta automáticamente
- Vista de tarjetas (vs tabla)
- Filtros avanzados
Criterios de Aceptación:
- Los proveedores ven solo órdenes elegibles para su ubicación
- Los proveedores no pueden acceder a PII del cliente
- Los agentes ven todas las subastas
RF-03: Gestión de Proveedores
La gestión de proveedores maneja registro, validación de documentos, elegibilidad y seguimiento de desempeño.
RF-03.01: Registro de Proveedores
| ID Req | RF-03.01 |
|---|---|
| Descripción | Los proveedores externos pueden auto-registrarse con información de empresa y contacto |
| Prioridad | P0 (Crítico) |
| Sprint | S3 |
| Historias | Registro de proveedor (S3) |
| Implementación | algesta-ms-provider-nestjs/src/application/commands/create-provider/, Entidad Provider |
| Evidencia | Notas de pruebas Sprint 3 |
| Estado | ✅ Implementado |
Datos de Registro:
- Nombre de empresa, NIT, representante legal
- Contacto: email, teléfono, WhatsApp
- Categorías de servicio (seleccionar múltiples de 13 categorías)
- Ubicaciones de cobertura (ciudades)
- Información de cuenta bancaria
Criterios de Aceptación:
- El proveedor completa el formulario de registro
- Se requiere verificación de email
- Validación de NIT único
- Proveedor creado con estado “PENDIENTE_DOCUMENTOS”
- Email de bienvenida enviado
RF-03.02: Carga y Validación de Documentos
| ID Req | RF-03.02 |
|---|---|
| Descripción | Los proveedores cargan documentos legales requeridos; los agentes validan y aprueban/rechazan |
| Prioridad | P0 (Crítico) |
| Sprint | S3 |
| Historias | Carga de documentos de certificación (S3) |
| Implementación | algesta-ms-provider-nestjs/src/application/commands/upload-Documento/, Documento entity, Azure Blob Storage |
| Evidencia | Notas de pruebas Sprint 3 |
| Estado | ✅ Implementado |
Documentos Requeridos:
- ARL (Seguro de Riesgos Laborales) - Fecha de vencimiento requerida
- EPS (Seguro de Salud) - Fecha de vencimiento requerida
- RUT (Registro Tributario) - Sin vencimiento
- Certificado de Experiencia - Sin vencimiento
- Seguro de Responsabilidad (opcional) - Fecha de vencimiento si se proporciona
Restricciones de Archivo:
- Formatos: PDF, JPG, PNG
- Tamaño máximo: 5 MB por archivo
- Almacenamiento: Azure Blob Storage
Estados de Documento:
- PENDIENTE - Cargado, esperando revisión
- EN_REVISION - Agente revisando
- APROBADO - Agente aprobó
- RECHAZADO - Agente rechazó (razón requerida)
- VENCIDO - Vencido (detectado automáticamente)
Criterios de Aceptación:
- El proveedor carga documento
- Archivo validado (formato, tamaño)
- Estado del documento → EN_REVISION
- El agente revisa y aprueba/rechaza
- Si se aprueba → estado → APROBADO
- Si se rechaza → estado → RECHAZADO, razón requerida, proveedor notificado
- Si el documento tiene vencimiento → verificación programada para expiración
RF-03.03: Gestión de Vencimiento de Documentos
| ID Req | RF-03.03 |
|---|---|
| Descripción | El sistema verifica automáticamente fechas de vencimiento de documentos y notifica a proveedores antes de la expiración |
| Prioridad | P1 (Alto) |
| Sprint | S3-S7 |
| Historias | Vencimientos de documentos (S3), Gestión automatizada de vencimientos (S7) |
| Implementación | algesta-ms-provider-nestjs/src/application/scheduled-tasks/check-Documento-expiry.task.ts |
| Evidencia | Notas de pruebas Sprint 7 |
| Estado | ✅ Implementado |
Lógica de Vencimiento:
- Tarea programada se ejecuta diariamente a las 2 AM
- Verifica todos los documentos con fechas de vencimiento
- Envía recordatorios:
- 30 días antes del vencimiento → recordatorio por email
- 15 días antes del vencimiento → email + WhatsApp
- 7 días antes del vencimiento → email + WhatsApp (urgente)
- En la fecha de vencimiento → Estado del documento → VENCIDO, proveedor suspendido del marketplace
Criterios de Aceptación:
- Los proveedores reciben recordatorios a los 30, 15, 7 días
- Al vencer, proveedor no elegible para nuevas subastas
- El proveedor puede cargar documento renovado
- Con la aprobación del nuevo documento, proveedor reactivado
RF-03.04: Elegibilidad de Proveedores
| ID Req | RF-03.04 |
|---|---|
| Descripción | El sistema determina la elegibilidad del proveedor para subastas del marketplace basándose en documentación, ubicación y categorías de servicio |
| Prioridad | P0 (Crítico) |
| Sprint | S3-S4 |
| Historias | Validación de proveedores elegibles (S4) |
| Implementación | algesta-ms-provider-nestjs/src/application/queries/get-eligible-providers/, Eligibility logic |
| Evidencia | Notas de pruebas Sprint 4 |
| Estado | ✅ Implementado |
Criterios de Elegibilidad:
- Documentación: Todos los documentos requeridos APROBADO y no VENCIDO
- Ubicación: La cobertura del proveedor incluye la ubicación de la orden
- Categoría de Servicio: El proveedor ofrece el tipo de servicio de la orden
- Estado: Estado del proveedor ACTIVO (no suspendido)
Criterios de Aceptación:
- El sistema filtra proveedores elegibles cuando se publica la subasta
- Solo se notifica a proveedores elegibles
- Si no hay proveedores elegibles → el agente recibe error
- Los proveedores pueden ver por qué no son elegibles (ej., “Documentación vencida”)
RF-03.05: Seguimiento de Desempeño de Proveedores
| ID Req | RF-03.05 |
|---|---|
| Descripción | El sistema rastrea métricas de desempeño del proveedor (tasa de completitud, satisfacción del cliente, cumplimiento de SLA) |
| Prioridad | P2 (Medio) |
| Sprint | S7-S8 |
| Historias | Tracking de performance (S7-S8) |
| Implementación | algesta-ms-provider-nestjs/src/domain/provider-performance.entity.ts, KPI calculations |
| Evidencia | Notas de pruebas Sprint 7-8 |
| Estado | 🟡 Parcialmente implementado |
Métricas de Desempeño:
- Tasa de Completitud: % de órdenes asignadas completadas exitosamente
- Satisfacción del Cliente: Calificación promedio de clientes (1-5 estrellas)
- Cumplimiento de SLA: % de órdenes que cumplen objetivos de SLA
- Tasa de Rechazo: % de cotizaciones rechazadas por clientes
Criterios de Aceptación:
- Las métricas se calculan después del cierre de cada orden
- El puntaje de desempeño visible para agentes durante la selección de proveedor
- Proveedores con bajo desempeño marcados para revisión
- Los proveedores pueden ver su propio dashboard de desempeño
Estado: Seguimiento básico implementado, dashboard completo pendiente.
RF-03.06: Listado y Búsqueda de Proveedores
| ID Req | RF-03.06 |
|---|---|
| Descripción | Los agentes pueden ver y buscar todos los proveedores con filtros |
| Prioridad | P1 (Alto) |
| Sprint | S7-S8 |
| Historias | Listado de proveedores (S7-S8) |
| Implementación | algesta-ms-provider-nestjs/src/application/queries/get-all-providers/, Provider list Componente |
| Evidencia | Notas de pruebas Sprint 8 |
| Estado | ✅ Implementado |
Filtros:
- Categorías de servicio
- Ubicación/ciudad
- Estado (ACTIVO, SUSPENDIDO, INACTIVO)
- Estado de documentación (COMPLETO, INCOMPLETO, VENCIDO)
- Puntaje de desempeño
Criterios de Aceptación:
- Lista paginada (10/25/50/100 por página)
- Ordenar por: nombre, desempeño, fecha de registro
- Exportar a CSV/PDF
RF-04: Gestión de Activos
La gestión de activos mantiene el historial del ciclo de vida de los activos de mantenimiento con reconocimiento de serial basado en OCR.
RF-04.01: Creación de Activos (Manual y Automática)
| ID Req | RF-04.01 |
|---|---|
| Descripción | El sistema crea registros de activos manualmente o automáticamente desde fotos de órdenes usando OCR |
| Prioridad | P0 (Crítico) |
| Sprint | S6-S8 |
| Historias | Gestión automatizada de hoja de vida (S7), Crear activo (S7) |
| Implementación | algesta-ms-orders-nestjs/src/application/commands/create-asset/, GPT-4 Vision OCR service |
| Evidencia | Notas de pruebas Sprint 7, Historia 16016 |
| Estado | 🟡 Implementado con bugs |
Modos de Creación:
-
Automático (desde foto):
- Carga de foto por WhatsApp
- GPT-4 Vision extrae: número de serial, número de modelo, S/N
- Si el serial es legible → buscar activo existente por serial
- Si existe → vincular orden al activo
- Si no existe → crear nuevo activo con datos extraídos
- Si el serial no es legible → generar ID único, crear activo
-
Manual (por agente):
- El agente completa formulario con datos del activo
- Número de serial (requerido si está disponible)
- Modelo, marca, ubicación
- Cliente propietario
Criterios de Aceptación:
- Precisión de OCR > 80% para seriales legibles
- Lógica de reintento si OCR falla (3 intentos)
- El usuario confirma el serial extraído antes de crear el activo
- Detección de serial duplicado
- Activo creado con Estado “ACTIVO”
RF-04.02: Historial de Activo (Hoja de Vida)
| ID Req | RF-04.02 |
|---|---|
| Descripción | El sistema mantiene historial completo de mantenimiento para cada activo |
| Prioridad | P0 (Crítico) |
| Sprint | S6-S8 |
| Historias | Historial consolidado de HV (S7-S8), Historia 16016, Historia 17988 |
| Implementación | algesta-ms-orders-nestjs/src/domain/asset-history.entity.ts, Asset history query |
| Evidencia | Notas de pruebas Sprint 7-8 |
| Estado | 🟡 Implementado con bugs de persistencia |
El Historial Incluye:
- Todas las órdenes vinculadas al activo (cronológico)
- Tipo de mantenimiento para cada orden
- Proveedor para cada orden
- Fechas de ejecución
- Reportes y fotos
- Cambios de estado
- Adjuntos de documentos
Criterios de Aceptación:
- Historial consultable por ID de activo o serial
- Visualización cronológica (más reciente primero)
- Filtrar por: rango de fechas, tipo de mantenimiento, proveedor
- Exportar a PDF
- Paginación para historiales grandes (>50 registros)
Problemas Conocidos: Algunos campos no persisten correctamente (backlog S8).
RF-04.03: Búsqueda y Consulta de Activos
| ID Req | RF-04.03 |
|---|---|
| Descripción | Los usuarios pueden buscar activos por número de serial, ubicación o cliente |
| Prioridad | P1 (Alto) |
| Sprint | S7-S8 |
| Historias | Consulta de HV desde agente (S7), Acceso a HV (S8) |
| Implementación | algesta-ms-orders-nestjs/src/application/queries/get-asset-by-serial/, Asset search Componente |
| Evidencia | Notas de pruebas Sprint 8, Historia 17988 |
| Estado | ✅ Implementado |
Modos de Búsqueda:
- Número de serial (coincidencia exacta o parcial)
- Ubicación (edificio, piso, sala)
- Nombre/ID del cliente
- Tipo de activo (HVAC, plomería, eléctrico, etc.)
Criterios de Aceptación:
- La búsqueda devuelve resultados en <2 segundos
- Coincidencia parcial de serial soportada (ej., “ABC” coincide con “ABC123”)
- Resultados paginados
- Hacer clic en el activo para ver HV completa
RF-04.04: Gestión de Estados de Activo
| ID Req | RF-04.04 |
|---|---|
| Descripción | Los activos tienen estados de ciclo de vida que rastrean el estado operacional |
| Prioridad | P1 (Alto) |
| Sprint | S7-S8 |
| Historias | Estado transaccional de activo (S7-S8) |
| Implementación | Asset entity state field, state transition logic |
| Evidencia | Notas de pruebas Sprint 7-8 |
| Estado | ✅ Implementado |
Estados de Activo:
- ACTIVO - Operacional, en uso
- EN_MANTENIMIENTO - Actualmente en mantenimiento
- FUERA_DE_SERVICIO - Fuera de servicio (averiado)
- RETIRADO - Dado de baja
Transiciones de Estado:
- ACTIVO → EN_MANTENIMIENTO (cuando se asigna orden)
- EN_MANTENIMIENTO → ACTIVO (cuando la orden se cierra exitosamente)
- EN_MANTENIMIENTO → FUERA_DE_SERVICIO (si no es reparable)
- FUERA_DE_SERVICIO → ACTIVO (después de reemplazo/reparación)
- Cualquier estado → RETIRADO (permanente)
Criterios de Aceptación:
- Los cambios de estado se rastrean en el historial del activo
- Indicadores visuales en el dashboard (codificados por color)
- Los reportes muestran distribución de estados de activos
RF-04.05: Exportación de Activo a PDF
| ID Req | RF-04.05 |
|---|---|
| Descripción | El sistema genera exportación PDF del historial del activo para cumplimiento y reportes |
| Prioridad | P1 (Alto) |
| Sprint | S7-S8 |
| Historias | Exportación PDF de HV (S8) |
| Implementación | algesta-ms-orders-nestjs/src/application/commands/export-asset-pdf/, Puppeteer PDF generation |
| Evidencia | Notas de pruebas Sprint 8 |
| Estado | 🔴 Pendiente (backlog S8) |
Contenido del PDF:
- Encabezado del activo (serial, modelo, ubicación, cliente)
- Tabla de historial de mantenimiento
- Fotos de todas las órdenes
- Estadísticas de resumen (total de órdenes, último mantenimiento, costo promedio)
Criterios de Aceptación:
- PDF generado en <10 segundos
- Formato profesional con marca de la empresa
- Enlace de descarga enviado al usuario
- PDF almacenado en Azure Blob Storage
Estado: Aún no implementado (P1 en fase de garantía).
RF-05: Cotizaciones y Aprobaciones
Los flujos de trabajo de cotización permiten desglose de costos itemizado con aprobaciones multinivel.
RF-05.01: Desglose de Cotización (Agente)
| ID Req | RF-05.01 |
|---|---|
| Descripción | El agente desglosa la orden en plantilla de cotización itemizada para que el proveedor cotice |
| Prioridad | P0 (Crítico) |
| Sprint | S6-S8 |
| Historias | Cotización por ítems (S6-S8), Informe de cotización (S6) |
| Implementación | algesta-ms-orders-nestjs/src/application/commands/create-quotation-template/, Quotation entity |
| Evidencia | Notas de pruebas Sprint 6-8 |
| Estado | ✅ Implementado |
Proceso de Desglose:
- El agente revisa la orden y el informe de visita técnica
- El agente crea líneas de ítems:
- Descripción del ítem (ej., “Reemplazo de tubería”, “Mano de obra”)
- Cantidad
- Unidad de medida
- Categoría (mano de obra, materiales, equipo)
- El agente envía al proveedor para cotizar cada ítem
Criterios de Aceptación:
- Mínimo 1 ítem, máximo 50 ítems
- Descripciones de ítems requeridas
- Plantilla guardada con Estado “PENDIENTE_PROVEEDOR”
- Proveedor notificado para enviar precios
RF-05.02: Precio de Cotización (Proveedor)
| ID Req | RF-05.02 |
|---|---|
| Descripción | El proveedor ingresa precio unitario y total para cada ítem de cotización |
| Prioridad | P0 (Crítico) |
| Sprint | S6-S8 |
| Historias | Cotización por ítems (S6-S8) |
| Implementación | algesta-ms-orders-nestjs/src/application/commands/submit-quotation/, Quotation item entity |
| Evidencia | Notas de pruebas Sprint 6-8 |
| Estado | ✅ Implementado |
Proceso de Precio:
- El proveedor recibe plantilla de cotización
- El proveedor ingresa para cada ítem:
- Precio unitario
- Total (calculado o manual)
- Notas (opcional)
- El proveedor envía cotización
Criterios de Aceptación:
- Todos los ítems deben tener precio unitario > 0
- Total calculado automáticamente (precio unitario × cantidad)
- Gran total calculado de todos los ítems
- Periodo de validez de cotización: 30 días (configurable)
- Cotización guardada con Estado “ENVIADA_CLIENTE”
- Cliente notificado para aprobación
RF-05.03: Inflación de Cotización (Agente)
| ID Req | RF-05.03 |
|---|---|
| Descripción | El agente puede ajustar al alza los precios cotizados por el proveedor para margen o ajuste de mercado |
| Prioridad | P1 (Alto) |
| Sprint | S7-S8 |
| Historias | Inflar valores de cotización (S8) |
| Implementación | algesta-ms-orders-nestjs/src/application/commands/inflate-quotation/, Inflation calculation logic |
| Evidencia | Notas de pruebas Sprint 8 |
| Estado | 🟡 Implementado con bugs |
Proceso de Inflación:
- El agente revisa la cotización del proveedor
- El agente ajusta precios (porcentaje o monto fijo):
- Por ítem (ej., +10% en mano de obra)
- Global (ej., +15% en toda la cotización)
- El sistema recalcula totales
- Cotización ajustada enviada al cliente (el proveedor no ve el ajuste)
Criterios de Aceptación:
- Se soporta inflación en % o monto fijo
- Precios originales del proveedor ocultos del cliente
- Inflación rastreada en rastro de auditoría
- El cliente aprueba la cotización inflada
Problemas Conocidos: Casos extremos en cálculo causan totales incorrectos (backlog S8 P1).
RF-05.04: Aprobación de Cotización (Cliente)
| ID Req | RF-05.04 |
|---|---|
| Descripción | El cliente revisa y aprueba/rechaza la cotización itemizada |
| Prioridad | P0 (Crítico) |
| Sprint | S5-S8 |
| Historias | Aprobación de cliente (S5-S8) |
| Implementación | algesta-ms-orders-nestjs/src/application/commands/approve-quotation/, Approval workflow |
| Evidencia | Notas de pruebas Sprint 5-8 |
| Estado | ✅ Implementado |
Proceso de Aprobación:
- El cliente recibe cotización vía WhatsApp (desglose itemizado + total)
- El cliente revisa cada ítem y el total
- El cliente aprueba o rechaza:
- Aprobar → estado → COTIZACION_APROBADA, proveedor notificado para programar ejecución
- Rechazar → estado → COTIZACION_RECHAZADA, razón requerida, agente notificado
Criterios de Aceptación:
- El cliente ve desglose itemizado (no nombre del proveedor para proteger confidencialidad)
- El cliente puede solicitar cambios (desencadena negociación)
- Aprobación registrada en rastro de auditoría
- Notificaciones enviadas a todas las partes
RF-05.05: Aprobaciones Multinivel
| ID Req | RF-05.05 |
|---|---|
| Descripción | El sistema soporta flujos de trabajo de aprobación multinivel para cotizaciones por encima de umbrales |
| Prioridad | P2 (Medio) |
| Sprint | S6-S8 (parcial) |
| Historias | Aprobador 1, Aprobador 2 (S8) |
| Implementación | Approval chain entity, workflow engine |
| Evidencia | Notas de pruebas Sprint 8 |
| Estado | 🟡 Parcialmente implementado |
Niveles de Aprobación:
- Nivel 1 (Solicitante): Crea orden, puede aprobar hasta $X
- Nivel 2 (Gerente): Aprueba $X - $Y
- Nivel 3 (Director): Aprueba > $Y
Flujo de Trabajo:
- El monto de la cotización determina los niveles de aprobación requeridos
- Aprobaciones secuenciales (Nivel 1 → Nivel 2 → Nivel 3)
- Cualquier nivel puede rechazar → volver al proveedor
- Aprobación final → procede la ejecución
Criterios de Aceptación:
- Umbrales configurables por cliente
- Notificaciones por email en cada nivel
- Escalamiento si no hay respuesta en 48 horas
- Rastro de auditoría muestra todos los aprobadores
Estado: Implementación básica existe, motor de flujo de trabajo completo pendiente (backlog P2).
RF-06: Reportes y KPIs
Los reportes proporcionan información operacional y seguimiento de SLA.
RF-06.01: Dashboard de KPIs
| ID Req | RF-06.01 |
|---|---|
| Descripción | El sistema muestra 4 KPIs operacionales con actualizaciones en tiempo real y exploración detallada |
| Prioridad | P1 (Alto) |
| Sprint | S7-S8 |
| Historias | KPIs operativos (S7-S8), Dashboard de KPIs (S7) |
| Implementación | algesta-ms-orders-nestjs/src/application/queries/get-kpis/, KPI calculation service, Dashboard KPI Componente |
| Evidencia | Notas de pruebas Sprint 7-8 |
| Estado | ✅ Implementado |
KPIs:
-
Tiempo de Completitud de Orden
- Definición: Tiempo promedio desde creación hasta cierre
- Fórmula: AVG(fecha_cierre - fecha_creación) para todas las órdenes cerradas
- Objetivo: <5 días hábiles
- Visualización: Gráfico de líneas (últimos 30 días)
-
Tasa de Cumplimiento de SLA
- Definición: % de órdenes que cumplen objetivos de SLA por urgencia
- Fórmula: (Órdenes que cumplen SLA / Total de órdenes) × 100
- Objetivo: >90%
- Visualización: Gráfico circular (EMERGENCIA, PRIORITARIO, NORMAL)
-
Tiempo de Aprobación de Cotización
- Definición: Tiempo promedio desde envío de cotización hasta aprobación del cliente
- Fórmula: AVG(fecha_aprobación - fecha_envío_cotización)
- Objetivo: <48 horas
- Visualización: Gráfico de barras (por nivel de urgencia)
-
Puntaje de Desempeño del Proveedor
- Definición: Promedio ponderado de tasa de completitud, satisfacción del cliente, cumplimiento de SLA
- Fórmula: (0.4 × tasa_completitud + 0.3 × satisfacción_cliente + 0.3 × cumplimiento_sla)
- Objetivo: >80%
- Visualización: Tabla de clasificación (top 10 proveedores)
Criterios de Aceptación:
- Los KPIs se actualizan cada 5 minutos
- Exploración detallada para ver datos subyacentes
- Exportar a CSV/PDF
- Filtros de rango de fechas (últimos 7/30/90 días)
RF-06.02: Reportes de Órdenes
| ID Req | RF-06.02 |
|---|---|
| Descripción | El sistema genera reportes comprensivos para órdenes (cotización, ejecución, visita técnica) |
| Prioridad | P1 (Alto) |
| Sprint | S5-S8 |
| Historias | Informes (S5-S8), Informe de cotización (S6), Informe de ejecución (S6) |
| Implementación | algesta-ms-orders-nestjs/src/application/commands/generate-report/, Puppeteer PDF generation |
| Evidencia | Notas de pruebas Sprint 6-8 |
| Estado | ✅ Implementado |
Tipos de Reporte:
-
Reporte de Cotización
- Desglose itemizado de cotización
- Información del proveedor
- Periodo de validez
- Total general
- Términos y condiciones
-
Reporte de Ejecución
- Resumen del trabajo realizado
- Materiales utilizados
- Fotos antes/después
- Firma del proveedor
- Duración de ejecución
-
Reporte de Visita Técnica
- Hallazgos y observaciones
- Acciones recomendadas
- Costos estimados
- Fotos
- Firma del agente/proveedor
Criterios de Aceptación:
- Reportes generados como PDF
- Formato profesional con marca
- Entrega por descarga o email
- Almacenados en Azure Blob Storage
- Vinculados al historial de órdenes
FR-06.03: Seguimiento de SLA y Alertas
| Req ID | FR-06.03 |
|---|---|
| Descripción | El sistema rastrea cumplimiento de SLA y envía alertas cuando el SLA está en riesgo o incumplido |
| Prioridad | P1 (Alta) |
| Sprint | S7-S8 |
| Historias de Usuario | Seguimiento de SLA (S7-S8) |
| Implementación | Servicio de cálculo de SLA, Tarea programada para alertas de SLA |
| Evidencia de Pruebas | Notas de pruebas Sprint 7-8 |
| Estado | ✅ Implementado |
Objetivos de SLA (por urgencia):
- EMERGENCIA: Respuesta 2h, Resolución 24h
- PRIORITARIO: Respuesta 8h, Resolución 72h
- NORMAL: Respuesta 24h, Resolución 5 días hábiles
Alertas:
- En Riesgo (50% del tiempo de SLA transcurrido) → Bandera amarilla, email al agente
- Crítico (80% del tiempo de SLA transcurrido) → Bandera roja, email al agente + gerente
- Incumplido (100% transcurrido) → Email de escalamiento al director, impacto en KPI
Criterios de Aceptación:
- Tarea programada verifica SLAs cada hora
- Indicadores visuales en dashboard (verde/amarillo/rojo)
- Emails de alerta enviados automáticamente
- Tasa de incumplimiento de SLA rastreada en KPI
FR-06.04: Reportes de Rendimiento (Proveedor)
| Req ID | FR-06.04 |
|---|---|
| Descripción | El sistema genera reportes de rendimiento para proveedores mostrando métricas y tendencias |
| Prioridad | P2 (Media) |
| Sprint | S7-S8 (parcial) |
| Historias de Usuario | Reportes avanzados de KPIs (S8) |
| Implementación | Generación de reportes de rendimiento de proveedores |
| Evidencia de Pruebas | Notas de pruebas Sprint 8 |
| Estado | 🟡 Parcialmente implementado (solo reportes básicos) |
Contenido del Reporte:
- Órdenes completadas (cantidad, tendencia)
- Tasa de completitud (%)
- Satisfacción del cliente (calificación promedio)
- Cumplimiento de SLA (%)
- Tasa de rechazo (cotizaciones rechazadas)
- Ingresos generados
Criterios de Aceptación:
- Reportes filtrables por rango de fechas
- Gráficos para tendencias (línea/barra)
- Exportación a PDF/CSV
- Proveedores pueden ver sus propios reportes
- Agentes pueden ver todos los reportes de proveedores
Estado: Reportes básicos existen, reportes avanzados (por ubicación, categoría) pendiente (backlog P2).
FR-07: Integraciones Externas
Las integraciones conectan Algesta con sistemas externos para notificaciones, gestión de tareas y gestión de documentos.
FR-07.01: Integración de Email con SendGrid
| Req ID | FR-07.01 |
|---|---|
| Descripción | El sistema envía emails transaccionales vía SendGrid para todos los eventos del ciclo de vida de órdenes |
| Prioridad | P0 (Crítica) |
| Sprint | S2-S8 |
| Historias de Usuario | Notificaciones por correo (S2-S8) |
| Implementación | algesta-ms-notifications-nestjs/src/infrastructure/sendgrid/sendgrid.service.ts |
| Evidencia de Pruebas | Notas de pruebas de todos los Sprints |
| Estado | ✅ Completamente integrado |
Tipos de Email:
- Confirmación de creación de orden
- Notificación de subasta en marketplace
- Selección de proveedor
- Solicitud de aprobación de cotización
- Ejecución programada
- Trabajo completado
- Orden cerrada
- Alertas de SLA
- Recordatorios de vencimiento de documentos
Criterios de Aceptación:
- Plantillas de email HTML con marca
- Lógica de reintentos (3 intentos con backoff exponencial)
- Seguimiento de entrega vía webhooks de SendGrid
- Manejo de rebotes y spam
- Enlaces de desuscripción (para emails de marketing)
FR-07.02: Integración de WhatsApp con Jelou
| Req ID | FR-07.02 |
|---|---|
| Descripción | El sistema se integra con la plataforma de IA conversacional Jelou para captura de órdenes y notificaciones por WhatsApp |
| Prioridad | P0 (Crítica) |
| Sprint | S2-S8 |
| Historias de Usuario | Integración WhatsApp (S2-S8), 7 skills (S2-S8) |
| Implementación | Skills del bot Jelou, Endpoints de API en Orders MS, Notifications MS |
| Evidencia de Pruebas | Notas de pruebas Sprint 2-8 |
| Estado | 🟡 Integrado con bugs por corregir |
Skills de Jelou (7 flujos de trabajo conversacionales):
- Registro - Recolectar información del cliente (teléfono, NIT, empresa)
- Creación de Orden - Capturar solicitud de servicio (problema, ubicación, fotos)
- Seguimiento - Consultar estado de orden por ID o teléfono
- Generación de PDF - Enviar PDF de confirmación de orden
- Actualizaciones de Estado - Notificar al cliente de cambios de estado
- Confirmación de Ejecución - Confirmar fecha programada
- Notificaciones - Enviar recordatorios y alertas
Modelos de IA:
- GPT-4 para clasificación de servicios
- GPT-4 Vision para OCR de números de serie desde fotos
Criterios de Aceptación:
- Comunicación bidireccional (Jelou ↔ API Gateway ↔ Microservicios)
- Registro de mensajes para auditoría
- Timeout de 30 segundos para llamadas de API
- Mensajes de respaldo en caso de fallo de API
- Estado de sesión con TTL de 1 hora
Problemas Conocidos: Bugs en flujo de extremo a extremo, mejoras de manejo de errores necesarias (P0 en fase de garantía).
FR-07.03: Integración con Asana
| Req ID | FR-07.03 |
|---|---|
| Descripción | El sistema crea y actualiza tareas en Asana para coordinación operacional interna |
| Prioridad | P1 (Alta) |
| Sprint | S5-S8 (parcial) |
| Historias de Usuario | Integración Asana (S5-S8) |
| Implementación | algesta-ms-orders-nestjs/src/infrastructure/external/asana.service.ts |
| Evidencia de Pruebas | Notas de pruebas Sprint 5-8 |
| Estado | 🟡 Parcialmente integrado |
Tareas de Asana Creadas:
- Nueva orden → Crear tarea en proyecto “Órdenes”
- Proveedor seleccionado → Actualizar tarea con nombre del proveedor
- Cotización enviada → Crear subtarea para aprobación
- Trabajo completado → Marcar tarea como completada
Criterios de Aceptación:
- Tareas creadas automáticamente en eventos de orden
- Sincronización bidireccional (cambios en Asana reflejados en Algesta)
- Campos personalizados para ID de orden, prioridad, estado
- Asignados basados en agentes de Algesta
Estado: Integración básica existe, sincronización bidireccional pendiente (P1 en Q1 2026).
FR-07.04: Integración con DocuSign (Futuro)
| Req ID | FR-07.04 |
|---|---|
| Descripción | El sistema envía contratos y pólizas a DocuSign para firma electrónica |
| Prioridad | P1 (Alta) |
| Sprint | S5 (diseñado), S8 (Implementación pendiente) |
| Historias de Usuario | Firma electrónica (S5) |
| Implementación | Diseñado, no implementado |
| Evidencia de Pruebas | Notas de pruebas Sprint 5 (validación de diseño) |
| Estado | 🔴 Diseñado, no implementado (P1 en Q1 2026) |
Flujos de Trabajo de Firma:
- Contrato de Proveedor - Nuevo proveedor firma acuerdo de servicio
- Contrato de Cliente - Cliente firma contrato de orden antes de ejecución
- Pólizas - Cliente firma pólizas de mantenimiento
Flujo Planificado:
- Agente activa solicitud de firma
- Sistema genera PDF desde plantilla
- Sistema envía a API de DocuSign con destinatarios
- Destinatarios reciben email con enlace de firma
- Webhook de DocuSign notifica a Algesta de completitud
- Sistema actualiza estado de orden/proveedor
Criterios de Aceptación (cuando se implemente):
- Múltiples firmantes soportados (secuencial o paralelo)
- Estado de firma rastreado (ENVIADO, FIRMADO, RECHAZADO)
- PDF firmado almacenado en Azure Blob Storage
- Emails de recordatorio si no se firma en 48 horas
Estado: Diseño aprobado en S5, implementación pendiente en Q1 2026 (P1).
FR-07.05: Integración con Qsystems (Futuro)
| Req ID | FR-07.05 |
|---|---|
| Descripción | El sistema se integra con la plataforma de gestión de clientes empresariales Qsystems para sincronización de datos |
| Prioridad | P2 (Media) |
| Sprint | Futuro (post-MVP) |
| Historias de Usuario | Integración Qsystems (futuro) |
| Implementación | No implementado |
| Evidencia de Pruebas | N/A |
| Estado | 🔴 Mejora futura (Q2 2026) |
Integración Planificada:
- Sincronizar datos de clientes empresariales (empresa, ubicaciones, activos)
- Sincronizar órdenes de Qsystems a Algesta
- Enviar actualizaciones de estado de órdenes de vuelta a Qsystems
Estado: Planificado para clientes empresariales en Q2 2026.
FR-07.06: Integración con Sistema de Activos Heredado (Futuro)
| Req ID | FR-07.06 |
|---|---|
| Descripción | El sistema consulta el sistema de activos heredado para datos históricos |
| Prioridad | P2 (Media) |
| Sprint | S8 (investigación parcial) |
| Historias de Usuario | Acceso a sistema anterior (S8), Historia 17988 |
| Implementación | Conexión API de solo lectura diseñada |
| Evidencia de Pruebas | Notas de pruebas Sprint 8 |
| Estado | 🔴 Integración mínima (P2 en Q2 2026) |
Integración Planificada:
- Acceso de solo lectura vía API o consulta directa a BD
- Consultar historial de activos del sistema heredado
- Mostrar en vista de HV de Algesta
- Caché para rendimiento (<3 segundos de tiempo de carga)
Desafíos:
- Sistema heredado tiene 500+ campos (muy complejo)
- Decisión: Algesta usa HV liviano, consulta al sistema heredado solo bajo demanda
Estado: Conexión básica establecida, integración completa pendiente (P2).
Matriz de Trazabilidad
Esta matriz mapea requisitos funcionales a historias de usuario, Sprints, implementación y evidencia de pruebas.
| Req ID | Requisito | Sprint | Historias de Usuario | Archivos de Implementación | Evidencia de Pruebas | Estado |
|---|---|---|---|---|---|---|
| FR-01: Gestión de Órdenes | ||||||
| FR-01.01 | Captura de Orden por WhatsApp | S2 | Integración WhatsApp | create-order/, skills de Jelou | Pruebas Sprint 2 | ✅ |
| FR-01.02 | Máquina de Estados de Orden | S2-S8 | Estados de órdenes | order.entity.ts | Todos los Sprints | ✅ |
| FR-01.03 | Gestión de Detalles de Orden | S2-S8 | Gestión de órdenes, Edición | update-order/ | Historia 16502 | ✅ |
| FR-01.04 | Búsqueda y Filtrado de Órdenes | S2-S8 | Gestión de solicitudes | get-all-orders/ | Historia 16502 | ✅ |
| FR-01.05 | Asignación de Orden | S2-S4 | Asignación, Publicación marketplace | assign-technician/, publish-to-marketplace/ | Pruebas Sprint 4 | ✅ |
| FR-01.06 | Notificaciones de Orden | S2-S8 | Notificaciones | event-handlers/ | Todos los Sprints | 🟡 |
| FR-01.07 | Historial de Orden y Auditoría | S2-S8 | Historial transaccional | order-history.entity.ts | Sprint 7-8 | ✅ |
| FR-01.08 | Urgencia y Prioridad | S1-S4 | Manejo de urgencia | Campo urgency en entidad Order | Pruebas Sprint 4 | ✅ |
| FR-01.09 | Programación de Visita Técnica | S6-S8 | Visita técnica | schedule-visit/, entidad Visit | Sprint 6-8 | ✅ |
| FR-01.10 | Confirmación de Ejecución | S6-S8 | Confirmar fecha ejecución | confirm-execution-date/ | Pruebas Sprint 8 | 🟡 |
| FR-02: Marketplace y Subastas | ||||||
| FR-02.01 | Publicación de Subasta | S4 | Historia 16544 | publish-auction/, entidad Auction | Historia 16544 | ✅ |
| FR-02.02 | Ofertas Anónimas | S4 | Ofertas anónimas | submit-offer/, entidad Offer | Pruebas Sprint 4 | ✅ |
| FR-02.03 | Selección de Proveedor | S4 | Selección de ganador | select-winner/ | Pruebas Sprint 4 | ✅ |
| FR-02.04 | Cierre de Subasta | S4 | Cierre de subasta | close-expired-auctions.task.ts | Pruebas Sprint 4 | ✅ |
| FR-02.05 | Visibilidad y Filtros del Marketplace | S4-S8 | Vista pública, Marketplace UX | Consultas Provider MS, Componente Marketplace | Sprint 4-8 | 🟡 |
| FR-03: Gestión de Proveedores | ||||||
| FR-03.01 | Registro de Proveedor | S3 | Registro de proveedor | create-provider/, entidad Provider | Pruebas Sprint 3 | ✅ |
| FR-03.02 | Carga y Validación de Documentos | S3 | Carga de Documentos | upload-documento/, entidad Documento | Pruebas Sprint 3 | ✅ |
| FR-03.03 | Gestión de Vencimiento de Documentos | S3-S7 | Vencimientos | check-documento-expiry.task.ts | Pruebas Sprint 7 | ✅ |
| FR-03.04 | Elegibilidad de Proveedor | S3-S4 | Validación de elegibles | get-eligible-providers/ | Pruebas Sprint 4 | ✅ |
| FR-03.05 | Seguimiento de Rendimiento de Proveedor | S7-S8 | Tracking de performance | provider-performance.entity.ts | Sprint 7-8 | 🟡 |
| FR-03.06 | Listado y Búsqueda de Proveedores | S7-S8 | Listado de proveedores | get-all-providers/ | Pruebas Sprint 8 | ✅ |
| FR-04: Gestión de Activos | ||||||
| FR-04.01 | Creación de Activo | S6-S8 | Gestión automatizada HV, Crear activo | create-asset/, servicio OCR | Historia 16016 | 🟡 |
| FR-04.02 | Historial de Activo (HV) | S6-S8 | Historial consolidado HV | asset-history.entity.ts | Historia 16016, 17988 | 🟡 |
| FR-04.03 | Búsqueda y Consulta de Activo | S7-S8 | Consulta HV, Acceso HV | get-asset-by-serial/ | Historia 17988 | ✅ |
| FR-04.04 | Gestión de Estado de Activo | S7-S8 | Estado transaccional activo | Estado en entidad Asset | Sprint 7-8 | ✅ |
| FR-04.05 | Exportación PDF de Activo | S7-S8 | Exportación PDF HV | export-asset-pdf/ | Pruebas Sprint 8 | 🔴 |
| FR-05: Cotizaciones y Aprobaciones | ||||||
| FR-05.01 | Desglose de Cotización (Agente) | S6-S8 | Cotización por ítems, Informe cotización | create-quotation-template/ | Sprint 6-8 | ✅ |
| FR-05.02 | Precio de Cotización (Proveedor) | S6-S8 | Cotización por ítems | submit-quotation/ | Sprint 6-8 | ✅ |
| FR-05.03 | Inflación de Cotización (Agente) | S7-S8 | Inflar valores cotización | inflate-quotation/ | Pruebas Sprint 8 | 🟡 |
| FR-05.04 | Aprobación de Cotización (Cliente) | S5-S8 | Aprobación de cliente | approve-quotation/ | Sprint 5-8 | ✅ |
| FR-05.05 | Aprobaciones Multinivel | S6-S8 | Aprobador 1, 2 | Entidad de cadena de aprobación | Pruebas Sprint 8 | 🟡 |
| FR-06: Reportes y KPIs | ||||||
| FR-06.01 | Dashboard de KPIs | S7-S8 | KPIs operativos, Dashboard KPIs | get-kpis/, servicio KPI | Sprint 7-8 | ✅ |
| FR-06.02 | Reportes de Órdenes | S5-S8 | Informes, Informe cotización, ejecución | generate-report/ | Sprint 6-8 | ✅ |
| FR-06.03 | Seguimiento de SLA y Alertas | S7-S8 | Seguimiento de SLA | Servicio SLA, Tarea programada | Sprint 7-8 | ✅ |
| FR-06.04 | Reportes de Rendimiento (Proveedor) | S7-S8 | Reportes avanzados KPIs | Reportes de rendimiento de proveedores | Pruebas Sprint 8 | 🟡 |
| FR-07: Integraciones Externas | ||||||
| FR-07.01 | Integración de Email SendGrid | S2-S8 | Notificaciones correo | sendgrid.service.ts | Todos los Sprints | ✅ |
| FR-07.02 | Integración de WhatsApp Jelou | S2-S8 | Integración WhatsApp, 7 skills | Skills de Jelou, Endpoints de API | Sprint 2-8 | ✅ |
| FR-07.03 | Integración con Asana | S5-S8 | Integración Asana | asana.service.ts | Sprint 5-8 | 🟡 |
| FR-07.04 | Integración con DocuSign | S5, S8 | Firma electrónica | Diseñado, no implementado | Diseño Sprint 5 | 🔴 |
| FR-07.05 | Integración con Qsystems | Futuro | Integración Qsystems | No implementado | N/A | 🔴 |
| FR-07.06 | Sistema de Activos Heredado | S8 | Acceso sistema anterior | API de solo lectura | Historia 17988 | 🔴 |
Leyenda de Estado:
- ✅ Completo: Completamente implementado y verificado
- 🟡 En Progreso: Parcialmente implementado o tiene bugs conocidos
- 🔴 Pendiente: Diseñado o planificado, aún no implementado
Resumen de Verificación
Métricas de Completitud
| Categoría | Total Reqs | Completo (✅) | En Progreso (🟡) | Pendiente (🔴) | % Completo |
|---|---|---|---|---|---|
| FR-01: Gestión de Órdenes | 10 | 7 | 3 | 0 | 70% |
| FR-02: Marketplace y Subastas | 5 | 4 | 1 | 0 | 80% |
| FR-03: Gestión de Proveedores | 6 | 5 | 1 | 0 | 83% |
| FR-04: Gestión de Activos | 5 | 2 | 2 | 1 | 40% |
| FR-05: Cotizaciones y Aprobaciones | 5 | 3 | 2 | 0 | 60% |
| FR-06: Reportes y KPIs | 4 | 3 | 1 | 0 | 75% |
| FR-07: Integraciones Externas | 6 | 1 | 3 | 2 | 17% |
| TOTAL | 41 | 25 | 13 | 3 | 61% |
Desglose por Prioridad
| Prioridad | Total Reqs | Completo | En Progreso | Pendiente | % Completo |
|---|---|---|---|---|---|
| P0 (Crítica) | 18 | 11 | 6 | 1 | 61% |
| P1 (Alta) | 18 | 12 | 5 | 1 | 67% |
| P2 (Media) | 5 | 2 | 2 | 1 | 40% |
Cobertura por Sprint
| Sprint | Requisitos Entregados | Total Acumulado |
|---|---|---|
| S1 | 1 (Diseño UX) | 1 |
| S2 | 5 (WhatsApp, Gestión de Órdenes, Notificaciones) | 6 |
| S3 | 4 (Gestión de Proveedores, Documentos) | 10 |
| S4 | 5 (Marketplace, Subastas) | 15 |
| S5 | 3 (Reportes, Aprobaciones) | 18 |
| S6 | 6 (Cotizaciones, Visitas, Activos) | 24 |
| S7 | 8 (Activos, KPIs, Rendimiento) | 32 |
| S8 | 9 (Finalización, Integraciones) | 41 |
Cobertura de Pruebas
| Tipo de Prueba | Cobertura | Evidencia |
|---|---|---|
| Pruebas de Aceptación | ✅ Comprensiva | Notas de pruebas Sprint 2-8, todas las historias de usuario |
| Pruebas de Humo | ✅ Completo | Notas de pruebas para S2-S8 |
| Pruebas E2E | 🟡 Parcial | Flujos clave probados (creación de orden, marketplace, cotizaciones) |
| Pruebas de Integración | 🟡 Parcial | Pruebas de integración de API, integración de sistemas externos |
| Pruebas Unitarias | 🟡 Parcial | Jest (backend), Vitest (frontend) |
| Pruebas de Rendimiento | 🔴 Pendiente | Pruebas de carga aún no realizadas |
Referencias Cruzadas
Documentación Relacionada
Requisitos:
- Requisitos de Negocio - Contexto de negocio, objetivos, decisiones estratégicas
- Requisitos No Funcionales - Requisitos de rendimiento, seguridad, escalabilidad
Arquitectura:
- Descripción General de Microservicios Backend - Arquitectura de implementación
- Descripción General de Arquitectura C4 - Diagramas de diseño del sistema
Funcionalidades:
- Descripción General de Funcionalidades - Resumen de áreas de funcionalidades
- Gestión de Órdenes - Detalles del ciclo de vida de órdenes
- Subastas de Marketplace - Detalles de marketplace y subastas
- Gestión de Proveedores - Detalles de gestión de proveedores
- Gestión de Activos - Detalles de HV de activos
- Flujos de Trabajo de Cotización - Detalles de cotización y aprobación
- Reportes y KPIs - Detalles de KPI y reportes
- Integraciones Externas - Detalles de integración
- Matriz de Trazabilidad - Matriz completa Requisitos ↔ Pruebas
Pruebas:
- Guía de Pruebas - Estrategia y ejecución de pruebas
- Notas de Pruebas:
/test/unified_testing_notes.md(fuera de la wiki)
Externo:
- Documentación de Sprints:
/docs/Sprint_[1-8].md - Análisis Completo del Backlog:
/docs/complete_backlog_analysis.md - Contexto:
/docs/context.md
Última Actualización: 2025-11-20 Próxima Revisión: Después de completar fase de garantía (Q1 2026) Propietario del Documento: Product Owner + Tech Lead