{
  "feature": "driver-shift-management",
  "version": "1.0.0",
  "description": "Manage driver availability through online/offline status toggling, controlling whether a driver appears as available for order dispatch and location tracking.",
  "category": "workflow",
  "tags": [
    "driver",
    "shift",
    "availability",
    "online-offline",
    "dispatch-eligibility"
  ],
  "actors": [
    {
      "id": "driver",
      "name": "Driver",
      "type": "human",
      "description": "Sets their own availability status via the driver app."
    },
    {
      "id": "platform",
      "name": "Platform",
      "type": "system",
      "description": "Uses driver online status to determine dispatch eligibility."
    },
    {
      "id": "operator",
      "name": "Operator",
      "type": "human",
      "description": "Can view and manage driver availability from the operator console."
    }
  ],
  "fields": [
    {
      "name": "driver_id",
      "type": "text",
      "required": true,
      "label": "Identifier of the driver."
    },
    {
      "name": "online",
      "type": "boolean",
      "required": true,
      "label": "Whether the driver is currently available for orders."
    },
    {
      "name": "status",
      "type": "select",
      "required": false,
      "label": "Driver operational status.",
      "options": [
        {
          "value": "active",
          "label": "Active"
        },
        {
          "value": "inactive",
          "label": "Inactive"
        },
        {
          "value": "on_break",
          "label": "On Break"
        }
      ]
    },
    {
      "name": "current_job_id",
      "type": "text",
      "required": false,
      "label": "Reference to the active order if the driver is currently on a job."
    },
    {
      "name": "city",
      "type": "text",
      "required": false,
      "label": "City the driver is currently operating in (auto-resolved from location)."
    },
    {
      "name": "country",
      "type": "text",
      "required": false,
      "label": "Country the driver is currently in (auto-resolved from location)."
    }
  ],
  "states": {
    "field": "online",
    "values": [
      {
        "value": true,
        "description": "Driver is online and available to receive order pings.",
        "initial": false
      },
      {
        "value": false,
        "description": "Driver is offline and will not receive order dispatches.",
        "initial": true
      }
    ],
    "transitions": [
      {
        "from": false,
        "to": true,
        "actor": "driver",
        "description": "Driver goes online to start their shift."
      },
      {
        "from": true,
        "to": false,
        "actor": "driver",
        "description": "Driver goes offline to end their shift."
      }
    ]
  },
  "rules": {
    "rule_01": "Only drivers with online=true are eligible to receive adhoc order pings.",
    "rule_02": "A driver going offline while on an active order retains the current job until it is completed or reassigned.",
    "rule_03": "Driver online status is tracked as a boolean field on the driver record.",
    "rule_04": "The platform filters for online drivers when computing nearby available drivers for adhoc dispatch.",
    "rule_05": "A driver's city and country are automatically updated from reverse geocoding during location updates.",
    "rule_06": "Driver status (active, inactive, on_break) provides finer-grained availability beyond the online boolean."
  },
  "outcomes": {
    "driver_goes_online": {
      "priority": 1,
      "given": [
        "driver updates their status to online via the app"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "driver.online",
          "value": true
        }
      ],
      "result": "Driver appears as available in dispatch queries and begins receiving order pings."
    },
    "driver_goes_offline": {
      "priority": 2,
      "given": [
        "driver updates their status to offline via the app"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "driver.online",
          "value": false
        }
      ],
      "result": "Driver is no longer dispatched new orders and disappears from active driver lists."
    },
    "driver_available_for_dispatch": {
      "priority": 3,
      "given": [
        "platform queries for available drivers near a pickup location",
        "driver is online",
        "driver has no active current_job"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "response.eligible_drivers",
          "description": "Driver is included in the result set for dispatch consideration."
        }
      ],
      "result": "Driver is a candidate for order assignment or adhoc ping."
    },
    "driver_unavailable_for_dispatch": {
      "priority": 4,
      "given": [
        "driver is offline OR has an active current_job"
      ],
      "then": [],
      "result": "Driver is excluded from dispatch queries."
    }
  },
  "errors": [
    {
      "code": "DRIVER_NOT_FOUND",
      "status": 404,
      "message": "Driver not found."
    },
    {
      "code": "DRIVER_OFFLINE",
      "status": 400,
      "message": "This driver is currently offline."
    }
  ],
  "related": [
    {
      "feature": "driver-assignment-dispatch",
      "type": "required",
      "reason": "Dispatch eligibility depends on driver online status."
    },
    {
      "feature": "driver-location-streaming",
      "type": "recommended",
      "reason": "Location updates typically only flow when driver is online."
    },
    {
      "feature": "driver-app-flow",
      "type": "required",
      "reason": "Driver app controls the online/offline toggle."
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_driver_shift_management",
        "description": "Manage driver availability through online/offline status toggling, controlling whether a driver appears as available for order dispatch and location tracking.",
        "success_metrics": [
          {
            "metric": "processing_time",
            "target": "< 5s",
            "measurement": "Time from request to completion"
          },
          {
            "metric": "success_rate",
            "target": ">= 99%",
            "measurement": "Successful operations divided by total attempts"
          }
        ],
        "constraints": [
          {
            "type": "performance",
            "description": "Must not block dependent workflows",
            "negotiable": true
          }
        ]
      }
    ],
    "autonomy": {
      "level": "semi_autonomous",
      "human_checkpoints": [
        "before transitioning to a terminal state"
      ],
      "escalation_triggers": [
        "error_rate > 5"
      ]
    },
    "safety": {
      "action_permissions": [
        {
          "action": "driver_goes_online",
          "permission": "autonomous"
        },
        {
          "action": "driver_goes_offline",
          "permission": "autonomous"
        },
        {
          "action": "driver_available_for_dispatch",
          "permission": "autonomous"
        },
        {
          "action": "driver_unavailable_for_dispatch",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "reliability",
        "over": "speed",
        "reason": "workflow steps must complete correctly before proceeding"
      }
    ],
    "coordination": {
      "protocol": "orchestrated",
      "consumes": [
        {
          "capability": "driver_assignment_dispatch",
          "from": "driver-assignment-dispatch",
          "fallback": "degrade"
        },
        {
          "capability": "driver_app_flow",
          "from": "driver-app-flow",
          "fallback": "degrade"
        }
      ]
    }
  },
  "extensions": {
    "source": {
      "repo": "https://github.com/fleetbase/fleetbase",
      "project": "Fleetbase",
      "tech_stack": "PHP / Laravel",
      "files_traced": 3,
      "entry_points": [
        "src/Models/Driver.php",
        "src/Http/Controllers/Api/v1/DriverController.php",
        "migrations/2023_04_27_053456_create_drivers_table.php"
      ]
    }
  }
}