From 0868b04298015b25410ba7045f1c5382fd81f413 Mon Sep 17 00:00:00 2001
From: Sam Rolfe <samuelrolfe@gmail.com>
Date: Tue, 2 Sep 2025 18:29:27 +1000
Subject: [PATCH] IMEI device API: telemetry, commands, receipts + migrations
 and routing

---
 app/Models/Command.php                        | 21 +++++++++++++
 app/Models/CommandReceipt.php                 | 17 ++++++++++
 app/Models/Device.php                         | 18 +++++++++++
 ...2025_08_29_000001_create_devices_table.php | 28 +++++++++++++++++
 ...8_29_000002_create_device_status_table.php | 29 +++++++++++++++++
 ...9_000003_create_device_telemetry_table.php | 31 +++++++++++++++++++
 ...8_29_000004_create_command_queue_table.php | 30 ++++++++++++++++++
 ...9_000005_create_command_receipts_table.php | 29 +++++++++++++++++
 routes/api.php                                |  1 +
 9 files changed, 204 insertions(+)
 create mode 100644 app/Models/Command.php
 create mode 100644 app/Models/CommandReceipt.php
 create mode 100644 app/Models/Device.php
 create mode 100644 database/migrations/2025_08_29_000001_create_devices_table.php
 create mode 100644 database/migrations/2025_08_29_000002_create_device_status_table.php
 create mode 100644 database/migrations/2025_08_29_000003_create_device_telemetry_table.php
 create mode 100644 database/migrations/2025_08_29_000004_create_command_queue_table.php
 create mode 100644 database/migrations/2025_08_29_000005_create_command_receipts_table.php

diff --git a/app/Models/Command.php b/app/Models/Command.php
new file mode 100644
index 0000000..05dfcea
--- /dev/null
+++ b/app/Models/Command.php
@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+
+class Command extends Model
+{
+    protected $table = 'command_queue';
+
+    protected $fillable = [
+        'device_id','command_type','payload','priority','status',
+        'not_before_at','expires_at','created_by_user_id',
+    ];
+
+    protected $casts = [
+        'payload' => 'array',
+        'not_before_at' => 'datetime',
+        'expires_at' => 'datetime',
+    ];
+}
diff --git a/app/Models/CommandReceipt.php b/app/Models/CommandReceipt.php
new file mode 100644
index 0000000..a995014
--- /dev/null
+++ b/app/Models/CommandReceipt.php
@@ -0,0 +1,17 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+
+class CommandReceipt extends Model
+{
+    protected $fillable = [
+        'command_id','device_id','acked_at','executed_at','result','result_detail',
+    ];
+
+    protected $casts = [
+        'acked_at' => 'datetime',
+        'executed_at' => 'datetime',
+    ];
+}
diff --git a/app/Models/Device.php b/app/Models/Device.php
new file mode 100644
index 0000000..6df8f74
--- /dev/null
+++ b/app/Models/Device.php
@@ -0,0 +1,18 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+
+class Device extends Model
+{
+    protected $fillable = [
+        'user_id','name','imei','is_active','last_seen_at','last_ip',
+        'firmware_version','hardware_version',
+    ];
+
+    protected $casts = [
+        'is_active' => 'boolean',
+        'last_seen_at' => 'datetime',
+    ];
+}
diff --git a/database/migrations/2025_08_29_000001_create_devices_table.php b/database/migrations/2025_08_29_000001_create_devices_table.php
new file mode 100644
index 0000000..599426b
--- /dev/null
+++ b/database/migrations/2025_08_29_000001_create_devices_table.php
@@ -0,0 +1,28 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up(): void
+    {
+        Schema::create('devices', function (Blueprint $table) {
+            $table->id();
+            $table->unsignedBigInteger('user_id')->nullable()->index();
+            $table->string('name')->nullable();
+            $table->string('imei', 32)->unique();
+            $table->boolean('is_active')->default(true);
+            $table->timestamp('last_seen_at')->nullable()->index();
+            $table->string('last_ip')->nullable();
+            $table->string('firmware_version')->nullable();
+            $table->string('hardware_version')->nullable();
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('devices');
+    }
+};
diff --git a/database/migrations/2025_08_29_000002_create_device_status_table.php b/database/migrations/2025_08_29_000002_create_device_status_table.php
new file mode 100644
index 0000000..22bb4fb
--- /dev/null
+++ b/database/migrations/2025_08_29_000002_create_device_status_table.php
@@ -0,0 +1,29 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up(): void
+    {
+        Schema::create('device_status', function (Blueprint $table) {
+            $table->id();
+            $table->unsignedBigInteger('device_id')->unique();
+            $table->boolean('is_car_on')->default(false);
+            $table->unsignedTinyInteger('battery_percent')->nullable();
+            $table->boolean('external_power')->default(false);
+            $table->unsignedInteger('sleep_interval_sec')->default(60);
+            $table->timestamp('last_gps_fix_at')->nullable();
+            $table->timestamp('reported_at')->nullable()->index();
+            $table->timestamps();
+
+            $table->foreign('device_id')->references('id')->on('devices')->onDelete('cascade');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('device_status');
+    }
+};
diff --git a/database/migrations/2025_08_29_000003_create_device_telemetry_table.php b/database/migrations/2025_08_29_000003_create_device_telemetry_table.php
new file mode 100644
index 0000000..22efd2f
--- /dev/null
+++ b/database/migrations/2025_08_29_000003_create_device_telemetry_table.php
@@ -0,0 +1,31 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up(): void
+    {
+        Schema::create('device_telemetry', function (Blueprint $table) {
+            $table->id();
+            $table->unsignedBigInteger('device_id')->index();
+            $table->timestamp('recorded_at')->index();
+            $table->decimal('lat', 10, 7);
+            $table->decimal('lng', 10, 7);
+            $table->decimal('altitude_m', 8, 2)->nullable();
+            $table->decimal('speed_kmh', 6, 2)->nullable();
+            $table->decimal('heading_deg', 6, 2)->nullable();
+            $table->decimal('accuracy_m', 8, 2)->nullable();
+            $table->json('raw')->nullable();
+            $table->timestamp('created_at')->useCurrent();
+
+            $table->foreign('device_id')->references('id')->on('devices')->onDelete('cascade');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('device_telemetry');
+    }
+};
diff --git a/database/migrations/2025_08_29_000004_create_command_queue_table.php b/database/migrations/2025_08_29_000004_create_command_queue_table.php
new file mode 100644
index 0000000..222cb8d
--- /dev/null
+++ b/database/migrations/2025_08_29_000004_create_command_queue_table.php
@@ -0,0 +1,30 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up(): void
+    {
+        Schema::create('command_queue', function (Blueprint $table) {
+            $table->id();
+            $table->unsignedBigInteger('device_id')->index();
+            $table->string('command_type', 64);
+            $table->json('payload')->nullable();
+            $table->unsignedTinyInteger('priority')->default(5);
+            $table->enum('status', ['queued','sent','acked','failed','expired'])->default('queued')->index();
+            $table->timestamp('not_before_at')->nullable()->index();
+            $table->timestamp('expires_at')->nullable()->index();
+            $table->unsignedBigInteger('created_by_user_id')->nullable();
+            $table->timestamps();
+
+            $table->foreign('device_id')->references('id')->on('devices')->onDelete('cascade');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('command_queue');
+    }
+};
diff --git a/database/migrations/2025_08_29_000005_create_command_receipts_table.php b/database/migrations/2025_08_29_000005_create_command_receipts_table.php
new file mode 100644
index 0000000..1e1fb15
--- /dev/null
+++ b/database/migrations/2025_08_29_000005_create_command_receipts_table.php
@@ -0,0 +1,29 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up(): void
+    {
+        Schema::create('command_receipts', function (Blueprint $table) {
+            $table->id();
+            $table->unsignedBigInteger('command_id')->index();
+            $table->unsignedBigInteger('device_id')->index();
+            $table->timestamp('acked_at')->nullable();
+            $table->timestamp('executed_at')->nullable();
+            $table->enum('result', ['ok','error'])->nullable();
+            $table->text('result_detail')->nullable();
+            $table->timestamps();
+
+            $table->foreign('command_id')->references('id')->on('command_queue')->onDelete('cascade');
+            $table->foreign('device_id')->references('id')->on('devices')->onDelete('cascade');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('command_receipts');
+    }
+};
diff --git a/routes/api.php b/routes/api.php
index f49ab9c..3d4f74e 100644
--- a/routes/api.php
+++ b/routes/api.php
@@ -2,6 +2,7 @@
 
 use Illuminate\Support\Facades\Route;
 use App\Http\Controllers\GpsController;
+use App\Http\Controllers\DeviceApiController;
 
 Route::get('/health', fn () => response()->json(['ok' => true]));