Saltearse al contenido
Documentación de la Plataforma Algesta

Flujo de Datos - Todos los Procesos de Negocio

1. Flujo de Incorporación de Proveedores

Proceso: Registro de Proveedor → Carga de Documento → Validación de Documento → Activación

sequenceDiagram
participant Provider as Proveedor
participant Dashboard as Dashboard React
participant APIGateway
participant ProviderMS as MS Proveedores
participant ProviderDB as BD Proveedores
participant BlobStorage as Azure Blob
participant NotificationsMS as MS Notificaciones

    Provider->>Dashboard: Completa formulario de registro
    Dashboard->>APIGateway: POST /api/provider/register
    APIGateway->>ProviderMS: CreateProviderCommand
    ProviderMS->>ProviderDB: Guarda proveedor (Estado: PENDING_DOCUMENTS)
    ProviderMS-->>Dashboard: Proveedor creado
    Dashboard-->>Provider: "Registro exitoso. Sube documentos requeridos"

    Provider->>Dashboard: Sube documento RUT (PDF)
    Dashboard->>APIGateway: POST /api/provider/Documentos
    APIGateway->>ProviderMS: UploadDocumentoCommand
    ProviderMS->>BlobStorage: Sube PDF a Azure
    BlobStorage-->>ProviderMS: URL del Blob
    ProviderMS->>ProviderDB: Guarda metadata del documento (Estado: PENDING)
    ProviderMS->>NotificationsMS: DocumentoUploadedEvent
    NotificationsMS->>NotificationsMS: Envía notificación al agente

    Note over Provider: Repetir para todos los documentos requeridos:<br/>RUT, Cámara de Comercio, ARL, Póliza, Certificado Bancario

    Note over Dashboard: Agente revisa documentos
    Dashboard->>APIGateway: PATCH /api/provider/Documentos/:id/approve
    APIGateway->>ProviderMS: UpdateDocumentoEstadoCommand
    ProviderMS->>ProviderDB: Actualiza documento (Estado: APPROVED)
    ProviderMS->>ProviderDB: Verifica si todos los docs aprobados → Actualiza proveedor (Estado: ACTIVE)
    ProviderMS->>NotificationsMS: ProviderActivatedEvent
    NotificationsMS->>Provider: "¡Proveedor activado! Puedes participar en subastas"

Figura: Secuencia de Incorporación de Proveedores - Flujo completo de registro de proveedor desde el registro hasta la activación, incluyendo carga y validación de documentos

Key Data Transformations:

  • Form data → CreateProviderDto → Provider Entity → MongoDB Documento
  • File upload → Azure Blob Storage → ProviderDocumento VO → MongoDB metadata

Required Documentos:

  • RUT (Tax Registration) - No expiry
  • Cámara de Comercio - Expires (renewed annually)
  • ARL (Occupational Risk) - Expires
  • Póliza de Responsabilidad Civil - Expires
  • Certificado Bancario - No expiry

2. Flujo de Subasta/Marketplace

Proceso: Publicar Orden → Notificar Proveedores → Enviar Ofertas → Seleccionar Ganador

sequenceDiagram
participant Agent as Agente
participant Dashboard
participant ProviderMS as MS Proveedores
participant ProviderDB as BD Proveedores
participant NotificationsMS as MS Notificaciones
participant Providers as Proveedores Elegibles
participant OrdersMS as MS Órdenes

    Agent->>Dashboard: Clic en "Publicar en Subasta" en orden
    Dashboard->>ProviderMS: PublishAuctionCommand
    ProviderMS->>ProviderDB: Crea subasta (Estado: PUBLISHED, duración: 48h)
    ProviderMS->>NotificationsMS: AuctionPublishedEvent
    NotificationsMS->>ProviderDB: Consulta proveedores elegibles (ACTIVE + servicios coincidentes)
    NotificationsMS->>Providers: Envía email + WhatsApp a cada proveedor

    Providers->>Dashboard: Ver detalles de subasta (anónimo)
    Providers->>Dashboard: Enviar oferta (monto, tiempo, notas)
    Dashboard->>ProviderMS: SubmitOfferCommand
    ProviderMS->>ProviderDB: Guarda AuctionOffer (Estado: PENDING)
    ProviderMS->>NotificationsMS: OfferSubmittedEvent
    NotificationsMS->>Providers: Email de confirmación

    Agent->>Dashboard: Ver ofertas (ordenadas por monto)
    Agent->>Dashboard: Clic en oferta para ver detalles del proveedor
    Agent->>Dashboard: Seleccionar ganador
    Dashboard->>ProviderMS: SelectWinnerCommand
    ProviderMS->>ProviderDB: Actualiza subasta (Estado: CLOSED)
    ProviderMS->>ProviderDB: Actualiza oferta ganadora (Estado: ACCEPTED)
    ProviderMS->>ProviderDB: Actualiza otras ofertas (Estado: REJECTED)
    ProviderMS->>NotificationsMS: AuctionClosedEvent + ProviderSelectedEvent
    NotificationsMS->>Providers: Notificación de ganador + Notificaciones de rechazo
    ProviderMS->>OrdersMS: ProviderSelectedEvent (orden asignada)

Figura: Secuencia de Flujo de Subasta/Marketplace - Publicación de orden en subasta, ofertas de proveedores y proceso de selección del ganador

Auction Business Rules:

  • Duration: 24-72 hours (configurable)
  • Anonymous bidding (provider names hidden during bidding)
  • Provider can submit only ONE offer per auction
  • Minimum 3 offers recommended (configurable)
  • Only Activo providers with valid Documentos can bid

3. Quotation Approval Flow

Process: Break Down Order → Provider Quotes Items → Agent Adjusts → Client Approves

sequenceDiagram
participant Agent
participant Provider
participant Client
participant OrdersMS
participant NotificationsMS

    Agent->>OrdersMS: CreateOrderItemsCommand<br/>[{desc: "Replace pump", qty: 1, unit: "unit"}]
    OrdersMS->>OrdersMS: Create OrderItem entities
    OrdersMS->>NotificationsMS: OrderItemsCreatedEvent
    NotificationsMS->>Provider: "Items ready for quotation"

    Provider->>OrdersMS: SubmitQuotationCommand<br/>[{itemId, unitPrice: 500, total: 500}]
    OrdersMS->>OrdersMS: Create Quotation entity (Estado: SUBMITTED)
    OrdersMS->>NotificationsMS: QuotationSubmittedEvent
    NotificationsMS->>Agent: "Quotation ready for review"

    Agent->>OrdersMS: InflateQuotationCommand (inflation: 20%)
    OrdersMS->>OrdersMS: Apply markup to all items
    OrdersMS->>OrdersMS: Calculate new total

    Agent->>OrdersMS: SendQuotationToClientCommand
    OrdersMS->>OrdersMS: Generate PDF with Puppeteer
    OrdersMS->>OrdersMS: Upload PDF to Azure Blob
    OrdersMS->>NotificationsMS: QuotationSentToClientEvent
    NotificationsMS->>Client: Email with PDF + WhatsApp link

    Client->>OrdersMS: ProcessClientApprovalCommand (approved: true, rating: 5)
    OrdersMS->>OrdersMS: Update order Estado to APPROVED
    OrdersMS->>NotificationsMS: OrderApprovedEvent
    NotificationsMS->>Provider: "Client approved quotation. Start execution"
    NotificationsMS->>Agent: "Order approved by client"

Figura: Quotation Approval Flow Sequence - Item breakdown, provider quotation submission, agent markup, and client approval process

Quotation Data Model:

{
  orderId: "ORD-001",
  items: [
    {
      Descripción: "Replace water pump",
      quantity: 1,
      unitOfMeasure: "unit",
      providerUnitPrice: 500,
      inflationPercentage: 20,
      finalUnitPrice: 600,
      finalTotalPrice: 600
    }
  ],
  subtotal: 500,
  inflationPercentage: 20,
  total: 600,
  Estado: "SENT_TO_CLIENT",
  pdfUrl: "https://blob.storage.azure.com/quotations/ORD-001.pdf"
}

See also: ADR-006: Item-Based Quotation

4. Order Execution and Closure Flow

Process: Confirm Date → Execute Work → Submit Report → Client Final Approval

sequenceDiagram
participant Provider
participant OrdersMS
participant Client
participant NotificationsMS
participant BlobStorage

    Provider->>OrdersMS: ConfirmExecutionDateCommand (date: 2025-11-25)
    OrdersMS->>OrdersMS: Update order (Estado: SCHEDULED, executionDate: 2025-11-25)
    OrdersMS->>NotificationsMS: ExecutionDateConfirmedEvent
    NotificationsMS->>Client: "Execution scheduled for Nov 25"

    Note over Provider: Provider performs work on-site

    Provider->>OrdersMS: SubmitExecutionReportCommand<br/>{Descripción, photos[], completionEstado: CompletoD}
    OrdersMS->>BlobStorage: Upload photos
    OrdersMS->>OrdersMS: Generate execution report PDF
    OrdersMS->>BlobStorage: Upload PDF
    OrdersMS->>OrdersMS: Update order (Estado: EXECUTION_CompletoD)
    OrdersMS->>NotificationsMS: ExecutionReportSubmittedEvent
    NotificationsMS->>Client: Email with PDF + WhatsApp link

    Client->>OrdersMS: ProcessFinalApprovalCommand (approved: true, rating: 5)
    OrdersMS->>OrdersMS: Update order (Estado: CLOSED)
    OrdersMS->>OrdersMS: Update provider rating
    OrdersMS->>NotificationsMS: OrderClosedEvent
    NotificationsMS->>Provider: "Order closed successfully. Thank you!"

Figura: Order Execution and Closure Flow Sequence - Work execution confirmation, report submission, and final client approval process

Execution Report Fields:

  • Work Descripción
  • Photos (before, during, after)
  • Materials used
  • Completion Estado: CompletoD | PARTIAL | Pendiente
  • Notes/observations
  • Provider signature (optional)

5. Asset Management and History Flow

Process: Capture Serial (OCR) → Query/Create Asset → Link to Order → Update History

sequenceDiagram
participant Client
participant Jelou as Jelou Bot
participant OCR as Tesseract.js
participant OrdersMS
participant AssetsAPI as Legacy Assets API
participant OrdersDB

    Client->>Jelou: Send photo of asset serial plate
    Jelou->>OCR: Process image
    OCR-->>Jelou: Serial: "AC-12345" (confidence: 85%)
    Jelou->>Client: "¿El serial es AC-12345?"
    Client->>Jelou: "Sí"

    Note over OrdersMS: During order creation
    OrdersMS->>AssetsAPI: GET /api/assets/:serial
    alt Asset exists
        AssetsAPI-->>OrdersMS: Asset details
        OrdersMS->>OrdersMS: Link order to existing asset
    else Asset not found
        OrdersMS->>OrdersDB: Create new Asset entity
        OrdersMS->>OrdersDB: Create AssetHistoryEvent (type: CREATED)
    end

    OrdersMS->>OrdersDB: Link order to asset
    OrdersMS->>OrdersDB: Add AssetHistoryEvent (type: MAINTENANCE_REQUEST)

    Note over OrdersMS: During order lifecycle
    OrdersMS->>OrdersDB: Add event: QUOTATION_APPROVED
    OrdersMS->>OrdersDB: Add event: EXECUTION_CompletoD with photos + work Descripción

    Note over OrdersMS: Agent or client views asset history
    OrdersMS->>OrdersDB: Query Asset + all AssetHistoryEvents
    OrdersMS->>OrdersMS: Generate asset history PDF (timeline, photos, costs)

Figura: Asset Management and History Flow Sequence - OCR-based asset identification, linking to orders, and maintaining Completo asset history

Asset History Events:

  • CREATED - Asset registered in system
  • MAINTENANCE_REQUEST - Order created for asset
  • QUOTATION_APPROVED - Maintenance approved with cost
  • EXECUTION_CompletoD - Maintenance performed
  • ASSET_UPDATED - Asset details changed
  • Estado_CHANGED - Asset Estado changed (Activo → INActivo → RETIRED)

See also:

6. Documento Management and Expiry Flow

Process: Upload Documento → Validate → Schedule Expiry Checks → Send Reminders → Suspend if Expired

sequenceDiagram
participant Provider
participant ProviderMS
participant BlobStorage
participant ProviderDB
participant ExpiryTask as DocumentoExpiryCheckTask
participant NotificationsMS

    Provider->>ProviderMS: UploadDocumentoCommand (type: ARL, file: PDF, expiryDate: 2025-12-31)
    ProviderMS->>ProviderMS: Validate file type, size
    ProviderMS->>BlobStorage: Upload to provider-Documentos/{providerId}/arl/
    BlobStorage-->>ProviderMS: Blob URL + SAS token
    ProviderMS->>ProviderDB: Save Documento metadata (Estado: Pendiente, expiryDate: 2025-12-31)

    Note over ExpiryTask: Daily cron job (midnight)
    ExpiryTask->>ProviderDB: Query Documentos with expiryDate
    ExpiryTask->>ExpiryTask: Check if expiring in 30, 15, 7 days

    alt Expiring in 30 days
        ExpiryTask->>NotificationsMS: DocumentoExpiringEvent (daysLeft: 30)
        NotificationsMS->>Provider: "ARL expires in 30 days. Please renew."
    end

    alt Expiring in 15 days
        ExpiryTask->>NotificationsMS: DocumentoExpiringEvent (daysLeft: 15)
        NotificationsMS->>Provider: "⚠️ ARL expires in 15 days!"
    end

    alt Expiring in 7 days
        ExpiryTask->>NotificationsMS: DocumentoExpiringEvent (daysLeft: 7)
        NotificationsMS->>Provider: "🚨 ARL expires in 7 days. Urgent!"
    end

    alt Expired
        ExpiryTask->>ProviderDB: Update Documento (Estado: EXPIRED)
        ExpiryTask->>ProviderDB: Update provider (Estado: SUSPENDED)
        ExpiryTask->>NotificationsMS: DocumentoExpiredEvent
        NotificationsMS->>Provider: "❌ ARL expired. Account suspended. Upload renewed Documento."
    end

    Provider->>ProviderMS: Upload renewed ARL
    ProviderMS->>ProviderDB: Update Documento (Estado: Pendiente, new expiryDate)
    ProviderMS->>ProviderDB: Update provider (Estado: Pendiente_DocumentoS)

Figura: Documento Management and Expiry Flow Sequence - Document upload with automatic expiry tracking, reminder notifications, and provider suspension for expired Documentos

Referencias Cruzadas

For detailed Documentoation of each process: