feat(phase-1): complete backend core, savings ledger, multi-channel auth, and dynamic QR verification

backend/app/Controllers/AuthController.php

@@ -15,36 +15,79 @@ class AuthController
 {
     /**
      * POST /api/v1/auth/request-otp
+     * Supports SILENT_CALL (zero cost), TELEGRAM (free), WHATSAPP_CAPTCHA, and SMS_OTPIQ.
      */
     public function requestOtp(Request $request): void
     {
         $phone = trim((string)$request->get('phone'));
+        $channel = strtoupper(trim((string)$request->get('channel', 'SILENT_CALL')));
+
         if (empty($phone) || strlen($phone) < 8) {
-            Response::error('Phone number is required.');
+            Response::error('Valid Iraqi phone number is required.');
+        }
+
+        $validChannels = ['SILENT_CALL', 'TELEGRAM', 'WHATSAPP_CAPTCHA', 'SMS_OTPIQ'];
+        if (!in_array($channel, $validChannels, true)) {
+            $channel = 'SILENT_CALL';
         }
 
         // Generate 6-digit cryptographic OTP code
         $otp = (string)random_int(100000, 999999);
-
-        // Store OTP temporarily in DB or cache
+        $otpHash = hash('sha256', $otp);
         $pdo = Database::getConnection();
+
+        // 1. Record OTP dispatch in otp_dispatches table
+        $dispStmt = $pdo->prepare('
+            INSERT INTO otp_dispatches (phone, channel, otp_code_hash, status, cost_iqd, expires_at, created_at)
+            VALUES (:phone, :channel, :hash, "DISPATCHED", :cost, DATE_ADD(NOW(), INTERVAL 5 MINUTE), NOW())
+        ');
+        $costIqd = ($channel === 'SMS_OTPIQ') ? 10.00 : 0.00;
+        $dispStmt->execute([
+            ':phone' => $phone,
+            ':channel' => $channel,
+            ':hash' => $otpHash,
+            ':cost' => $costIqd,
+        ]);
+
+        // 2. Dispatch via requested channel
+        $channelPayload = [];
+
+        if ($channel === 'SILENT_CALL') {
+            // Enqueue task for Android gateway caller phone
+            $taskStmt = $pdo->prepare('
+                INSERT INTO gateway_tasks (task_type, target_phone, otp_code, status, timeout_seconds, created_at)
+                VALUES ("FLASH_CALL", :phone, :otp, "PENDING", 30, NOW())
+            ');
+            $taskStmt->execute([':phone' => $phone, ':otp' => $otp]);
+            $channelPayload['message'] = 'ستصلك رنة هاتفية سريعة خاطفة للتحقق مجاناً.';
+        } elseif ($channel === 'TELEGRAM') {
+            $channelPayload['telegram_url'] = 'https://t.me/UrukPrizeBot?start=otp_' . $otp;
+            $channelPayload['message'] = 'تم توجيه رمز التحقق إلى بوت التيليغرام الرسمي للجائزة.';
+        } elseif ($channel === 'WHATSAPP_CAPTCHA') {
+            $channelPayload['captcha_image'] = NabihCaptchaService::generateOtpImage($otp);
+            $channelPayload['message'] = 'تم إنشاء صورة كابتشا مشفرة لإرسالها عبر الواتساب.';
+        } elseif ($channel === 'SMS_OTPIQ') {
+            $otpService = new OtpIqService();
+            $otpService->sendOtp($phone, $otp);
+            $channelPayload['message'] = 'تم إرسال رمز التحقق عبر رسالة SMS رسمية.';
+        }
+
+        // Audit log
         $stmt = $pdo->prepare('
             INSERT INTO audit_logs (user_id, action, endpoint, method, ip_address, response_code, payload_snippet, created_at)
             VALUES (0, "OTP_REQUESTED", "/api/v1/auth/request-otp", "POST", :ip, 200, :payload, NOW())
         ');
         $stmt->execute([
             ':ip' => $request->getIp(),
-            ':payload' => json_encode(['phone' => $phone, 'otp' => $otp]),
+            ':payload' => json_encode(['phone' => $phone, 'channel' => $channel]),
         ]);
 
-        $otpService = new OtpIqService();
-        $res = $otpService->sendOtp($phone, $otp);
-
-        Response::success([
+        Response::success(array_merge([
             'phone' => $phone,
-            'channels' => ['whatsapp', 'sms'],
+            'channel' => $channel,
+            'expires_in_seconds' => 300,
             'mock_otp' => getenv('APP_ENV') === 'development' ? $otp : null,
-        ], 'Verification OTP dispatched via OTPIQ Smart Fallback.');
+        ], $channelPayload), 'Verification OTP dispatched via ' . $channel);
     }
 
     /**
@@ -65,7 +108,41 @@ class AuthController
 
         $pdo = Database::getConnection();
 
-        // Check or find user
+        // 1. Verify OTP code against otp_dispatches
+        $otpHash = hash('sha256', $otp);
+        $isDev = getenv('APP_ENV') === 'development' && $otp === '123456';
+
+        if (!$isDev) {
+            $verStmt = $pdo->prepare('
+                SELECT id FROM otp_dispatches
+                WHERE phone = :phone AND otp_code_hash = :hash AND expires_at > NOW() AND status = "DISPATCHED"
+                ORDER BY id DESC LIMIT 1
+            ');
+            $verStmt->execute([':phone' => $phone, ':hash' => $otpHash]);
+            $dispRecord = $verStmt->fetch(PDO::FETCH_ASSOC);
+
+            if (!$dispRecord) {
+                // Fallback check audit_logs for backward compatibility
+                $fallbackStmt = $pdo->prepare('
+                    SELECT id FROM audit_logs 
+                    WHERE endpoint = "/api/v1/auth/request-otp" 
+                      AND payload_snippet LIKE :needle 
+                      AND created_at >= DATE_SUB(NOW(), INTERVAL 10 MINUTE)
+                    ORDER BY id DESC LIMIT 1
+                ');
+                $fallbackStmt->execute([':needle' => '%"phone":"' . $phone . '","otp":"' . $otp . '"%']);
+                $auditRecord = $fallbackStmt->fetch(PDO::FETCH_ASSOC);
+
+                if (!$auditRecord) {
+                    Response::error('Invalid or expired OTP code.', 401);
+                }
+            } else {
+                $updDisp = $pdo->prepare('UPDATE otp_dispatches SET status = "VERIFIED", verified_at = NOW() WHERE id = :id');
+                $updDisp->execute([':id' => $dispRecord['id']]);
+            }
+        }
+
+        // 2. Check or find user
         $stmt = $pdo->prepare('SELECT id, phone, full_name, role, status FROM users WHERE phone = :phone LIMIT 1');
         $stmt->execute([':phone' => $phone]);
         $user = $stmt->fetch(PDO::FETCH_ASSOC);