Skip to content

BSS Swap-Network Operator Workflow Specification

Workflow Diagram

BSS Operator Workflow

Complete sequence diagram showing the operator service coordination journey through six workflow areas: OP1 (Station Readiness Management), OP2 (Service Intent Monitoring), OP3 (Customer Service Coordination), OP4 (Asset Management Operations), OP5 (Performance Monitoring), and OP6 (Issue Resolution).

Purpose

This document defines the comprehensive workflow experience for swap-network operators managing battery swap stations, coordinating service delivery, and maintaining operational excellence. It focuses on the operator's role in facilitating smooth service delivery while managing station operations, customer interactions, and asset coordination.

Source Traceability

  • Parent Document: bss-technical-specs.md
  • Target Implementation: bss-agent-v2.ts operator experience functions + operator portal interfaces
  • Focus Area: Swap-network operator service coordination and station management

Overview: Operator Service Coordination Journey

The swap-network operator experience follows operational workflows designed for efficient service delivery:

  1. 🏢 Station Readiness Management: Ensure station operational status and asset availability
  2. 📡 Service Intent Monitoring: Monitor incoming customer service requests and intent signals
  3. 🎯 Customer Service Coordination: Guide customers through service process and handle issues
  4. 🔋 Asset Management Operations: Coordinate battery swaps, inventory, and equipment status
  5. 📊 Performance Monitoring: Track station performance and operational metrics
  6. 🛠️ Issue Resolution: Handle service issues, customer support, and technical problems

OP1: Station Readiness Management

Workflow: "Ensure station is ready for service operations"

Agent Function: manageStationReadiness

OP1.1: Station Status Monitoring

  1. Asset Inventory Check: Verify battery inventory levels and charge status
  2. Equipment Status Validation: Confirm all swap equipment is operational
  3. Safety System Verification: Validate safety systems and emergency protocols
  4. Staff Readiness Confirmation: Ensure adequate staffing for service delivery
  5. Service Capability Assessment: Determine station's current service capacity

OP1.2: Readiness State Broadcasting

  1. Station Status Signal: Broadcast current station readiness status
  2. Capacity Information: Share available service slots and estimated wait times
  3. Asset Availability Update: Update available battery inventory for customer visibility
  4. Service Restrictions Communication: Notify of any service limitations or special conditions
  5. ARM Integration: Coordinate with ARM for asset availability updates

OP1.3: MQTT Status Broadcasting

Topic Pattern: emit/abs/bss/station/{station_id}/status_update

Status Payload: 

{
  "station_id": "STATION_001",
  "operational_status": "ready|busy|maintenance|offline",
  "battery_inventory": {
    "available_batteries": 12,
    "charging_batteries": 8,
    "reserved_batteries": 2,
    "total_capacity": 24
  },
  "service_capacity": {
    "current_queue_length": 0,
    "estimated_wait_time_minutes": 0,
    "max_concurrent_services": 3,
    "active_service_slots": 1
  },
  "equipment_status": {
    "swap_cabinet_operational": true,
    "charging_infrastructure_status": "normal",
    "safety_systems_status": "active"
  },
  "staff_status": {
    "on_duty_operators": 2,
    "shift_end_time": "2025-01-15T22:00:00Z",
    "operator_certifications_valid": true
  },
  "service_restrictions": [
    "premium_battery_service_only",
    "manual_assistance_required"
  ],
  "last_updated": "2025-01-15T14:30:00Z"
}

Station Readiness Outcomes

  • ✅ STATION_READY: Station fully operational and ready for service
  • 🔋 INVENTORY_SUFFICIENT: Adequate battery inventory for projected demand
  • ⚙️ EQUIPMENT_OPERATIONAL: All equipment functioning within normal parameters
  • 👥 STAFF_READY: Adequate staffing and certifications for service delivery
  • ⚠️ LIMITED_SERVICE: Station operational but with service restrictions
  • 🛠️ MAINTENANCE_REQUIRED: Station needs maintenance before full service
  • ❌ STATION_OFFLINE: Station not operational due to critical issues

Implementation Requirements

// Target function: manageStationReadiness
const manageStationReadiness = async (requestData: RequestData, planState: PlanState): Promise<PartialOutcome> => {
  const stationId = requestData.station_id;
  const shiftContext = requestData.operator_shift_context;

  // Check battery inventory levels and charge status
  // Validate equipment operational status
  // Verify safety systems and emergency protocols
  // Confirm staff readiness and certifications
  // Assess overall service capacity
  // Broadcast station status via MQTT

  return {
    signals: ['STATION_READY' | 'INVENTORY_SUFFICIENT' | 'EQUIPMENT_OPERATIONAL' | 'STAFF_READY' | 'LIMITED_SERVICE' | 'MAINTENANCE_REQUIRED' | 'STATION_OFFLINE'],
    metadata: {
      station_status: {
        station_id: stationId,
        operational_status: 'ready|busy|maintenance|offline',
        readiness_score: 'calculated readiness percentage',
        service_capacity: 'current service capacity assessment'
      },
      inventory_assessment: {
        battery_counts: {
          available: 'ready for immediate use',
          charging: 'batteries currently charging',
          reserved: 'batteries reserved for specific customers',
          maintenance: 'batteries requiring maintenance'
        },
        charge_status_distribution: 'battery charge level distribution',
        projected_demand: 'estimated customer demand for shift'
      },
      equipment_diagnostics: {
        swap_cabinet_status: 'operational|degraded|offline',
        charging_infrastructure: 'status of charging equipment',
        safety_systems: 'fire suppression, emergency stops, etc.',
        communication_systems: 'MQTT, internet connectivity, etc.'
      },
      staff_assessment: {
        on_duty_count: 'number of operators currently on duty',
        certification_status: 'all certifications valid and current',
        shift_coverage: 'adequate coverage for projected demand',
        emergency_contacts: 'supervisor and emergency contact availability'
      },
      mqtt_broadcast: {
        topic: `emit/abs/bss/station/${stationId}/status_update`,
        payload: 'comprehensive station status for customer and ARM visibility',
        broadcast_frequency: 'regular status updates every 5 minutes'
      }
    }
  };
};

OP2: Service Intent Monitoring

Workflow: "Monitor and respond to customer service requests"

Agent Function: monitorServiceIntents

OP2.1: Intent Signal Reception

  1. MQTT Signal Monitoring: Listen for customer service intent signals
  2. Intent Signal Analysis: Parse customer requirements and service needs
  3. Service Capability Matching: Verify station can fulfill customer requirements
  4. Queue Management: Manage customer service queue and priority handling
  5. Response Signal Preparation: Prepare acknowledgment and service coordination signals

OP2.2: Customer Service Coordination

  1. Service Acknowledgment: Confirm receipt of customer service intent
  2. Queue Position Assignment: Assign customer position in service queue
  3. Estimated Wait Time: Calculate and communicate expected service time
  4. Special Requirements Handling: Address any special service needs or preferences
  5. Preparation Instructions: Provide customer with arrival and preparation instructions

OP2.3: MQTT Intent Listening and Response

Listening Topic: emit/abs/bss/service/+/intent_signal Response Topic: echo/abs/bss/service/{customer_id}/intent_acknowledged

Intent Acknowledgment Payload: 

{
  "customer_id": "customer_001",
  "station_id": "STATION_001",
  "acknowledgment_status": "accepted|queued|rejected|conditional",
  "queue_information": {
    "queue_position": 2,
    "estimated_wait_minutes": 15,
    "customers_ahead": 1,
    "current_service_in_progress": true
  },
  "service_preparation": {
    "arrival_instructions": "Arrive at Bay 2, scan QR code on arrival",
    "battery_compatibility_confirmed": true,
    "special_requirements_noted": ["fast_service_preferred"],
    "operator_assignment": "OPR-001"
  },
  "conditional_requirements": {
    "payment_verification_required": false,
    "service_plan_validation_needed": false,
    "identity_verification_required": true
  },
  "operator_context": {
    "operator_id": "OPR-001",
    "operator_name": "John Smith",
    "shift_end_time": "2025-01-15T22:00:00Z",
    "operator_certification": "BSS-Level-2"
  },
  "acknowledgment_timestamp": "2025-01-15T14:32:00Z"
}

Service Intent Monitoring Outcomes

  • 📡 INTENT_RECEIVED: Customer service intent successfully received
  • ✅ SERVICE_ACCEPTED: Customer service request accepted and queued
  • 📋 QUEUE_POSITION_ASSIGNED: Customer assigned position in service queue
  • ⏱️ WAIT_TIME_CALCULATED: Accurate wait time estimate provided
  • ⚠️ SERVICE_CONDITIONAL: Service accepted with specific conditions
  • ❌ SERVICE_REJECTED: Service request rejected due to capacity/compatibility
  • 🔄 QUEUE_UPDATED: Service queue updated with new customer

Implementation Requirements

// Target function: monitorServiceIntents
const monitorServiceIntents = async (requestData: RequestData, planState: PlanState): Promise<PartialOutcome> => {
  const intentSignal = requestData.customer_intent_signal;
  const stationId = requestData.station_id;
  const operatorId = requestData.operator_id;

  // Parse customer service intent signal
  // Analyze service requirements against station capabilities
  // Check service queue capacity and current load
  // Calculate estimated wait time and queue position
  // Prepare acknowledgment signal with service coordination details
  // Send echo response via MQTT

  return {
    signals: ['INTENT_RECEIVED' | 'SERVICE_ACCEPTED' | 'QUEUE_POSITION_ASSIGNED' | 'WAIT_TIME_CALCULATED' | 'SERVICE_CONDITIONAL' | 'SERVICE_REJECTED' | 'QUEUE_UPDATED'],
    metadata: {
      intent_analysis: {
        customer_id: intentSignal.customer_id,
        service_requirements: intentSignal.service_requirements,
        compatibility_check: 'station can fulfill requirements',
        special_needs_assessment: 'analysis of special requirements'
      },
      service_coordination: {
        queue_position: 'assigned position in service queue',
        estimated_wait_time: 'calculated wait time in minutes',
        operator_assignment: operatorId,
        service_bay_assignment: 'designated service bay or area'
      },
      acknowledgment_signal: {
        mqtt_topic: `echo/abs/bss/service/${intentSignal.customer_id}/intent_acknowledged`,
        acknowledgment_status: 'accepted|queued|rejected|conditional',
        preparation_instructions: 'customer arrival and preparation guidance',
        operator_contact: 'operator contact information for customer'
      },
      queue_management: {
        current_queue_length: 'updated queue length after addition',
        queue_priority_adjustments: 'any priority-based queue adjustments',
        capacity_utilization: 'current station capacity utilization percentage'
      }
    }
  };
};

OP3: Customer Service Coordination

Workflow: "Guide customer through service process"

Agent Function: coordinateCustomerService

OP3.1: Customer Arrival Processing

  1. Customer Identity Verification: Confirm customer identity and service authorization
  2. Service Plan Validation: Verify customer's service plan and quota availability
  3. Location Binding Confirmation: Confirm customer-location binding established
  4. Service Bay Assignment: Direct customer to appropriate service bay or area
  5. Service Initiation Preparation: Prepare for battery swap service execution

OP3.2: Service Execution Guidance

  1. Safety Briefing: Provide safety instructions and service procedure overview
  2. Battery Swap Coordination: Coordinate physical battery swap process
  3. Service Quality Assurance: Monitor service execution for quality and safety
  4. Issue Resolution: Handle any service issues or customer concerns immediately
  5. Service Completion Verification: Verify successful service completion

OP3.3: Customer Experience Management

  1. Communication Management: Maintain clear communication throughout service
  2. Wait Time Management: Provide accurate updates on service progress
  3. Problem Escalation: Escalate complex issues to supervisors or technical support
  4. Customer Feedback Collection: Gather customer feedback for service improvement
  5. Service Documentation: Document service details for record-keeping

Customer Service Coordination Outcomes

  • ✅ CUSTOMER_VERIFIED: Customer identity and authorization confirmed
  • 🎯 SERVICE_BAY_ASSIGNED: Customer directed to appropriate service location
  • 🔋 SWAP_SERVICE_INITIATED: Battery swap service process started
  • 👥 OPERATOR_ENGAGED: Operator actively engaged in customer service
  • ⚠️ ISSUE_DETECTED: Service issue identified requiring attention
  • 🛠️ TECHNICAL_SUPPORT_REQUIRED: Complex issue requiring specialist assistance
  • ✅ SERVICE_COMPLETED: Customer service successfully completed

Implementation Requirements

// Target function: coordinateCustomerService
const coordinateCustomerService = async (requestData: RequestData, planState: PlanState): Promise<PartialOutcome> => {
  const customerId = requestData.customer_id;
  const serviceDetails = requestData.service_details;
  const operatorId = requestData.operator_id;

  // Verify customer identity and service authorization
  // Validate service plan and quota availability
  // Assign appropriate service bay and equipment
  // Guide customer through service process
  // Monitor service execution for quality and safety
  // Handle any issues or customer concerns
  // Document service completion and customer feedback

  return {
    signals: ['CUSTOMER_VERIFIED' | 'SERVICE_BAY_ASSIGNED' | 'SWAP_SERVICE_INITIATED' | 'OPERATOR_ENGAGED' | 'ISSUE_DETECTED' | 'TECHNICAL_SUPPORT_REQUIRED' | 'SERVICE_COMPLETED'],
    metadata: {
      customer_processing: {
        customer_id: customerId,
        identity_verification_method: 'QR_code|NFC|manual|biometric',
        service_authorization_status: 'verified|conditional|denied',
        service_plan_validation: 'plan active and quota available'
      },
      service_coordination: {
        service_bay_assignment: 'designated service bay or area',
        operator_assignment: operatorId,
        estimated_service_duration: 'expected time for service completion',
        service_priority_level: 'normal|urgent|premium'
      },
      service_execution: {
        safety_briefing_completed: 'customer informed of safety procedures',
        battery_swap_status: 'initiated|in_progress|completed|failed',
        service_quality_metrics: 'real-time service quality assessment',
        customer_satisfaction_indicators: 'customer feedback during service'
      },
      issue_management: {
        issues_detected: 'any service issues or complications',
        resolution_actions: 'steps taken to resolve issues',
        escalation_required: 'whether supervisor or technical support needed',
        customer_communication: 'updates provided to customer'
      },
      service_documentation: {
        service_start_time: 'timestamp of service initiation',
        service_completion_time: 'timestamp of service completion',
        battery_swap_details: 'old battery ID, new battery ID',
        customer_feedback_score: 'customer satisfaction rating',
        operator_notes: 'any special notes or observations'
      }
    }
  };
};

OP4: Asset Management Operations

Workflow: "Coordinate battery and equipment management"

Agent Function: manageAssetOperations

OP4.1: Battery Inventory Management

  1. Battery Status Monitoring: Track battery charge levels and availability
  2. Charging Schedule Coordination: Manage battery charging sequences and priorities
  3. Battery Quality Assessment: Monitor battery health and performance metrics
  4. Inventory Optimization: Maintain optimal mix of available and charging batteries
  5. Asset Movement Tracking: Track battery movements and assignments

OP4.2: Equipment Operations

  1. Swap Cabinet Management: Monitor and operate automated swap equipment
  2. Charging Infrastructure: Manage charging stations and power distribution
  3. Safety System Monitoring: Oversee safety systems and emergency protocols
  4. Preventive Maintenance: Coordinate routine maintenance and inspections
  5. Equipment Performance Tracking: Monitor equipment efficiency and utilization

OP4.3: Asset Coordination Signals

Topic Pattern: emit/abs/bss/asset/{asset_type}/{asset_id}/operation_command

Battery Management Signal: 

{
  "asset_type": "battery",
  "asset_id": "BAT-001",
  "operation_command": "initiate_charge|stop_charge|quality_check|assign_to_customer|return_to_inventory",
  "operator_context": {
    "operator_id": "OPR-001",
    "station_id": "STATION_001",
    "operation_reason": "customer_service|maintenance|optimization"
  },
  "asset_parameters": {
    "target_charge_level": 95,
    "charging_priority": "normal|urgent|low",
    "quality_check_type": "routine|diagnostic|full_inspection",
    "assignment_duration": "service_completion|24_hours|indefinite"
  },
  "safety_considerations": {
    "temperature_monitoring": true,
    "safety_protocols_active": ["fire_suppression", "emergency_shutdown"],
    "operator_safety_certification": "BSS-Level-2"
  },
  "tracking_metadata": {
    "operation_sequence_id": "unique_operation_identifier",
    "expected_completion_time": "2025-01-15T15:30:00Z",
    "performance_tracking": true
  },
  "timestamp": "2025-01-15T15:00:00Z"
}

Asset Management Outcomes

  • 🔋 BATTERY_STATUS_UPDATED: Battery status successfully updated
  • ⚡ CHARGING_SEQUENCE_OPTIMIZED: Battery charging schedule optimized
  • ✅ ASSET_OPERATION_COMPLETED: Asset operation successfully executed
  • ⚙️ EQUIPMENT_STATUS_VERIFIED: Equipment operational status confirmed
  • ⚠️ MAINTENANCE_REQUIRED: Asset or equipment requires maintenance attention
  • 🛠️ TECHNICAL_ISSUE_DETECTED: Technical problem requiring specialist intervention
  • 📊 PERFORMANCE_METRICS_UPDATED: Asset performance data updated

Implementation Requirements

// Target function: manageAssetOperations
const manageAssetOperations = async (requestData: RequestData, planState: PlanState): Promise<PartialOutcome> => {
  const assetOperation = requestData.asset_operation;
  const operatorId = requestData.operator_id;
  const stationId = requestData.station_id;

  // Monitor battery inventory and charge status
  // Coordinate charging schedules and priorities
  // Manage battery quality assessments
  // Operate swap cabinet and charging equipment
  // Track asset movements and assignments
  // Monitor equipment performance and safety systems
  // Coordinate with ARM for asset state updates

  return {
    signals: ['BATTERY_STATUS_UPDATED' | 'CHARGING_SEQUENCE_OPTIMIZED' | 'ASSET_OPERATION_COMPLETED' | 'EQUIPMENT_STATUS_VERIFIED' | 'MAINTENANCE_REQUIRED' | 'TECHNICAL_ISSUE_DETECTED' | 'PERFORMANCE_METRICS_UPDATED'],
    metadata: {
      battery_management: {
        inventory_status: {
          available_batteries: 'batteries ready for immediate service',
          charging_batteries: 'batteries currently charging',
          maintenance_batteries: 'batteries requiring maintenance',
          total_capacity: 'maximum battery capacity at station'
        },
        charging_coordination: {
          charging_schedule: 'optimized charging sequence',
          priority_charging: 'batteries requiring urgent charging',
          power_distribution: 'electrical load balancing across chargers',
          estimated_charge_completion: 'completion times for charging batteries'
        },
        quality_monitoring: {
          battery_health_metrics: 'health status of all batteries',
          performance_degradation_tracking: 'battery performance over time',
          quality_alerts: 'batteries requiring attention or replacement',
          lifecycle_management: 'battery age and usage tracking'
        }
      },
      equipment_operations: {
        swap_cabinet_status: {
          operational_status: 'cabinet operational status',
          current_operations: 'active swap operations',
          maintenance_alerts: 'equipment requiring attention',
          performance_metrics: 'cabinet efficiency and speed metrics'
        },
        charging_infrastructure: {
          charger_status: 'individual charger operational status',
          power_consumption: 'current power usage and capacity',
          charging_efficiency: 'energy efficiency metrics',
          thermal_management: 'temperature monitoring and cooling'
        },
        safety_systems: {
          fire_suppression_status: 'fire safety system operational status',
          emergency_shutdown_systems: 'emergency stop and shutdown capabilities',
          safety_monitoring: 'continuous safety parameter monitoring',
          operator_safety_compliance: 'operator safety certification status'
        }
      },
      asset_coordination: {
        arm_integration: {
          asset_state_synchronization: 'sync with ARM for asset updates',
          asset_assignment_tracking: 'track asset assignments and movements',
          location_inventory_updates: 'update location inventory in ARM'
        },
        operation_tracking: {
          operation_sequence_id: 'unique identifier for operation tracking',
          performance_metrics: 'operation efficiency and success rates',
          operator_performance: 'individual operator performance tracking'
        }
      }
    }
  };
};

OP5: Performance Monitoring

Workflow: "Track station performance and operational metrics"

Agent Function: monitorStationPerformance

OP5.1: Real-Time Performance Tracking

  1. Service Metrics Collection: Track service completion times, queue lengths, customer satisfaction
  2. Asset Utilization Monitoring: Monitor battery usage, charging efficiency, equipment uptime
  3. Operator Performance Assessment: Track individual operator performance and productivity
  4. Revenue Generation Tracking: Monitor service revenue and utilization rates
  5. Efficiency Optimization: Identify opportunities for operational improvements

OP5.2: Performance Analytics and Reporting

  1. Daily Performance Summary: Generate daily operational performance reports
  2. Trend Analysis: Identify performance trends and seasonal patterns
  3. Benchmark Comparison: Compare performance against station targets and network averages
  4. Predictive Analytics: Forecast demand and resource requirements
  5. Performance Alerts: Generate alerts for performance issues or opportunities

OP5.3: Performance Data Broadcasting

Topic Pattern: emit/abs/bss/station/{station_id}/performance_metrics

Performance Metrics Payload: 

{
  "station_id": "STATION_001",
  "reporting_period": {
    "start_time": "2025-01-15T00:00:00Z",
    "end_time": "2025-01-15T23:59:59Z",
    "period_type": "daily|weekly|monthly"
  },
  "service_metrics": {
    "total_services_completed": 45,
    "average_service_time_minutes": 8.5,
    "customer_satisfaction_score": 4.7,
    "service_success_rate": 0.98,
    "peak_hour_performance": {
      "peak_period": "17:00-19:00",
      "services_during_peak": 12,
      "average_wait_time_peak": 6.2
    }
  },
  "asset_utilization": {
    "battery_swap_count": 45,
    "battery_utilization_rate": 0.75,
    "charging_efficiency": 0.92,
    "equipment_uptime": 0.98,
    "energy_consumption_kwh": 320.5
  },
  "operator_performance": {
    "total_operators": 3,
    "average_services_per_operator": 15,
    "operator_efficiency_score": 0.87,
    "customer_interaction_quality": 4.6,
    "safety_compliance_score": 1.0
  },
  "revenue_metrics": {
    "total_revenue_generated": 2250.00,
    "average_revenue_per_service": 50.00,
    "premium_service_percentage": 0.33,
    "revenue_per_hour": 93.75
  },
  "operational_efficiency": {
    "station_capacity_utilization": 0.68,
    "resource_optimization_score": 0.82,
    "waste_reduction_metrics": {
      "energy_waste_percentage": 0.05,
      "time_waste_percentage": 0.08
    }
  },
  "performance_alerts": [
    {
      "alert_type": "efficiency_opportunity",
      "description": "Peak hour capacity could be increased",
      "recommended_action": "Consider additional operator during 17:00-19:00"
    }
  ],
  "timestamp": "2025-01-15T23:59:59Z"
}

Performance Monitoring Outcomes

  • 📊 METRICS_COLLECTED: Performance metrics successfully gathered
  • 📈 TRENDS_IDENTIFIED: Performance trends and patterns identified
  • 🎯 TARGETS_EVALUATED: Performance against targets assessed
  • ⚡ OPTIMIZATION_OPPORTUNITIES: Efficiency improvement opportunities identified
  • 🚨 PERFORMANCE_ALERTS: Performance issues or alerts generated
  • 📋 REPORTS_GENERATED: Performance reports successfully created
  • 🔄 CONTINUOUS_IMPROVEMENT: Improvement actions initiated

Implementation Requirements

// Target function: monitorStationPerformance
const monitorStationPerformance = async (requestData: RequestData, planState: PlanState): Promise<PartialOutcome> => {
  const stationId = requestData.station_id;
  const reportingPeriod = requestData.reporting_period;
  const performanceContext = requestData.performance_context;

  // Collect service completion and customer satisfaction metrics
  // Monitor asset utilization and equipment performance
  // Track operator performance and productivity
  // Calculate revenue generation and efficiency metrics
  // Generate performance reports and trend analysis
  // Identify optimization opportunities and performance alerts
  // Broadcast performance metrics via MQTT

  return {
    signals: ['METRICS_COLLECTED' | 'TRENDS_IDENTIFIED' | 'TARGETS_EVALUATED' | 'OPTIMIZATION_OPPORTUNITIES' | 'PERFORMANCE_ALERTS' | 'REPORTS_GENERATED' | 'CONTINUOUS_IMPROVEMENT'],
    metadata: {
      performance_data: {
        service_metrics: {
          total_services: 'number of services completed',
          average_service_time: 'mean service completion time',
          customer_satisfaction: 'customer satisfaction scores',
          service_success_rate: 'percentage of successful services'
        },
        asset_metrics: {
          battery_utilization: 'battery usage efficiency',
          charging_performance: 'charging system efficiency',
          equipment_uptime: 'equipment availability percentage',
          energy_consumption: 'total energy usage'
        },
        operator_metrics: {
          productivity_scores: 'individual operator productivity',
          service_quality: 'operator service quality ratings',
          safety_compliance: 'safety protocol adherence',
          customer_interaction: 'customer interaction quality'
        }
      },
      analytics_results: {
        trend_analysis: {
          performance_trends: 'identified performance trends',
          seasonal_patterns: 'seasonal demand and performance patterns',
          improvement_areas: 'areas showing improvement',
          decline_areas: 'areas showing performance decline'
        },
        benchmark_comparison: {
          target_performance: 'performance against set targets',
          network_comparison: 'performance vs other stations',
          industry_benchmarks: 'performance vs industry standards'
        },
        predictive_insights: {
          demand_forecast: 'predicted future demand',
          resource_requirements: 'anticipated resource needs',
          maintenance_scheduling: 'predicted maintenance requirements'
        }
      },
      optimization_recommendations: {
        efficiency_opportunities: 'identified efficiency improvements',
        resource_optimization: 'optimal resource allocation recommendations',
        process_improvements: 'suggested process enhancements',
        training_needs: 'operator training recommendations'
      },
      reporting_outputs: {
        mqtt_broadcast: {
          topic: `emit/abs/bss/station/${stationId}/performance_metrics`,
          payload: 'comprehensive performance metrics',
          frequency: 'daily, weekly, and monthly reporting'
        },
        dashboard_updates: 'operator dashboard performance updates',
        management_reports: 'summary reports for management review'
      }
    }
  };
};

OP6: Issue Resolution

Workflow: "Handle service issues and customer support"

Agent Function: resolveServiceIssues

OP6.1: Issue Detection and Classification

  1. Issue Identification: Detect service issues through multiple channels (customer reports, system alerts, operator observation)
  2. Issue Classification: Categorize issues by type, severity, and required resolution approach
  3. Impact Assessment: Evaluate issue impact on service delivery and customer experience
  4. Resource Requirement Analysis: Determine resources needed for issue resolution
  5. Escalation Decision: Decide whether issue requires escalation to supervisors or specialists

OP6.2: Resolution Process Management

  1. Immediate Response Actions: Take immediate actions to minimize service disruption
  2. Customer Communication: Keep customer informed of issue status and resolution progress
  3. Technical Resolution: Execute technical solutions or workarounds
  4. Quality Assurance: Verify issue resolution and service quality restoration
  5. Follow-up Actions: Conduct follow-up to ensure sustained resolution

OP6.3: Issue Tracking and Documentation

  1. Issue Documentation: Record detailed issue information and resolution steps
  2. Resolution Tracking: Track resolution progress and time to resolution
  3. Knowledge Base Updates: Update operational knowledge base with resolution procedures
  4. Prevention Analysis: Analyze issues for prevention opportunities
  5. Performance Impact Assessment: Evaluate issue impact on station performance

Issue Resolution Outcomes

  • 🔍 ISSUE_IDENTIFIED: Service issue successfully identified and classified
  • ⚡ IMMEDIATE_ACTION_TAKEN: Immediate response actions executed
  • 💬 CUSTOMER_INFORMED: Customer communication established and maintained
  • 🔧 TECHNICAL_RESOLUTION_APPLIED: Technical solution successfully implemented
  • 📞 ESCALATION_INITIATED: Issue escalated to appropriate specialist or supervisor
  • ✅ ISSUE_RESOLVED: Issue successfully resolved and service restored
  • 📚 KNOWLEDGE_UPDATED: Resolution procedure added to knowledge base

Implementation Requirements

// Target function: resolveServiceIssues
const resolveServiceIssues = async (requestData: RequestData, planState: PlanState): Promise<PartialOutcome> => {
  const issueDetails = requestData.issue_details;
  const operatorId = requestData.operator_id;
  const customerId = requestData.customer_id;

  // Identify and classify the service issue
  // Assess issue impact and resource requirements
  // Take immediate response actions
  // Communicate with customer about issue status
  // Execute technical resolution or escalate if needed
  // Document issue and resolution for knowledge base
  // Verify resolution and conduct follow-up

  return {
    signals: ['ISSUE_IDENTIFIED' | 'IMMEDIATE_ACTION_TAKEN' | 'CUSTOMER_INFORMED' | 'TECHNICAL_RESOLUTION_APPLIED' | 'ESCALATION_INITIATED' | 'ISSUE_RESOLVED' | 'KNOWLEDGE_UPDATED'],
    metadata: {
      issue_classification: {
        issue_type: 'technical|customer_service|equipment|safety|billing',
        severity_level: 'low|medium|high|critical',
        impact_scope: 'individual_customer|station_operations|network_wide',
        urgency_rating: 'routine|urgent|emergency'
      },
      resolution_process: {
        immediate_actions: 'actions taken to minimize disruption',
        technical_solutions: 'technical resolution steps',
        workarounds_applied: 'temporary solutions while permanent fix developed',
        escalation_details: 'escalation path and specialist involvement'
      },
      customer_communication: {
        communication_method: 'verbal|app_notification|SMS|email',
        status_updates_provided: 'frequency and content of customer updates',
        customer_satisfaction: 'customer satisfaction with issue resolution',
        compensation_offered: 'any service credits or compensation provided'
      },
      documentation: {
        issue_ticket_id: 'unique identifier for issue tracking',
        resolution_time: 'total time from identification to resolution',
        resolution_steps: 'detailed steps taken to resolve issue',
        knowledge_base_update: 'procedure added to operational knowledge base'
      },
      performance_impact: {
        service_interruption_time: 'duration of service interruption',
        customers_affected: 'number of customers impacted',
        revenue_impact: 'estimated revenue impact of issue',
        operational_efficiency_impact: 'impact on station efficiency metrics'
      },
      prevention_analysis: {
        root_cause_analysis: 'identified root cause of issue',
        prevention_recommendations: 'recommendations to prevent recurrence',
        process_improvements: 'suggested process improvements',
        training_needs: 'additional training needs identified'
      }
    }
  };
};

Integration Notes

MQTT Signal Integration

Following the established messaging convention for operator workflows:

// Operator Signal Patterns
const operatorTopics = {
  stationStatus: `emit/abs/bss/station/{station_id}/status_update`,
  intentAcknowledgment: `echo/abs/bss/service/{customer_id}/intent_acknowledged`,
  assetOperation: `emit/abs/bss/asset/{asset_type}/{asset_id}/operation_command`,
  performanceMetrics: `emit/abs/bss/station/{station_id}/performance_metrics`,
  issueAlert: `emit/abs/bss/station/{station_id}/issue_alert`
};

// Operator Subscription Patterns
const operatorSubscriptions = [
  'emit/abs/bss/service/+/intent_signal',      // Customer service intents
  'echo/abs/bss/fleet/+/allocation_completed', // Asset allocation completions
  'emit/abs/bss/station/+/status_request',     // Station status requests
  'meta/abs/bss/operator/+/shift_management'   // Operator shift management
];

Component Boundaries

Operator workflows respect DIRAC component separation:

// Operator Agent: Service coordination and customer interaction
interface OperatorAgentWorkflows {
  manageStationReadiness(requestData: RequestData, planState: PlanState): Promise<PartialOutcome>;
  monitorServiceIntents(requestData: RequestData, planState: PlanState): Promise<PartialOutcome>;
  coordinateCustomerService(requestData: RequestData, planState: PlanState): Promise<PartialOutcome>;
  manageAssetOperations(requestData: RequestData, planState: PlanState): Promise<PartialOutcome>;
  monitorStationPerformance(requestData: RequestData, planState: PlanState): Promise<PartialOutcome>;
  resolveServiceIssues(requestData: RequestData, planState: PlanState): Promise<PartialOutcome>;
}

// ARM: Asset management and location services
interface ARMOperatorServices {
  updateAssetStatus(assetUpdates: AssetUpdate[]): Promise<void>;
  getStationInventory(stationId: string): Promise<InventoryData>;
  coordinateAssetMovements(movements: AssetMovement[]): Promise<void>;
}

// UXI: Operator interface and tools
interface UXIOperatorServices {
  displayStationDashboard(metrics: StationMetrics): void;
  handleCustomerInteraction(interaction: CustomerInteraction): void;
  showPerformanceReports(reports: PerformanceReport[]): void;
}

Operator State Management

Operator workflows integrate with the FSM system:

// Operator State Transitions
const OperatorStateTransitions = {
  SHIFT_START: {
    from: 'off_duty',
    to: 'on_duty',
    triggers: ['manageStationReadiness']
  },
  SERVICE_ENGAGEMENT: {
    from: 'available',
    to: 'serving_customer',
    triggers: ['coordinateCustomerService']
  },
  ISSUE_HANDLING: {
    from: 'serving_customer',
    to: 'resolving_issue',
    triggers: ['resolveServiceIssues']
  }
};

Implementation Priority

Phase 1: Core Operator Functions (Immediate)

  1. OP3: coordinateCustomerService - Essential for customer interaction
  2. OP2: monitorServiceIntents - Required for service coordination
  3. OP6: resolveServiceIssues - Critical for service quality

Phase 2: Operational Management (Near-term)

  1. OP1: manageStationReadiness - Station operational status
  2. OP4: manageAssetOperations - Asset coordination and management

Phase 3: Advanced Analytics (Future)

  1. OP5: monitorStationPerformance - Performance analytics and optimization

Integration Dependencies

  1. Customer Workflows: Integration with rider and servicer workflows
  2. Asset Management: ARM coordination for asset operations
  3. Performance Analytics: Data collection and reporting systems
  4. Issue Management: Escalation and knowledge management systems

Expected Operator Signal Flow

🏪 Station readiness check ➡️ OP1: Status broadcast ➡️ ARM/UXI updates
                 ⬇️
📡 Customer intent received ➡️ OP2: Intent acknowledgment ➡️ Customer notification
                 ⬇️
👥 Customer arrives ➡️ OP3: Service coordination ➡️ Guided service delivery
                 ⬇️
🔋 Asset operations ➡️ OP4: Asset management ➡️ ARM state updates
                 ⬇️
📊 Performance tracking ➡️ OP5: Metrics collection ➡️ Analytics and reporting
                 ⬇️
🛠️ Issue detection ➡️ OP6: Issue resolution ➡️ Knowledge base updates

This operator workflow architecture ensures efficient service delivery while maintaining operational excellence and customer satisfaction.