Gestión de Órdenes

1. Descripción General de la Funcionalidad

El sistema de gestión de órdenes es el núcleo de la plataforma Algesta, manejando el ciclo de vida completo desde la solicitud inicial del cliente vía WhatsApp hasta la asignación de marketplace, ejecución, aprobación y cierre. Soporta múltiples tipos de órdenes (correctivo, preventivo, adaptación), prioridades (emergencia, prioridad) y actores (cliente, agente, proveedor). El sistema mantiene historial transaccional para auditabilidad e integra con sistemas externos para notificaciones, firmas y pagos. Todas las transiciones de estado son rastreadas, marcadas con timestamp y atribuidas a usuarios específicos, habilitando seguimiento completo de SLA, reportes de cumplimiento y analítica operacional.

2. Contexto de Negocio

Algesta necesitaba reemplazar el manejo manual y fragmentado de solicitudes de mantenimiento con un sistema automatizado y rastreable que pudiera escalar para manejar múltiples clientes, proveedores y tipos de activos mientras mantiene un estricto cumplimiento y seguimiento de SLA. El proceso anterior involucraba llamadas telefónicas, correos electrónicos y hojas de cálculo, lo que resultaba en solicitudes perdidas, responsabilidad poco clara y sin visibilidad del rendimiento. El sistema de gestión de órdenes centraliza todas las actividades de mantenimiento, aplica flujos de trabajo estandarizados y proporciona visibilidad en tiempo real para todos los interesados.

3. Estados de Órdenes y Ciclo de Vida

Diagrama de Máquina de Estados

stateDiagram-v2
    [*] --> Creada: Client submits via WhatsApp
    Creada --> EnRevision: Agent reviews
    EnRevision --> PublicadaParaOfertas: Published to marketplace
    EnRevision --> Cancelada: Order cancelled
    PublicadaParaOfertas --> RecibiendoOfertas: Providers bid
    RecibiendoOfertas --> ProveedorSeleccionado: Agent selects winner
    ProveedorSeleccionado --> CotizacionEnviada: Provider sends quote
    CotizacionEnviada --> CotizacionAprobada: Client approves
    CotizacionEnviada --> CotizacionRechazada: Client rejects
    CotizacionRechazada --> CotizacionEnviada: Provider revises
    CotizacionAprobada --> DocumentosEnFirma: Contracts to DocuSign
    DocumentosEnFirma --> PolizaAsignada: Policy assigned
    PolizaAsignada --> AnticipoRegistrado: Advance payment
    AnticipoRegistrado --> VisitaTecnica: Technical visit scheduled
    VisitaTecnica --> TrabajoIniciado: Provider starts work
    TrabajoIniciado --> InformeEjecucion: Provider submits report
    InformeEjecucion --> RevisionAgente: Agent reviews
    RevisionAgente --> AprobacionCliente: Sent to client
    AprobacionCliente --> TrabajoAprobado: Client approves
    AprobacionCliente --> Retrabajo: Client requests changes
    Retrabajo --> InformeEjecucion: Provider resubmits
    TrabajoAprobado --> PagoFinal: Final payment
    PagoFinal --> Cerrada: Order closed
    Cerrada --> [*]

    Cancelada --> [*]

Descripciones de Estados

Estado	Descripción	Actor	Estados Siguientes	Sprint Introducido
Creada	Orden inicial desde WhatsApp	Cliente	EnRevision	S2
EnRevision	Agente valida y enriquece	Agente	PublicadaParaOfertas, Cancelada	S2
PublicadaParaOfertas	Publicada en marketplace	Agente	RecibiendoOfertas	S4
RecibiendoOfertas	Proveedores enviando ofertas	Proveedor	ProveedorSeleccionado	S4
ProveedorSeleccionado	Proveedor ganador seleccionado	Agente	CotizacionEnviada	S4
CotizacionEnviada	Proveedor envió cotización	Proveedor	CotizacionAprobada, CotizacionRechazada	S5
CotizacionAprobada	Cliente aprobó cotización	Cliente	DocumentoosEnFirma	S5
CotizacionRechazada	Cliente rechazó cotización	Cliente	CotizacionEnviada	S5
DocumentoosEnFirma	Contratos enviados a DocuSign	Agente	PolizaAsignada	S5
PolizaAsignada	Póliza de seguro asignada	Agente	AnticipoRegistrado	S5
AnticipoRegistrado	Pago de anticipo registrado	Agente	VisitaTecnica	S5
VisitaTecnica	Visita técnica programada	Proveedor	TrabajoIniciado	S6
TrabajoIniciado	Ejecución de trabajo iniciada	Proveedor	InformeEjecucion	S6
InformeEjecucion	Informe de ejecución enviado	Proveedor	RevisionAgente	S6
RevisionAgente	Agente revisando informe	Agente	AprobacionCliente	S7
AprobacionCliente	Cliente revisando trabajo	Cliente	TrabajoAprobado, Retrabajo	S7
TrabajoAprobado	Cliente aprobó trabajo	Cliente	PagoFinal	S7
Retrabajo	Retrabajo solicitado	Cliente	InformeEjecucion	S7
PagoFinal	Pago final procesado	Agente	Cerrada	S8
Cerrada	Orden cerrada	Agente	[*]	S8
Cancelada	Orden cancelada	Agente	[*]	S2

4. Historias de Usuario por Sprint

Sprint 1: Diseño UX

US-S1-001: Panel de Control de Agente para Órdenes

Descripción: Como agente, quiero ver un panel de control de todas las órdenes para poder gestionarlas eficientemente
Criterios de Aceptación:
- Wireframes y prototipos entregados en Figma
- Panel de control muestra lista de órdenes con información clave (número, cliente, estado, Prioridad, fecha)
- Funcionalidad de filtros y ordenamiento diseñada
- Vista de detalle diseñada con toda la información de la orden
Estado: ✅ Completo
Evidencia: Sprint 1 acta de cierre, Figma prototypes

US-S1-002: Flujo de Interacción de Cliente en WhatsApp

Descripción: Como cliente, quiero iniciar una solicitud de servicio vía WhatsApp para no tener que aprender un nuevo sistema
Criterios de Aceptación:
- Flujo UX para conversación de WhatsApp diseñado
- Plantillas de mensajes definidas
- Flujos de manejo de errores diseñados
Estado: ✅ Completo
Evidencia: Sprint 1 acta de cierre, Figma prototypes

Sprint 2: Integración WhatsApp

US-S2-001: Creación de Orden desde WhatsApp

Descripción: Como cliente, quiero enviar un mensaje a WhatsApp y que cree una orden automáticamente
Criterios de Aceptación:
- WhatsApp Business API conectado
- Mensajes recibidos en backend
- Órdenes creadas con datos del mensaje original
- Confirmación automática enviada al cliente
- Orden visible en el panel de control
Estado: ✅ Completo
Implementación:
- algesta-agent/jelou/bot.json - Configuración del bot
- algesta-agent/jelou/skills/skill_*.json - Definiciones de habilidades
- algesta-ms-orders-nestjs/src/application/handlers/commands/create-order.handler.ts - Comando de creación de orden
- algesta-ms-orders-nestjs/src/application/handlers/commands/create-order-from-gateway.handler.ts - Integración con gateway
Evidencia de Pruebas: Sprint 2 Pruebas notes - Integración WhatsApp validada
API Endpoints:
- POST /api/orders/create - Crear orden desde WhatsApp
- POST /api/orders/from-gateway - Crear orden desde panel de control

US-S2-002: Notificación de Orden al Cliente

Descripción: Como cliente, quiero recibir una notificación de WhatsApp cuando mi orden sea creada para saber que fue recibida
Criterios de Aceptación:
- Notificación enviada inmediatamente después de la creación de la orden
- Incluye número de orden para seguimiento
- Incluye tiempo estimado de respuesta
Estado: ✅ Completo
Implementación:
- algesta-ms-notifications-nestjs/src/application/handlers/send-whatsapp-notification.handler.ts
Evidencia de Pruebas: Sprint 2 Pruebas notes

Sprint 3: Visualización y Gestión de Órdenes

US-S3-001: Ver Órdenes con Filtros

Descripción: Como agente, quiero ver todas las órdenes entrantes con filtros por fecha, estado y Prioridad
Criterios de Aceptación:
- Panel de control muestra lista de órdenes con filtros
- Filtros: rango de fechas, estado, Prioridad, tipo de servicio, agente asignado
- Ordenar por: fecha de creación, Prioridad, estado
- Paginación para conjuntos de datos grandes
- Actualizaciones en tiempo real cuando llegan nuevas órdenes
Estado: ✅ Completo
Implementación:
- algesta-dashboard-react/src/Funcionalidades/orders/ - Módulo de funcionalidad de órdenes
- algesta-ms-orders-nestjs/src/application/handlers/queries/orders/get-all-orders.handler.ts - Consulta de lista de órdenes
Evidencia de Pruebas: Sprint 3 Pruebas - Visualización de órdenes validada
API Endpoints:
- GET /api/orders?state=X&Prioridad=Y&from=DATE&to=DATE - Listar órdenes con filtros

US-S3-002: Ver Detalles de Orden

Descripción: Como agente, quiero ver los detalles de la orden incluyendo información del cliente, información del activo, fotos y Prioridad
Criterios de Aceptación:
- Vista de detalle muestra toda la información de la orden
- Fotos mostradas en galería
- Información del cliente visible
- Información del activo visible (si está asociado)
- Línea de tiempo del historial de la orden visible
- Botones de acción basados en el estado actual
Estado: ✅ Completo
Implementación:
- algesta-dashboard-react/src/Funcionalidades/orders/Componentes/OrderDetail.tsx
- algesta-ms-orders-nestjs/src/application/handlers/queries/orders/get-order-by-id.handler.ts
API Endpoints:
- GET /api/orders/:id - Obtener detalles de orden

US-S3-003: Asignar Orden a Agente

Descripción: Como agente, quiero asignar órdenes a mí mismo o a otros agentes
Criterios de Aceptación:
- Menú desplegable de asignación con lista de agentes
- Agente asignado visible en lista y detalle de orden
- Notificación enviada al agente asignado
- Asignación rastreada en historial de orden
Estado: ✅ Completo
Implementación:
- algesta-ms-orders-nestjs/src/application/handlers/commands/assign-technician-to-order.handler.ts
API Endpoints:
- POST /api/orders/:id/assign - Asignar orden a agente

Sprint 4: Publicación en Marketplace

US-S4-001: Publicar Orden en Marketplace

Descripción: Como agente, quiero publicar una orden en el marketplace para que los proveedores puedan ofertar
Criterios de Aceptación:
- Botón “Publicar en Marketplace” visible para órdenes elegibles
- Formulario para configurar duración de subasta (horas/días)
- Opción para agregar preguntas personalizadas para proveedores
- Validación de datos requeridos de la orden (ubicación, tipo de servicio, fotos)
- Validación de que existe al menos un proveedor elegible
- Estado cambia a “PublicadaParaOfertas”
- Proveedores elegibles reciben notificación
Estado: ✅ Completo
Implementación:
- algesta-ms-provider-nestjs/src/application/handlers/commands/auction/publish-order-for-auction.handler.ts
- algesta-dashboard-react/src/Funcionalidades/marketplace/
Evidencia de Pruebas: Sprint 4 Pruebas notes - Historia 16544
API Endpoints:
- POST /api/auctions/publish - Publicar orden en marketplace

US-S4-002: Rastrear Estado del Marketplace

Descripción: Como agente, quiero rastrear el estado de órdenes en el marketplace
Criterios de Aceptación:
- Panel de control muestra órdenes en subasta
- Muestra número de ofertas recibidas
- Muestra tiempo restante en subasta
- Muestra si se alcanzó el mínimo de ofertas (3)
- Alerta si la subasta cierra pronto con ofertas insuficientes
Estado: ✅ Completo
Implementación:
- algesta-dashboard-react/src/Funcionalidades/marketplace/Componentes/AuctionEstado.tsx
- algesta-ms-provider-nestjs/src/application/handlers/queries/auction/get-auction-Estado.handler.ts
API Endpoints:
- GET /api/auctions/:id/Estado - Obtener estado de subasta

Sprint 5: Flujos Post-Subasta

US-S5-001: Ver Ofertas de Proveedores

Descripción: Como agente, quiero ver todas las ofertas de una orden para poder seleccionar el mejor proveedor
Criterios de Aceptación:
- Ofertas solo visibles si ≥3 ofertas enviadas
- Tabla con: Proveedor, Costo, Duración, Calificación, Estado de Documentos
- Ordenable por costo, calificación, duración
- Fila expandible para ver historial del proveedor
- Botón para seleccionar proveedor
Estado: ✅ Completo
Implementación:
- algesta-ms-provider-nestjs/src/application/handlers/queries/auction/list-auction-offers.handler.ts
- algesta-dashboard-react/src/Funcionalidades/marketplace/auction/
API Endpoints:
- GET /api/auctions/:id/offers - Listar ofertas

US-S5-002: Seleccionar Proveedor

Descripción: Como agente, quiero seleccionar el proveedor ganador para que la orden pueda proceder
Criterios de Aceptación:
- Diálogo de confirmación mostrando detalles del proveedor
- Estado de orden cambia a “ProveedorSeleccionado”
- Proveedor seleccionado recibe notificación
- Proveedores no seleccionados reciben notificación
- Subasta es cerrada
Estado: ✅ Completo
Implementación:
- algesta-ms-provider-nestjs/src/application/handlers/commands/auction/assign-provider.handler.ts
API Endpoints:
- POST /api/auctions/:auctionId/assign - Seleccionar proveedor y asignar a subasta
Nota: La selección de proveedor se maneja vía el API de marketplace/subastas, no vía una ruta del controlador de órdenes. Ver marketplace-auctions.md para documentación completa del API de subastas y selección de proveedor.

US-S5-003: Enviar Documentos a Firma Electrónica

Descripción: Como agente, quiero enviar contratos para firma electrónica después de la aprobación de cotización
Criterios de Aceptación:
- Botón “Enviar a Firma” visible después de aprobación de cotización
- Documentos enviados a DocuSign
- Todas las partes (cliente, proveedor, Algesta) reciben solicitud de firma
- Estado cambia a “DocumentoosEnFirma”
- Estado de firma rastreado
Estado: ✅ Completo
Implementación:
- algesta-ms-orders-nestjs/src/application/handlers/commands/send-to-signature.handler.ts
Evidencia de Pruebas: Sprint 5 Pruebas notes
API Endpoints:
- POST /api/orders/:id/send-to-signature - Enviar documentos a DocuSign

Sprint 6: Visita Técnica y Ejecución

US-S6-001: Programar Visita Técnica

Descripción: Como proveedor, quiero programar una visita técnica antes de iniciar el trabajo
Criterios de Aceptación:
- Proveedor puede seleccionar fecha y hora para la visita
- Cliente recibe notificación con detalles de la visita
- Detalles de la visita visibles en línea de tiempo de la orden
- Estado cambia a “VisitaTecnica”
Estado: ✅ Completo
Implementación:
- algesta-api-gateway-nestjs/src/infrastructure/controllers/technical-visit.controller.ts - TechnicalVisitController
- algesta-ms-provider-nestjs/src/application/handlers/commands/schedule-technical-visit.handler.ts - TechnicalVisitService
API Endpoints:
- POST /api/technical-visit/provider-technical-visit - Programar visita técnica (soporta flujo de dos fases: selección de proveedor y programación de visita)

US-S6-002: Enviar Informe de Ejecución

Descripción: Como proveedor, quiero enviar un informe de ejecución con fotos y detalles
Criterios de Aceptación:
- Formulario con: trabajo realizado, materiales usados, fotos, fecha de finalización
- Fotos subidas a Azure Blob
- Informe enviado y visible para el agente
- Estado cambia a “InformeEjecucion”
- Agente recibe notificación
Estado: ✅ Completo
Implementación:
- algesta-ms-orders-nestjs/src/application/handlers/commands/submit-execution-report.handler.ts
API Endpoints:
- POST /api/orders/:id/execution-report - Enviar informe de ejecución

Sprint 7: Aprobación y Cierre

US-S7-001: Agente Revisa Informe de Ejecución

Descripción: Como agente, quiero revisar el informe de ejecución del proveedor antes de enviarlo al cliente
Criterios de Aceptación:
- Ver informe de ejecución con todos los detalles
- Ver fotos de antes/después
- Aprobar o solicitar cambios
- Si se aprueba, estado cambia a “AprobacionCliente”
- Cliente recibe notificación
Estado: ✅ Completo
Implementación:
- algesta-ms-orders-nestjs/src/application/handlers/commands/review-execution-report.handler.ts
API Endpoints:
- POST /api/orders/:id/review-report - Revisar informe de ejecución

US-S7-002: Cliente Aprueba Trabajo

Descripción: Como cliente, quiero aprobar el trabajo completado o solicitar cambios
Criterios de Aceptación:
- Cliente recibe enlace para revisar trabajo
- Puede ver fotos e informe
- Aprobar o rechazar con comentarios
- Si se aprueba, estado cambia a “TrabajoAprobado”
- Si se rechaza, estado cambia a “Retrabajo”
- Todas las partes notificadas de la decisión
Estado: ✅ Completo
Implementación:
- algesta-ms-orders-nestjs/src/application/handlers/commands/approve-work.handler.ts
- algesta-ms-orders-nestjs/src/application/handlers/commands/request-rework.handler.ts
API Endpoints:
- POST /api/orders/:id/approve-work - Aprobar trabajo
- POST /api/orders/:id/request-changes - Solicitar retrabajo

Sprint 8: Finalización

US-S8-001: Cerrar Orden

Descripción: Como agente, quiero cerrar una orden después de que el pago final sea procesado
Criterios de Aceptación:
- Pago final registrado
- Estado cambia a “Cerrada”
- Todas las partes notificadas
- Orden visible en lista de órdenes cerradas
- Métricas de rendimiento actualizadas
Estado: ✅ Completo
Implementación:
- algesta-ms-orders-nestjs/src/application/handlers/commands/close-order.handler.ts
API Endpoints:
- POST /api/orders/:id/close - Cerrar orden

5. Modelo de Datos de Orden

Entidad Order

Referencia: algesta-ms-orders-nestjs/src/domain/entities/order.entity.ts

Campo	Tipo	Descripción	Requerido	Origen
`_id`	ObjectId	Identificador único	Sí	Auto-generado
`orderNumber`	String	ID legible (ej., ORD-2025-001)	Sí	`order-id-generator.service.ts`
`clientId`	ObjectId	Referencia al cliente	Sí	Desde WhatsApp o dashboard
`assetId`	ObjectId	Referencia al activo	No	Desde HV o creado
`serviceType`	Enum	CORRECTIVE, PREVENTIVE, ADAPTATION	Sí	Desde cliente
`Prioridad`	Enum	EMERGENCY, Prioridad, NORMAL	Sí	Desde cliente o agente
`state`	Enum	Ver máquina de estados arriba	Sí	Transiciones de estado
`Descripción`	String	Descripción del servicio	Sí	Desde cliente
`photos`	Array	URLs de Azure Blob	No	Desde WhatsApp
`location`	Object	Dirección, coordenadas, ciudad, región	Sí	Desde cliente
`createdAt`	Date	Marca de tiempo de creación	Sí	Auto
`updatedAt`	Date	Última actualización	Sí	Auto
`assignedAgentId`	ObjectId	Agente asignado	No	Desde asignación
`assignedProviderId`	ObjectId	Proveedor seleccionado	No	Desde subasta
`auctionId`	ObjectId	Subasta relacionada	No	Desde marketplace
`quotationId`	ObjectId	Cotización aprobada	No	Desde proveedor
`executionReportId`	ObjectId	Informe de ejecución	No	Desde proveedor
`approvalDate`	Date	Fecha de aprobación del cliente	No	Desde aprobación
`closureDate`	Date	Fecha de cierre de orden	No	Desde cierre
`cancellationReason`	String	Razón si fue cancelada	No	Desde cancelación

6. Historial de Órdenes y Auditoría

Sistema de Historial Transaccional

Cada cambio de estado crea un registro OrderHistory para trazabilidad completa de auditoría y seguimiento de SLA.

Referencia: algesta-ms-orders-nestjs/src/domain/entities/order-history.entity.ts

Entidad OrderHistory

Campo	Tipo	Descripción
`_id`	ObjectId	Identificador único
`orderId`	ObjectId	Orden relacionada
`previousState`	Enum	Estado antes de la transición
`newState`	Enum	Estado después de la transición
`userId`	ObjectId	Usuario que hizo el cambio
`userRole`	Enum	AGENT, PROVIDER, CLIENT, SYSTEM
`timestamp`	Date	Cuándo ocurrió el cambio
`reason`	String	Razón del cambio
`metadata`	Object	Contexto adicional (ej., razón de rechazo, comentarios de aprobación)

Casos de Uso

Trazabilidad de Auditoría: Historial completo de quién hizo qué y cuándo
Cálculo de SLA: Tiempo entre estados específicos (ej., Creada → ProveedorSeleccionado)
Cumplimiento: Requerido para reportes regulatorios
Depuración: Solucionar problemas de órdenes revisando historial
Cálculo de KPI: Datos fuente para métricas operacionales

Referencia: algesta-ms-orders-nestjs/src/shared/services/order-history.service.ts

7. Resumen de Endpoints API

Endpoint	Método	Descripción	Actor	Sprint
`/api/orders/create`	POST	Crear orden desde WhatsApp	Sistema	S2
`/api/orders/from-gateway`	POST	Crear orden desde dashboard	Agente	S2
`/api/orders`	GET	Listar todas las órdenes con filtros	Agente	S3
`/api/orders/:id`	GET	Obtener detalles de orden	Agente/Proveedor/Cliente	S3
`/api/orders/:id/assign`	POST	Asignar orden a agente	Agente	S3
`/api/orders/:id/publish`	POST	Publicar en marketplace	Agente	S4
`/api/auctions/:auctionId/assign`	POST	Seleccionar proveedor y asignar a subasta	Agente	S4
`/api/orders/:id/quotation`	POST	Enviar cotización	Proveedor	S5
`/api/orders/:id/approve-quotation`	POST	Aprobar cotización	Cliente	S5
`/api/orders/:id/reject-quotation`	POST	Rechazar cotización	Cliente	S5
`/api/orders/:id/send-to-signature`	POST	Enviar documentos a DocuSign	Agente	S5
`/api/technical-visit/provider-technical-visit`	POST	Programar visita técnica	Proveedor	S6
`/api/orders/:id/start-work`	POST	Iniciar ejecución de trabajo	Proveedor	S6
`/api/orders/:id/execution-report`	POST	Enviar informe de ejecución	Proveedor	S6
`/api/orders/:id/review-report`	POST	Agente revisa informe	Agente	S7
`/api/orders/:id/approve-work`	POST	Aprobar trabajo completado	Cliente	S7
`/api/orders/:id/request-changes`	POST	Solicitar retrabajo	Cliente	S7
`/api/orders/:id/close`	POST	Cerrar orden	Agente	S8
`/api/orders/counter`	GET	Obtener conteo de órdenes por estado	Agente	S5
`/api/orders/history/:id`	GET	Obtener historial de orden	Agente	S5

Referencia: algesta-ms-orders-nestjs/src/infrastructure/controllers/order.controller.ts

8. Puntos de Integración

Integraciones Internas

WhatsApp (Jelou): Creación de órdenes, actualizaciones de estado, confirmación de fecha de ejecución
Servicio de Notificaciones: Notificaciones por email y WhatsApp para cambios de estado
Servicio de Proveedores: Participación en subastas, envío de cotizaciones
Servicio de Activos: Asociación de activos y actualizaciones de HV

Integraciones Externas

DocuSign: Firma de contratos después de aprobación de cotización
Azure Blob Storage: Almacenamiento de fotos y documentos
Servicio OCR: Reconocimiento de seriales desde fotos

9. Flujos de Trabajo Clave con Diagramas de Secuencia

Creación de Orden desde WhatsApp

sequenceDiagram
    participant Client
    participant Jelou
    participant Gateway
    participant OrdersMS
    participant NotificationsMS

    Client->>Jelou: Send message with service request
    Jelou->>Gateway: POST /api/orders/from-gateway
    Gateway->>OrdersMS: CreateOrderFromGatewayCommand
    OrdersMS->>OrdersMS: Validate data
    OrdersMS->>OrdersMS: Create Order entity (state: Creada)
    OrdersMS->>OrdersMS: Save to MongoDB
    OrdersMS->>OrdersMS: Create OrderHistory record
    OrdersMS->>NotificationsMS: Send confirmation notification
    NotificationsMS->>Jelou: Send WhatsApp message
    Jelou->>Client: "Your order ORD-2025-001 has been created"
    OrdersMS-->>Gateway: Order created response
    Gateway-->>Jelou: Success

Publicación de Orden en Marketplace

sequenceDiagram
    participant Agent
    participant Dashboard
    participant Gateway
    participant OrdersMS
    participant ProviderMS
    participant NotificationsMS

    Agent->>Dashboard: Click "Publish to Marketplace"
    Dashboard->>Gateway: POST /api/orders/:id/publish
    Gateway->>OrdersMS: Validate order state
    OrdersMS->>ProviderMS: Get eligible providers
    ProviderMS-->>OrdersMS: List of eligible providers
    alt No eligible providers
        OrdersMS-->>Dashboard: Error: No providers available
    else Providers available
        OrdersMS->>ProviderMS: Create auction
        ProviderMS->>ProviderMS: Save auction (state: ACTIVE)
        OrdersMS->>OrdersMS: Update order state to PublicadaParaOfertas
        OrdersMS->>OrdersMS: Create OrderHistory record
        OrdersMS->>NotificationsMS: Notify eligible providers
        NotificationsMS->>NotificationsMS: Send emails/WhatsApp
        OrdersMS-->>Dashboard: Success
    end

Selección de Proveedor y Aprobación de Cotización

sequenceDiagram
    participant Agent
    participant Dashboard
    participant Gateway
    participant OrdersMS
    participant ProviderMS
    participant NotificationsMS
    participant Client

    Agent->>Dashboard: Select provider from offers
    Dashboard->>Gateway: POST /api/auctions/:id/assign
    Gateway->>ProviderMS: AssignProviderCommand
    ProviderMS->>ProviderMS: Update auction status to CLOSED
    ProviderMS->>OrdersMS: Update order with selected provider
    OrdersMS->>OrdersMS: Update state to ProveedorSeleccionado
    OrdersMS->>OrdersMS: Create OrderHistory record
    ProviderMS->>NotificationsMS: Notify selected provider
    ProviderMS->>NotificationsMS: Notify non-selected providers
    NotificationsMS->>NotificationsMS: Send notifications

    Note over ProviderMS,Client: Provider submits quotation

    ProviderMS->>OrdersMS: Quotation submitted
    OrdersMS->>OrdersMS: Update state to CotizacionEnviada
    OrdersMS->>NotificationsMS: Notify client for approval
    NotificationsMS->>Client: "Please review quotation"

    Client->>Gateway: Approve quotation
    Gateway->>OrdersMS: ApproveQuotationCommand
    OrdersMS->>OrdersMS: Update state to CotizacionAprobada
    OrdersMS->>OrdersMS: Create OrderHistory record
    OrdersMS->>NotificationsMS: Notify agent and provider

Ejecución de Trabajo y Aprobación

sequenceDiagram
    participant Provider
    participant ProviderPortal
    participant Gateway
    participant OrdersMS
    participant Agent
    participant Client
    participant NotificationsMS

    Provider->>ProviderPortal: Submit execution report
    ProviderPortal->>Gateway: POST /api/orders/:id/execution-report
    Gateway->>OrdersMS: SubmitExecutionReportCommand
    OrdersMS->>OrdersMS: Save report
    OrdersMS->>OrdersMS: Update state to InformeEjecucion
    OrdersMS->>OrdersMS: Create OrderHistory record
    OrdersMS->>NotificationsMS: Notify agent
    NotificationsMS->>Agent: "New execution report"

    Agent->>Gateway: Review and approve report
    Gateway->>OrdersMS: ReviewExecutionReportCommand
    OrdersMS->>OrdersMS: Update state to AprobacionCliente
    OrdersMS->>OrdersMS: Create OrderHistory record
    OrdersMS->>NotificationsMS: Notify client
    NotificationsMS->>Client: "Please review completed work"

    Client->>Gateway: Approve work
    Gateway->>OrdersMS: ApproveWorkCommand
    OrdersMS->>OrdersMS: Update state to TrabajoAprobado
    OrdersMS->>OrdersMS: Create OrderHistory record
    OrdersMS->>NotificationsMS: Notify all parties

10. Evidencia de Pruebas y Validación

De unified_Pruebas_notes.md:

Sprint 2: Integración WhatsApp

Historia: Creación de Orden desde WhatsApp
Pre-requisitos: Bot Jelou configurado, gateway conectado, MongoDB disponible
Escenarios:
- Cliente envía mensaje → Orden creada → Confirmación enviada
- Datos inválidos → Mensaje de error → No se crea orden
- Adjunto de foto → Subida a Azure Blob → URL almacenada en orden
Resultados Esperados: Todos los escenarios validados ✅

Sprint 3: Visualización de Órdenes

Escenarios:
- Agente ve lista de órdenes → Todas las órdenes mostradas con estados correctos
- Agente filtra por estado → Solo órdenes en estado seleccionado mostradas
- Agente ve detalles de orden → Toda la información mostrada correctamente
- Agente asigna orden → Asignación rastreada en historial
Resultados Esperados: Todos los escenarios validados ✅

Sprint 4: Publicación en Marketplace

Historia 16544: Publicación en Marketplace
Pre-requisitos: Órdenes en estado “EnRevision”, proveedores elegibles, datos de orden válidos
Escenarios:
- Publicación con proveedores elegibles → Subasta creada → Proveedores notificados
- Publicación sin proveedores elegibles → Mensaje de error mostrado
- Publicación con datos insuficientes → Error de validación
- Seguimiento post-publicación → Subasta visible en marketplace
Resultados Esperados: Todos los escenarios validados ✅

Sprint 5-8: Flujos Post-Subasta

Firma Electrónica: Envío de documentos y seguimiento de estado validado
Aprobación de Cotización: Flujos de aprobación y rechazo probados
Informes de Ejecución: Envío y revisión de informe validados
Aprobación de Trabajo: Flujos de aprobación de cliente y retrabajo probados

Historia 16502: Gestión de Solicitudes

Escenarios:
- Agente crea orden desde dashboard → Orden creada exitosamente
- Agente ve lista de órdenes con filtros → Resultados correctos retornados
- Agente ve detalles de orden → Toda la información mostrada
- Agente realiza acciones basadas en estado → Transiciones de estado correctas
Resultados Esperados: Todos los escenarios validados ✅

11. Problemas Conocidos y Mejoras Futuras

De Completo_backlog_analysis.md:

🟧 Problemas Críticos

Flujos end-to-end de WhatsApp necesitan estabilización
Automatización de notificación de confirmación de fecha de ejecución pendiente
Casos extremos de validación de transición de estado

🟨 Mejoras Esenciales

Refinamiento de permisos basados en roles (solicitante, aprobador 1, aprobador 2)
Mejora del flujo de trabajo de cancelación de órdenes
Operaciones masivas de órdenes (asignar múltiples, cerrar múltiples)

🟩 Operaciones Post-MVP

Asignación automática basada en afinidad de agente, zona, especialidad
Plantillas de órdenes para tipos de servicio comunes
Búsqueda avanzada con capacidades de texto completo

🟦 Backlog Futuro

Automatización de mantenimiento preventivo (órdenes recurrentes)
Analítica y pronóstico de órdenes
Integración con sistema contable para facturación automatizada
Aplicación móvil para agentes de campo

12. Referencias Cruzadas

Documentación de Arquitectura

Flujos de Datos

Funcionalidades Relacionadas

Documentación de Sprints

Documentación de Sprint 2-8 (ver docs/Sprint_2.md hasta Sprint_8.md en el repositorio del proyecto)

Pruebas

Notas Unificadas de Pruebas (ver test/unified_Pruebas_notes.md en el repositorio del proyecto)

Última Actualización: 2025-11-20 | Próxima Revisión: Fin de Fase de Garantía