openapi: "3.0.0"
info:
  title: "Industrial Maintenance Expert API"
  version: "1.0.0"
  description: |
    API especializada en monitoreo y mantenimiento predictivo industrial.
    Diseñada específicamente para integración con Bedrock Agents, proporcionando:
    - Datos contextualizados de sensores industriales
    - Análisis histórico y predictivo
    - Recomendaciones de mantenimiento basadas en patrones

    Esta API sigue principios AI-Friendly, facilitando el razonamiento
    y toma de decisiones de los modelos de lenguaje.

paths:
  /equipment:
    get:
      summary: "Lista todos los equipos monitoreados"
      description: |
        Proporciona una vista general de todos los equipos en la planta,
        incluyendo su estado actual y métricas clave.

        Use este endpoint cuando necesite:
        - Evaluación general del estado de la planta
        - Identificación de equipos críticos
        - Planificación de mantenimiento global
      operationId: "listEquipment"
      tags: ["monitoring"]
      responses:
        '200':
          description: "Lista exitosa de equipos con su estado"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Equipment'
              example:
                - id: "COMP-101"
                  type: "compressor"
                  location: "north_plant"
                  status: "warning"
                  lastMaintenance: "2024-01-15"
                  healthScore: 0.82

  /equipment/{equipmentId}/health:
    get:
      summary: "Obtiene estado completo de un equipo"
      description: |
        Análisis comprehensivo del estado de un equipo específico.
        Incluye métricas actuales, tendencias, patrones históricos
        y recomendaciones de mantenimiento.

        Este endpoint es crucial para:
        - Evaluación detallada de salud del equipo
        - Detección temprana de anomalías
        - Planificación de mantenimiento preventivo
        - Análisis de patrones de degradación
      operationId: "getEquipmentHealth"
      tags: ["monitoring", "analysis"]
      parameters:
        - name: equipmentId
          in: path
          description: "ID único del equipo (ejemplo: COMP-101)"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: |
            Estado detallado del equipo incluyendo:
            - Métricas actuales con interpretación
            - Análisis de tendencias
            - Recomendaciones basadas en patrones
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthAssessment'

  /equipment/{equipmentId}/metrics:
    get:
      summary: "Obtiene métricas en tiempo real"
      description: |
        Proporciona lecturas actuales de todos los sensores
        asociados al equipo, con interpretación contextual
        y comparación con rangos normales.

        Ideal para:
        - Monitoreo en tiempo real
        - Verificación de alarmas
        - Validación de operación normal
      operationId: "getEquipmentMetrics"
      tags: ["monitoring"]
      parameters:
        - name: equipmentId
          in: path
          description: "ID del equipo"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "Métricas actuales con interpretación"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metrics'

  /equipment/{equipmentId}/maintenance-history:
    get:
      summary: "Obtiene historial de mantenimiento"
      description: |
        Proporciona registro completo de mantenimientos,
        incluyendo preventivos, correctivos y hallazgos.

        Útil para:
        - Análisis de patrones de fallo
        - Planificación de mantenimiento
        - Optimización de intervalos
      operationId: "getMaintenanceHistory"
      tags: ["maintenance"]
      parameters:
        - name: equipmentId
          in: path
          description: "ID del equipo"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "Historial detallado de mantenimiento"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaintenanceHistory'

components:
  schemas:
    Equipment:
      type: object
      description: "Información básica de equipo industrial"
      properties:
        id:
          type: string
          description: "Identificador único del equipo"
        type:
          type: string
          description: "Tipo de equipo"
          enum: ["compressor", "pump", "turbine", "motor"]
        location:
          type: string
          description: "Ubicación en planta"
        status:
          type: string
          description: "Estado operativo actual"
          enum: ["normal", "warning", "critical", "maintenance"]
        healthScore:
          type: number
          format: float
          description: |
            Índice de salud del equipo (0-1)
            - 0.9-1.0: Excelente
            - 0.7-0.9: Bueno
            - 0.5-0.7: Requiere atención
            - <0.5: Crítico

    HealthAssessment:
      type: object
      description: "Evaluación completa de salud del equipo"
      properties:
        timestamp:
          type: string
          format: date-time
          description: "Momento de la evaluación"
        currentMetrics:
          $ref: '#/components/schemas/Metrics'
        trends:
          type: object
          description: "Análisis de tendencias"
          properties:
            degradationRate:
              type: number
              description: "Tasa de degradación (%/día)"
            predictedFailureTime:
              type: string
              format: date-time
              description: "Tiempo estimado hasta fallo crítico"
        recommendations:
          type: array
          items:
            $ref: '#/components/schemas/Recommendation'

    Metrics:
      type: object
      description: "Métricas en tiempo real del equipo"
      properties:
        temperature:
          type: object
          properties:
            value:
              type: number
              description: "Temperatura actual en Celsius"
            status:
              type: string
              enum: ["normal", "warning", "critical"]
            normalRange:
              type: object
              properties:
                min:
                  type: number
                  description: "Límite inferior normal"
                max:
                  type: number
                  description: "Límite superior normal"
        vibration:
          type: object
          properties:
            value:
              type: number
              description: "Vibración en g"
            status:
              type: string
              enum: ["normal", "warning", "critical"]
            trend:
              type: string
              description: "Tendencia de cambio"

    MaintenanceHistory:
      type: object
      description: "Historial de mantenimiento"
      properties:
        equipmentId:
          type: string
        records:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                format: date
              type:
                type: string
                enum: ["preventive", "corrective", "emergency"]
              findings:
                type: string
                description: "Hallazgos y acciones tomadas"
              nextScheduled:
                type: string
                format: date

    Recommendation:
      type: object
      description: "Recomendación de mantenimiento"
      properties:
        priority:
          type: string
          enum: ["high", "medium", "low"]
        action:
          type: string
          description: "Acción recomendada"
        rationale:
          type: string
          description: "Justificación de la recomendación"
        deadline:
          type: string
          format: date
          description: "Fecha límite recomendada"
