feat: complete jobcard client management foundation

app/Domain/Notification/NotificationQueue.php

@@ -0,0 +1,36 @@
+<?php
+declare(strict_types=1);
+
+namespace App\Domain\Notification;
+
+use PDO;
+use InvalidArgumentException;
+
+/** Persists validated notifications as per-user rows with database-backed deduplication. */
+final class NotificationQueue
+{
+    public function __construct(private readonly ?NotificationRecord $records = null)
+    {
+    }
+
+    /** @return list<int> inserted notification ids */
+    public function enqueue(PDO $pdo, array $record): array
+    {
+        $validation = ($this->records ?? new NotificationRecord())->validate($record);
+        if (!$validation['valid']) throw new InvalidArgumentException('Invalid notification: ' . implode(' ', $validation['errors']));
+        $title = is_scalar($record['title'] ?? null) ? trim((string)$record['title']) : '';
+        $body = is_scalar($record['body'] ?? null) ? trim((string)$record['body']) : '';
+        if ($title === '' || mb_strlen($title) > 190) throw new InvalidArgumentException('Notification title is required and must be 190 characters or fewer.');
+        $lookup = $pdo->prepare('SELECT id FROM users WHERE email = :email AND is_active = 1 LIMIT 1');
+        $insert = $pdo->prepare('INSERT INTO notifications (user_id, type, title, body, deduplication_key, read_at) VALUES (:user, :type, :title, :body, :dedup, :read_at) ON DUPLICATE KEY UPDATE id = LAST_INSERT_ID(id)');
+        $ids = [];
+        foreach ($validation['recipients'] as $email) {
+            $lookup->execute(['email' => $email]);
+            $userId = $lookup->fetchColumn();
+            if ($userId === false) continue;
+            $insert->execute(['user' => $userId, 'type' => $validation['type'], 'title' => $title, 'body' => $body === '' ? null : $body, 'dedup' => $validation['deduplication_key'], 'read_at' => $validation['is_read'] ? date('Y-m-d H:i:s') : null]);
+            $ids[] = (int)$pdo->lastInsertId();
+        }
+        return $ids;
+    }
+}