{
  "feature": "maintenance-reminders",
  "version": "1.0.0",
  "description": "Define maintenance tasks that trigger notifications when a tracked vehicle crosses a configured odometer, engine hours, or time threshold, with automatic repeat reminders at regular intervals for o...",
  "category": "workflow",
  "tags": [
    "gps",
    "tracking",
    "maintenance",
    "odometer",
    "service",
    "reminder",
    "fleet"
  ],
  "actors": [
    {
      "id": "fleet_admin",
      "name": "Fleet Administrator",
      "type": "human",
      "description": "Creates and manages maintenance task definitions per device or group"
    },
    {
      "id": "pipeline",
      "name": "Maintenance Event Handler",
      "type": "system",
      "description": "Evaluates each incoming position against all active maintenance definitions for the device"
    },
    {
      "id": "mechanic",
      "name": "Maintenance Team",
      "type": "human",
      "description": "Receives maintenance reminders and records service completion"
    }
  ],
  "fields": [
    {
      "name": "name",
      "type": "text",
      "required": true,
      "label": "Name of the maintenance task (e.g. Oil change, Tyre rotation, Annual inspection)"
    },
    {
      "name": "tracking_type",
      "type": "select",
      "required": true,
      "label": "The metric to track: odometer (metres), hours (milliseconds), or a time field (server_time, devic..."
    },
    {
      "name": "start_value",
      "type": "number",
      "required": true,
      "label": "The tracking metric value at which the first reminder fires"
    },
    {
      "name": "period_value",
      "type": "number",
      "required": false,
      "label": "Interval at which the reminder repeats after the initial trigger; zero means fire once only"
    },
    {
      "name": "device_id",
      "type": "hidden",
      "required": false,
      "label": "Device this maintenance task applies to (or inherited from group)"
    }
  ],
  "rules": {
    "rule_1": "The first reminder fires when the tracking metric crosses start_value (previous value < start_value <= current value)",
    "rule_2": "If period_value > 0, subsequent reminders fire each time the metric increases by another period_value interval beyond start_value",
    "rule_3": "Interval boundary crossing is detected mathematically; if a large GPS gap causes multiple intervals to be skipped, a reminder fires for the current crossing only",
    "rule_4": "Maintenance definitions can be assigned to individual devices, to groups (inherited by all devices in the group), or to a user account",
    "rule_5": "Only the latest position for each device is evaluated; outdated positions do not trigger maintenance reminders",
    "rule_6": "A reminder event stores the maintenance task ID and the current tracking value so the service record can be annotated with the relevant mileage or hours"
  },
  "outcomes": {
    "initial_reminder_fired": {
      "priority": 10,
      "given": [
        "previous tracking value < start_value",
        "current tracking value >= start_value",
        "position is the latest for the device"
      ],
      "then": [
        {
          "action": "create_record",
          "target": "event",
          "description": "Maintenance reminder event recorded with type = maintenance, maintenance_id, current tracking value",
          "type": "event"
        },
        {
          "action": "emit_event",
          "event": "maintenance.due",
          "payload": [
            "device_id",
            "maintenance_id",
            "maintenance_name",
            "tracking_type",
            "current_value",
            "start_value"
          ]
        }
      ],
      "result": "Maintenance reminder event stored; notification dispatched to assigned users"
    },
    "periodic_reminder_fired": {
      "priority": 8,
      "given": [
        "current tracking value has crossed a period boundary beyond start_value",
        "period_value > 0",
        "position is the latest for the device"
      ],
      "then": [
        {
          "action": "create_record",
          "target": "event",
          "description": "Repeat maintenance reminder event recorded",
          "type": "event"
        },
        {
          "action": "emit_event",
          "event": "maintenance.due",
          "payload": [
            "device_id",
            "maintenance_id",
            "maintenance_name",
            "tracking_type",
            "current_value",
            "period_boundary"
          ]
        }
      ],
      "result": "Repeat reminder fired; next service interval boundary has been reached"
    },
    "no_threshold_crossed": {
      "priority": 3,
      "given": [
        "current tracking value has not crossed any maintenance boundary"
      ],
      "then": [],
      "result": "No reminder generated; maintenance is not yet due"
    }
  },
  "errors": [
    {
      "code": "MAINTENANCE_DEVICE_NOT_FOUND",
      "message": "The device referenced does not exist",
      "status": 404
    },
    {
      "code": "MAINTENANCE_NOT_FOUND",
      "message": "The specified maintenance definition does not exist",
      "status": 404
    }
  ],
  "events": [
    {
      "name": "maintenance.due",
      "description": "A maintenance threshold has been reached for a tracked vehicle",
      "payload": [
        "device_id",
        "maintenance_id",
        "maintenance_name",
        "tracking_type",
        "current_value",
        "threshold_value"
      ]
    }
  ],
  "related": [
    {
      "feature": "odometer-tracking",
      "type": "required",
      "reason": "Odometer values are the primary trigger metric for distance-based maintenance"
    },
    {
      "feature": "engine-hours-tracking",
      "type": "recommended",
      "reason": "Engine hours provide an alternative maintenance trigger for equipment tracked by running time"
    },
    {
      "feature": "gps-position-ingestion",
      "type": "required",
      "reason": "Each position update drives the maintenance threshold evaluation"
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_maintenance_reminders",
        "description": "Define maintenance tasks that trigger notifications when a tracked vehicle crosses a configured odometer, engine hours, or time threshold, with automatic repeat reminders at regular intervals for o...",
        "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 making irreversible changes"
      ],
      "escalation_triggers": [
        "error_rate > 5"
      ]
    },
    "safety": {
      "action_permissions": [
        {
          "action": "initial_reminder_fired",
          "permission": "autonomous"
        },
        {
          "action": "periodic_reminder_fired",
          "permission": "autonomous"
        },
        {
          "action": "no_threshold_crossed",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "reliability",
        "over": "speed",
        "reason": "workflow steps must complete correctly before proceeding"
      }
    ],
    "coordination": {
      "protocol": "orchestrated",
      "consumes": [
        {
          "capability": "odometer_tracking",
          "from": "odometer-tracking",
          "fallback": "degrade"
        },
        {
          "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/model/Maintenance.java",
        "src/main/java/org/traccar/handler/events/MaintenanceEventHandler.java"
      ]
    }
  }
}