{
  "feature": "fuel-level-reporting",
  "version": "1.0.0",
  "description": "Read fuel sensor data transmitted by GPS hardware, detect significant fuel drops (theft or fast consumption) and unexpected increases (refuelling), and provide fuel consumption summaries across tri...",
  "category": "data",
  "tags": [
    "gps",
    "tracking",
    "fuel",
    "fleet",
    "sensor",
    "alert",
    "consumption"
  ],
  "actors": [
    {
      "id": "device",
      "name": "GPS Device",
      "type": "external",
      "description": "Reads fuel sensor and includes fuel level in position transmissions"
    },
    {
      "id": "pipeline",
      "name": "Position Processing Pipeline",
      "type": "system",
      "description": "Compares fuel levels between consecutive positions to detect threshold crossings"
    },
    {
      "id": "fleet_manager",
      "name": "Fleet Manager",
      "type": "human",
      "description": "Monitors fuel levels, reviews consumption reports, and investigates anomalous drops"
    }
  ],
  "fields": [
    {
      "name": "fuel_level",
      "type": "number",
      "required": false,
      "label": "Current fuel level as a percentage (0–100%) from the sensor"
    },
    {
      "name": "fuel_volume",
      "type": "number",
      "required": false,
      "label": "Current fuel volume in litres (device-specific unit)"
    },
    {
      "name": "fuel_used",
      "type": "number",
      "required": false,
      "label": "Cumulative fuel consumed since device reset or reference point"
    },
    {
      "name": "fuel_consumption_rate",
      "type": "number",
      "required": false,
      "label": "Instantaneous fuel consumption rate (litres per hour or per 100 km depending on device)"
    },
    {
      "name": "fuel_drop_threshold",
      "type": "number",
      "required": false,
      "label": "Minimum decrease in fuel level/volume that triggers a fuel drop event"
    },
    {
      "name": "fuel_increase_threshold",
      "type": "number",
      "required": false,
      "label": "Minimum increase in fuel level/volume that triggers a fuel increase (refuel) event"
    }
  ],
  "rules": {
    "rule_1": "Fuel data is read from position attributes; the specific attribute key and unit depend on the device and protocol",
    "rule_2": "A fuel drop event is generated when the fuel level decreases by more than fuel_drop_threshold between consecutive positions",
    "rule_3": "A fuel increase event is generated when the fuel level increases by more than fuel_increase_threshold between consecutive positions (indicating a refuel)",
    "rule_4": "Only latest positions are evaluated for threshold crossings; outdated positions are skipped",
    "rule_5": "Fuel consumption is calculated per trip and per summary period using the difference between start and end fuel values",
    "rule_6": "If the device does not report a fuel sensor, the feature is inactive and no fuel events are generated",
    "rule_7": "Both percentage-based and volume-based fuel attributes are supported; the platform uses whichever the device provides"
  },
  "outcomes": {
    "fuel_drop_detected": {
      "priority": 10,
      "given": [
        "current fuel value is lower than previous fuel value by >= fuel_drop_threshold",
        "position is the latest for the device"
      ],
      "then": [
        {
          "action": "create_record",
          "target": "event",
          "description": "Fuel drop event recorded with type = device_fuel_drop, previous and current values",
          "type": "event"
        },
        {
          "action": "emit_event",
          "event": "fuel.dropped",
          "payload": [
            "device_id",
            "previous_fuel",
            "current_fuel",
            "delta",
            "position_id",
            "fix_time"
          ]
        }
      ],
      "result": "Fuel drop event stored; possible theft or leak investigation can be triggered"
    },
    "fuel_increase_detected": {
      "priority": 10,
      "given": [
        "current fuel value is higher than previous fuel value by >= fuel_increase_threshold",
        "position is the latest for the device"
      ],
      "then": [
        {
          "action": "create_record",
          "target": "event",
          "description": "Fuel increase event recorded with type = device_fuel_increase, previous and current values",
          "type": "event"
        },
        {
          "action": "emit_event",
          "event": "fuel.increased",
          "payload": [
            "device_id",
            "previous_fuel",
            "current_fuel",
            "delta",
            "position_id",
            "fix_time"
          ]
        }
      ],
      "result": "Fuel increase event stored; refuelling noted for cost tracking"
    },
    "no_fuel_sensor": {
      "priority": 3,
      "given": [
        "position does not include any fuel attribute"
      ],
      "then": [],
      "result": "Fuel events skipped for this position; no fuel data is available from this device"
    }
  },
  "errors": [
    {
      "code": "FUEL_DEVICE_NOT_FOUND",
      "message": "The device referenced does not exist",
      "status": 404
    }
  ],
  "events": [
    {
      "name": "fuel.dropped",
      "description": "Fuel level fell by more than the configured threshold — possible theft, leak, or high consumption",
      "payload": [
        "device_id",
        "previous_fuel",
        "current_fuel",
        "delta",
        "position_id",
        "fix_time"
      ]
    },
    {
      "name": "fuel.increased",
      "description": "Fuel level rose by more than the configured threshold — refuelling detected",
      "payload": [
        "device_id",
        "previous_fuel",
        "current_fuel",
        "delta",
        "position_id",
        "fix_time"
      ]
    }
  ],
  "related": [
    {
      "feature": "gps-position-ingestion",
      "type": "required",
      "reason": "Fuel values arrive as position attributes from device transmissions"
    },
    {
      "feature": "trip-detection",
      "type": "recommended",
      "reason": "Trip reports include fuel consumption from start to end of each trip"
    },
    {
      "feature": "fleet-scheduled-reports",
      "type": "recommended",
      "reason": "Fuel summary reports aggregate consumption over configurable periods"
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_fuel_level_reporting",
        "description": "Read fuel sensor data transmitted by GPS hardware, detect significant fuel drops (theft or fast consumption) and unexpected increases (refuelling), and provide fuel consumption summaries across tri...",
        "success_metrics": [
          {
            "metric": "data_accuracy",
            "target": "100%",
            "measurement": "Records matching source of truth"
          },
          {
            "metric": "duplicate_rate",
            "target": "0%",
            "measurement": "Duplicate records detected post-creation"
          }
        ],
        "constraints": [
          {
            "type": "performance",
            "description": "Data consistency must be maintained across concurrent operations",
            "negotiable": false
          }
        ]
      }
    ],
    "autonomy": {
      "level": "supervised",
      "human_checkpoints": [
        "before making irreversible changes"
      ],
      "escalation_triggers": [
        "error_rate > 5"
      ]
    },
    "safety": {
      "action_permissions": [
        {
          "action": "fuel_drop_detected",
          "permission": "autonomous"
        },
        {
          "action": "fuel_increase_detected",
          "permission": "autonomous"
        },
        {
          "action": "no_fuel_sensor",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "data_integrity",
        "over": "performance",
        "reason": "data consistency must be maintained across all operations"
      }
    ],
    "coordination": {
      "protocol": "orchestrated",
      "consumes": [
        {
          "capability": "gps_position_ingestion",
          "from": "gps-position-ingestion",
          "fallback": "degrade"
        }
      ]
    }
  },
  "extensions": {
    "source": {
      "repo": "https://github.com/traccar/traccar",
      "project": "Traccar GPS Tracking Server",
      "tech_stack": "Java 17, Netty",
      "files_traced": 4,
      "entry_points": [
        "src/main/java/org/traccar/handler/events/FuelEventHandler.java",
        "src/main/java/org/traccar/model/Position.java"
      ]
    }
  }
}