Update: 2026-05-06 01:38:39

2026-05-06 01:38:39 +03:00
parent c63d9944ee
commit 97ff911751
13 changed files with 2170 additions and 0 deletions
--- a/app/modules_app/auth/mobile_request_otp.php
+++ b/app/modules_app/auth/mobile_request_otp.php
@@ -0,0 +1,137 @@
+<?php
+/**
+ * Mobile OTP Request Endpoint
+ * POST /v1/auth/mobile/request-otp
+ * 
+ * Sends an OTP to the user's registered phone number.
+ * The phone must already be registered by an admin in the web dashboard.
+ */
+
+declare(strict_types=1);
+
+use App\Core\Database;
+use App\Core\Validator;
+use App\Core\Security;
+use App\Middleware\RateLimitMiddleware;
+
+// Rate limit: 3 OTP requests per minute per IP
+RateLimitMiddleware::check(3, 60);
+
+$data = Security::sanitize(input());
+
+// 1. Validate
+$errors = Validator::validate($data, [
+    'phone' => 'required',
+]);
+
+if ($errors) {
+    json_error('رقم الهاتف مطلوب', 422, $errors);
+}
+
+$phone = preg_replace('/[^0-9+]/', '', $data['phone']);
+$phoneHash = hash('sha256', $phone);
+
+// 2. Find user by phone hash
+$db = Database::getInstance();
+$stmt = $db->prepare("SELECT id, tenant_id, name, is_active FROM users WHERE phone_hash = ? LIMIT 1");
+$stmt->execute([$phoneHash]);
+$user = $stmt->fetch();
+
+if (!$user) {
+    // Don't reveal if phone exists — generic message
+    json_success(null, 'إذا كان الرقم مسجلاً، سيتم إرسال رمز التحقق');
+    exit;
+}
+
+if (!$user['is_active']) {
+    json_error('الحساب معطّل. تواصل مع المسؤول.', 403);
+}
+
+// 3. Generate OTP (6 digits)
+$otp = str_pad((string)random_int(100000, 999999), 6, '0', STR_PAD_LEFT);
+$otpHash = password_hash($otp, PASSWORD_DEFAULT);
+$expiresAt = date('Y-m-d H:i:s', time() + 300); // 5 minutes
+
+// 4. Store OTP in database (or Redis if available)
+// Using a simple approach: store in a cache file per phone
+$cacheDir = STORAGE_PATH . '/cache/otp';
+if (!is_dir($cacheDir)) {
+    mkdir($cacheDir, 0755, true);
+}
+
+$otpData = [
+    'hash' => $otpHash,
+    'user_id' => $user['id'],
+    'attempts' => 0,
+    'max_attempts' => 5,
+    'expires_at' => time() + 300,
+    'created_at' => time(),
+];
+
+$fp = fopen($cacheDir . '/otp_' . $phoneHash . '.json', 'w');
+if ($fp) {
+    flock($fp, LOCK_EX);
+    fwrite($fp, json_encode($otpData));
+    flock($fp, LOCK_UN);
+    fclose($fp);
+}
+
+// 5. Send OTP via SMS
+// TODO: Replace with your actual SMS provider
+$smsSent = sendOtpSms($phone, $otp);
+
+if (!$smsSent) {
+    error_log("WARN: Failed to send OTP SMS to phone hash: {$phoneHash}");
+    // Still return success to not reveal info, but log the issue
+}
+
+// Log for development (REMOVE IN PRODUCTION!)
+if (env('APP_DEBUG', 'false') === 'true') {
+    error_log("DEV OTP for {$phone}: {$otp}");
+}
+
+json_success(null, 'إذا كان الرقم مسجلاً، سيتم إرسال رمز التحقق');
+
+// ─── SMS Helper ──────────────────────────────────────────
+function sendOtpSms(string $phone, string $otp): bool
+{
+    $smsProvider = env('SMS_PROVIDER', 'log'); // 'log', 'twilio', 'jordan_sms', 'custom'
+    
+    $message = "رمز التحقق لتطبيق مُصادَق: {$otp}\nصالح لمدة 5 دقائق.";
+    
+    switch ($smsProvider) {
+        case 'custom':
+            // Custom SMS API (your own provider)
+            $apiUrl = env('SMS_API_URL');
+            $apiKey = env('SMS_API_KEY');
+            if (!$apiUrl || !$apiKey) return false;
+            
+            try {
+                $ch = curl_init($apiUrl);
+                curl_setopt_array($ch, [
+                    CURLOPT_POST => true,
+                    CURLOPT_POSTFIELDS => json_encode([
+                        'to' => $phone,
+                        'message' => $message,
+                        'api_key' => $apiKey,
+                    ]),
+                    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
+                    CURLOPT_RETURNTRANSFER => true,
+                    CURLOPT_TIMEOUT => 10,
+                ]);
+                $response = curl_exec($ch);
+                $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+                curl_close($ch);
+                return $httpCode >= 200 && $httpCode < 300;
+            } catch (\Exception $e) {
+                error_log("SMS send error: " . $e->getMessage());
+                return false;
+            }
+            
+        case 'log':
+        default:
+            // Development: just log the OTP
+            error_log("SMS OTP [{$phone}]: {$otp}");
+            return true;
+    }
+}
--- a/app/modules_app/auth/mobile_verify_otp.php
+++ b/app/modules_app/auth/mobile_verify_otp.php
@@ -0,0 +1,174 @@
+<?php
+/**
+ * Mobile OTP Verify Endpoint
+ * POST /v1/auth/mobile/verify-otp
+ * 
+ * Verifies OTP, registers device, and returns JWT + device secret for HMAC.
+ */
+
+declare(strict_types=1);
+
+use App\Core\Database;
+use App\Core\JWT;
+use App\Core\Validator;
+use App\Core\Security;
+use App\Middleware\RateLimitMiddleware;
+
+// Rate limit: 10 verify attempts per minute per IP
+RateLimitMiddleware::check(10, 60);
+
+$data = Security::sanitize(input());
+
+// 1. Validate
+$errors = Validator::validate($data, [
+    'phone' => 'required',
+    'otp'   => 'required',
+]);
+
+if ($errors) {
+    json_error('رقم الهاتف ورمز التحقق مطلوبان', 422, $errors);
+}
+
+$phone = preg_replace('/[^0-9+]/', '', $data['phone']);
+$phoneHash = hash('sha256', $phone);
+$deviceId = $data['device_id'] ?? '';
+$deviceName = $data['device_name'] ?? 'Unknown Device';
+$platform = $data['platform'] ?? 'android';
+$appVersion = $data['app_version'] ?? '1.0.0';
+$pushToken = $data['push_token'] ?? null;
+
+if (empty($deviceId)) {
+    json_error('معرّف الجهاز مطلوب', 422);
+}
+
+// 2. Load OTP from cache
+$cacheFile = STORAGE_PATH . '/cache/otp/otp_' . $phoneHash . '.json';
+if (!file_exists($cacheFile)) {
+    json_error('رمز التحقق غير صالح أو منتهي الصلاحية', 401);
+}
+
+$fp = fopen($cacheFile, 'r+');
+if (!$fp) {
+    json_error('خطأ في النظام', 500);
+}
+
+flock($fp, LOCK_EX);
+$content = stream_get_contents($fp);
+$otpData = json_decode($content, true);
+
+if (!$otpData || $otpData['expires_at'] < time()) {
+    flock($fp, LOCK_UN);
+    fclose($fp);
+    @unlink($cacheFile);
+    json_error('رمز التحقق منتهي الصلاحية. اطلب رمزاً جديداً.', 401);
+}
+
+// Check attempts
+if ($otpData['attempts'] >= $otpData['max_attempts']) {
+    flock($fp, LOCK_UN);
+    fclose($fp);
+    @unlink($cacheFile);
+    json_error('تجاوزت عدد المحاولات المسموحة. اطلب رمزاً جديداً.', 429);
+}
+
+// Verify OTP
+if (!password_verify($data['otp'], $otpData['hash'])) {
+    $otpData['attempts']++;
+    ftruncate($fp, 0);
+    rewind($fp);
+    fwrite($fp, json_encode($otpData));
+    flock($fp, LOCK_UN);
+    fclose($fp);
+    
+    $remaining = $otpData['max_attempts'] - $otpData['attempts'];
+    json_error("رمز التحقق غير صحيح. المحاولات المتبقية: {$remaining}", 401);
+}
+
+// OTP is valid — clean up
+flock($fp, LOCK_UN);
+fclose($fp);
+@unlink($cacheFile);
+
+// 3. Fetch user
+$db = Database::getInstance();
+$userId = $otpData['user_id'];
+
+$stmt = $db->prepare("SELECT id, tenant_id, name, email, role, is_active FROM users WHERE id = ? LIMIT 1");
+$stmt->execute([$userId]);
+$user = $stmt->fetch();
+
+if (!$user || !$user['is_active']) {
+    json_error('الحساب غير موجود أو معطّل', 403);
+}
+
+// 4. Generate device secret for HMAC
+$deviceSecret = hash('sha256', $userId . $deviceId . bin2hex(random_bytes(16)));
+
+// 5. Register/Update device
+$stmt = $db->prepare("
+    INSERT INTO user_devices (id, user_id, device_fingerprint, device_name, platform, app_version, push_token, device_secret, is_trusted, last_seen_at)
+    VALUES (UUID(), ?, ?, ?, ?, ?, ?, ?, TRUE, NOW())
+    ON DUPLICATE KEY UPDATE
+        device_name = VALUES(device_name),
+        platform = VALUES(platform),
+        app_version = VALUES(app_version),
+        push_token = VALUES(push_token),
+        device_secret = VALUES(device_secret),
+        is_trusted = TRUE,
+        last_seen_at = NOW(),
+        updated_at = NOW()
+");
+$stmt->execute([
+    $userId,
+    $deviceId,
+    $deviceName,
+    $platform,
+    $appVersion,
+    $pushToken,
+    password_hash($deviceSecret, PASSWORD_DEFAULT), // Store hashed
+]);
+
+// 6. Generate JWT (30 days for mobile)
+$secret = env('JWT_SECRET');
+if (!$secret || strlen($secret) < 32) {
+    error_log('FATAL: JWT_SECRET is missing or too short in .env');
+    json_error('Server configuration error', 500);
+}
+
+$payload = [
+    'user_id'   => $user['id'],
+    'tenant_id' => $user['tenant_id'],
+    'role'      => $user['role'],
+    'device_id' => $deviceId,
+    'source'    => 'mobile',
+    'exp'       => time() + (30 * 24 * 3600), // 30 days
+];
+
+$token = JWT::encode($payload, $secret);
+
+// 7. Generate refresh token
+$refreshToken = bin2hex(random_bytes(32));
+$refreshTokenHash = hash('sha256', $refreshToken);
+$stmt = $db->prepare("UPDATE users SET refresh_token_hash = ?, last_login_at = NOW() WHERE id = ?");
+$stmt->execute([$refreshTokenHash, $userId]);
+
+// 8. Decrypt name for response
+$userName = $user['name'];
+try {
+    $decrypted = \App\Core\Encryption::decrypt($user['name']);
+    if ($decrypted !== false) $userName = $decrypted;
+} catch (\Exception $e) {
+    // Keep encrypted name
+}
+
+json_success([
+    'access_token'  => $token,
+    'refresh_token' => $refreshToken,
+    'device_secret' => $deviceSecret, // Client stores this securely for HMAC
+    'user' => [
+        'id'        => $user['id'],
+        'name'      => $userName,
+        'role'      => $user['role'],
+        'tenant_id' => $user['tenant_id'],
+    ],
+], 'تم التحقق بنجاح. مرحباً بك في مُصادَق!');
--- a/app/modules_app/auth/register_device.php
+++ b/app/modules_app/auth/register_device.php
@@ -0,0 +1,60 @@
+<?php
+/**
+ * Register/Update Device Endpoint
+ * POST /v1/auth/mobile/register-device
+ * 
+ * Updates push token and device info for an already-authenticated device.
+ */
+
+declare(strict_types=1);
+
+use App\Core\Database;
+use App\Middleware\AuthMiddleware;
+use App\Core\Security;
+
+$decoded = AuthMiddleware::check();
+$userId = $decoded['user_id'];
+$deviceId = $decoded['device_id'] ?? null;
+
+if (!$deviceId) {
+    json_error('هذا الـ endpoint مخصص لتطبيق الهاتف فقط', 403);
+}
+
+$data = Security::sanitize(input());
+
+$db = Database::getInstance();
+
+$updateFields = [];
+$params = [];
+
+if (isset($data['push_token'])) {
+    $updateFields[] = 'push_token = ?';
+    $params[] = $data['push_token'];
+}
+
+if (isset($data['app_version'])) {
+    $updateFields[] = 'app_version = ?';
+    $params[] = $data['app_version'];
+}
+
+if (isset($data['device_name'])) {
+    $updateFields[] = 'device_name = ?';
+    $params[] = $data['device_name'];
+}
+
+// Always update last_seen
+$updateFields[] = 'last_seen_at = NOW()';
+
+if (empty($updateFields)) {
+    json_success(null, 'لا يوجد بيانات للتحديث');
+    exit;
+}
+
+$sql = "UPDATE user_devices SET " . implode(', ', $updateFields) . " WHERE user_id = ? AND device_fingerprint = ?";
+$params[] = $userId;
+$params[] = $deviceId;
+
+$stmt = $db->prepare($sql);
+$stmt->execute($params);
+
+json_success(null, 'تم تحديث بيانات الجهاز');
--- a/app/modules_app/batches/create.php
+++ b/app/modules_app/batches/create.php
@@ -0,0 +1,72 @@
+<?php
+/**
+ * Create Batch Endpoint
+ * POST /v1/batches/create
+ * 
+ * Creates a new invoice batch for the mobile scanner.
+ * Returns batch_id that the mobile app uses to upload images.
+ */
+
+declare(strict_types=1);
+
+use App\Core\Database;
+use App\Middleware\AuthMiddleware;
+use App\Core\Security;
+use App\Core\Validator;
+use App\Middleware\QuotaMiddleware;
+
+$decoded = AuthMiddleware::check();
+$tenantId = $decoded['tenant_id'];
+$userId = $decoded['user_id'];
+
+$data = Security::sanitize(input());
+
+// 1. Validate
+$errors = Validator::validate($data, [
+    'company_id' => 'required',
+]);
+
+if ($errors) {
+    json_error('رقم الشركة مطلوب', 422, $errors);
+}
+
+$companyId = $data['company_id'];
+$source = $data['source'] ?? 'mobile_scan';
+$expectedImages = (int)($data['expected_images'] ?? 0);
+
+// 2. Permission check
+$db = Database::getInstance();
+$stmt = $db->prepare("SELECT id FROM companies WHERE id = ? AND tenant_id = ? AND deleted_at IS NULL");
+$stmt->execute([$companyId, $tenantId]);
+
+if (!$stmt->fetch()) {
+    json_error('الوصول مرفوض لهذه الشركة', 403);
+}
+
+// 3. Check quota (preview — don't increment yet)
+try {
+    QuotaMiddleware::checkInvoiceQuota($tenantId);
+} catch (\Exception $e) {
+    json_error('تم استنفاد رصيد الفواتير لهذا الشهر. قم بترقية باقتك.', 429);
+}
+
+// 4. Generate batch ID
+$batchId = vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex(random_bytes(16)), 4));
+
+// 5. Create batch record
+$stmt = $db->prepare("
+    INSERT INTO invoice_batches (id, tenant_id, company_id, uploaded_by, total_images, source, status)
+    VALUES (?, ?, ?, ?, ?, ?, 'uploading')
+");
+$stmt->execute([$batchId, $tenantId, $companyId, $userId, $expectedImages, $source]);
+
+// 6. Create upload directory
+$uploadDir = STORAGE_PATH . '/invoices/' . $tenantId . '/' . $companyId . '/batches/' . $batchId;
+if (!is_dir($uploadDir)) {
+    mkdir($uploadDir, 0755, true);
+}
+
+json_success([
+    'batch_id' => $batchId,
+    'upload_url' => 'v1/batches/upload-image',
+], 'تم إنشاء الدفعة بنجاح. ابدأ برفع الصور.');
--- a/app/modules_app/batches/finalize.php
+++ b/app/modules_app/batches/finalize.php
@@ -0,0 +1,65 @@
+<?php
+/**
+ * Finalize Batch Endpoint
+ * POST /v1/batches/finalize
+ * 
+ * Marks a batch as ready for processing.
+ * Triggers background processing (or processes synchronously depending on setup).
+ */
+
+declare(strict_types=1);
+
+use App\Core\Database;
+use App\Middleware\AuthMiddleware;
+use App\Core\Security;
+
+$decoded = AuthMiddleware::check();
+$tenantId = $decoded['tenant_id'];
+$userId = $decoded['user_id'];
+
+$data = Security::sanitize(input());
+$batchId = $data['batch_id'] ?? null;
+
+if (!$batchId) {
+    json_error('معرّف الدفعة مطلوب', 422);
+}
+
+$db = Database::getInstance();
+
+// 1. Verify batch
+$stmt = $db->prepare("
+    SELECT id, status, total_images 
+    FROM invoice_batches 
+    WHERE id = ? AND tenant_id = ? AND uploaded_by = ?
+");
+$stmt->execute([$batchId, $tenantId, $userId]);
+$batch = $stmt->fetch();
+
+if (!$batch) {
+    json_error('الدفعة غير موجودة', 404);
+}
+
+if ($batch['status'] !== 'uploading') {
+    json_error('تم إنهاء هذه الدفعة مسبقاً', 400);
+}
+
+if ($batch['total_images'] == 0) {
+    json_error('لا يمكن إنهاء دفعة فارغة', 400);
+}
+
+// 2. Mark as processing
+$stmt = $db->prepare("
+    UPDATE invoice_batches 
+    SET status = 'processing', updated_at = NOW() 
+    WHERE id = ?
+");
+$stmt->execute([$batchId]);
+
+// In a real production environment, you would dispatch a job to a queue worker here.
+// For now, the queue worker is a cron job that checks the `invoice_processing_queue` table.
+
+json_success([
+    'batch_id' => $batchId,
+    'status' => 'processing',
+    'total_images' => $batch['total_images']
+], 'تم إنهاء الدفعة بنجاح وإرسالها للمعالجة');
--- a/app/modules_app/batches/status.php
+++ b/app/modules_app/batches/status.php
@@ -0,0 +1,54 @@
+<?php
+/**
+ * Batch Status Endpoint
+ * GET /v1/batches/status
+ * 
+ * Returns the processing status of a batch and its items.
+ */
+
+declare(strict_types=1);
+
+use App\Core\Database;
+use App\Middleware\AuthMiddleware;
+use App\Core\Security;
+
+$decoded = AuthMiddleware::check();
+$tenantId = $decoded['tenant_id'];
+$userId = $decoded['user_id'];
+
+$data = Security::sanitize($_GET);
+$batchId = $data['batch_id'] ?? null;
+
+if (!$batchId) {
+    json_error('معرّف الدفعة مطلوب', 422);
+}
+
+$db = Database::getInstance();
+
+// 1. Get batch info
+$stmt = $db->prepare("
+    SELECT id, status, total_images, processed_images, failed_images, created_at, completed_at
+    FROM invoice_batches 
+    WHERE id = ? AND tenant_id = ?
+");
+$stmt->execute([$batchId, $tenantId]);
+$batch = $stmt->fetch();
+
+if (!$batch) {
+    json_error('الدفعة غير موجودة', 404);
+}
+
+// 2. Get items
+$stmt = $db->prepare("
+    SELECT id, invoice_id, image_order, status, error_message, created_at, processed_at
+    FROM invoice_processing_queue
+    WHERE batch_id = ?
+    ORDER BY image_order ASC
+");
+$stmt->execute([$batchId]);
+$items = $stmt->fetchAll();
+
+json_success([
+    'batch' => $batch,
+    'items' => $items
+], 'تم جلب حالة الدفعة');
--- a/app/modules_app/batches/upload_image.php
+++ b/app/modules_app/batches/upload_image.php
@@ -0,0 +1,97 @@
+<?php
+/**
+ * Upload Image to Batch
+ * POST /v1/batches/upload-image
+ * 
+ * Uploads a single image to an existing batch.
+ * Supports multipart/form-data with 'image' file and 'batch_id'.
+ */
+
+declare(strict_types=1);
+
+use App\Core\Database;
+use App\Middleware\AuthMiddleware;
+
+$decoded = AuthMiddleware::check();
+$tenantId = $decoded['tenant_id'];
+$userId = $decoded['user_id'];
+
+// 1. Validate request
+$batchId = $_POST['batch_id'] ?? null;
+$imageOrder = (int)($_POST['image_order'] ?? 0);
+
+if (!$batchId || !isset($_FILES['image']) || $_FILES['image']['error'] !== UPLOAD_ERR_OK) {
+    $uploadError = $_FILES['image']['error'] ?? 'No file';
+    json_error("معرّف الدفعة وصورة الفاتورة مطلوبان (كود: {$uploadError})", 422);
+}
+
+// 2. Verify batch belongs to this tenant and is still uploading
+$db = Database::getInstance();
+$stmt = $db->prepare("
+    SELECT id, company_id, status, total_images 
+    FROM invoice_batches 
+    WHERE id = ? AND tenant_id = ? AND uploaded_by = ?
+");
+$stmt->execute([$batchId, $tenantId, $userId]);
+$batch = $stmt->fetch();
+
+if (!$batch) {
+    json_error('الدفعة غير موجودة أو ليس لديك صلاحية', 404);
+}
+
+if ($batch['status'] !== 'uploading') {
+    json_error('لا يمكن إضافة صور لدفعة تمت معالجتها', 400);
+}
+
+// 3. Validate file type
+$allowedTypes = ['image/jpeg', 'image/png', 'image/webp', 'image/heic', 'image/heif'];
+$mimeType = $_FILES['image']['type'];
+if (!in_array($mimeType, $allowedTypes)) {
+    json_error('نوع الملف غير مدعوم. المسموح: JPEG, PNG, WebP, HEIC', 422);
+}
+
+// 4. Validate file size (max 10MB)
+$maxSize = 10 * 1024 * 1024;
+if ($_FILES['image']['size'] > $maxSize) {
+    json_error('حجم الصورة أكبر من 10 ميغابايت', 422);
+}
+
+// 5. Save file
+$companyId = $batch['company_id'];
+$uploadDir = STORAGE_PATH . '/invoices/' . $tenantId . '/' . $companyId . '/batches/' . $batchId;
+if (!is_dir($uploadDir)) {
+    mkdir($uploadDir, 0755, true);
+}
+
+$extension = pathinfo($_FILES['image']['name'], PATHINFO_EXTENSION) ?: 'jpg';
+$fileName = sprintf('img_%03d_%s.%s', $imageOrder, bin2hex(random_bytes(4)), $extension);
+$targetPath = $uploadDir . '/' . $fileName;
+
+if (!move_uploaded_file($_FILES['image']['tmp_name'], $targetPath)) {
+    json_error('فشل في حفظ الصورة', 500);
+}
+
+// 6. Add to processing queue
+$stmt = $db->prepare("
+    INSERT INTO invoice_processing_queue (batch_id, tenant_id, company_id, image_path, image_order, status)
+    VALUES (?, ?, ?, ?, ?, 'pending')
+");
+$stmt->execute([$batchId, $tenantId, $companyId, $targetPath, $imageOrder]);
+
+// 7. Update batch image count
+$stmt = $db->prepare("
+    UPDATE invoice_batches 
+    SET total_images = total_images + 1, updated_at = NOW()
+    WHERE id = ?
+");
+$stmt->execute([$batchId]);
+
+// Count uploaded so far
+$stmt = $db->prepare("SELECT COUNT(*) FROM invoice_processing_queue WHERE batch_id = ?");
+$stmt->execute([$batchId]);
+$uploadedCount = (int)$stmt->fetchColumn();
+
+json_success([
+    'uploaded' => $uploadedCount,
+    'file_name' => $fileName,
+], "تم رفع الصورة بنجاح ({$uploadedCount} صور في الدفعة)");
--- a/app/modules_app/voice/parse_intent.php
+++ b/app/modules_app/voice/parse_intent.php
@@ -0,0 +1,103 @@
+<?php
+/**
+ * Voice Parse Intent Proxy Endpoint
+ * POST /v1/voice/parse-intent
+ * 
+ * Proxies transcribed text to Gemini to extract intent and parameters.
+ */
+
+declare(strict_types=1);
+
+use App\Middleware\AuthMiddleware;
+use App\Middleware\RateLimitMiddleware;
+use App\Core\Security;
+use App\Core\Validator;
+
+// Rate limit: 20 per minute
+RateLimitMiddleware::check(20, 60);
+
+$decoded = AuthMiddleware::check();
+$data = Security::sanitize(input());
+
+$errors = Validator::validate($data, ['text' => 'required']);
+if ($errors) {
+    json_error('النص مطلوب', 422);
+}
+
+$apiKey = env('GEMINI_API_KEY');
+if (!$apiKey) {
+    json_error('Gemini API Key غير متوفر', 500);
+}
+
+$text = $data['text'];
+
+$systemPrompt = <<<PROMPT
+أنت محلل أوامر لنظام مُصادَق للفوترة الأردني.
+استخرج النية والمعاملات من النص وأرجع JSON فقط.
+
+الأوامر المتاحة:
+- list_invoices: { company?: string, from?: date, to?: date, status?: string }
+- check_quota: {}
+- open_scanner: { company?: string }
+- search_invoice: { amount?: number, company?: string, number?: string }
+- get_report: { type: "tax"|"monthly", period?: string }
+- check_status: { invoice_id?: string, company?: string }
+- export_pdf: { invoice_id?: string, company?: string }
+- navigate: { screen: string }
+
+أرجع JSON بهذا التنسيق:
+{
+  "action": "...",
+  "params": {...},
+  "confirmation": "نص قصير تأكيد بالعامية الأردنية أو الفصحى المبسطة"
+}
+PROMPT;
+
+$payload = [
+    'contents' => [
+        ['parts' => [['text' => $text]]]
+    ],
+    'systemInstruction' => [
+        'parts' => [['text' => $systemPrompt]]
+    ],
+    'generationConfig' => [
+        'responseMimeType' => 'application/json',
+        'temperature' => 0.2
+    ]
+];
+
+// Determine appropriate endpoint based on env
+$model = env('GEMINI_MODEL', 'gemini-1.5-flash');
+$url = "https://generativelanguage.googleapis.com/v1beta/models/{$model}:generateContent?key={$apiKey}";
+
+$ch = curl_init($url);
+curl_setopt_array($ch, [
+    CURLOPT_POST => true,
+    CURLOPT_POSTFIELDS => json_encode($payload),
+    CURLOPT_RETURNTRANSFER => true,
+    CURLOPT_HTTPHEADER => ['Content-Type: application/json']
+]);
+
+$response = curl_exec($ch);
+$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+$error = curl_error($ch);
+curl_close($ch);
+
+if ($httpCode !== 200) {
+    error_log("Gemini Error: $response | $error");
+    json_error('فشل في تحليل الأمر', 500);
+}
+
+$respData = json_decode($response, true);
+if (!isset($respData['candidates'][0]['content']['parts'][0]['text'])) {
+    json_error('رد غير متوقع من AI', 500);
+}
+
+$jsonText = $respData['candidates'][0]['content']['parts'][0]['text'];
+$parsed = json_decode($jsonText, true);
+
+if (!$parsed) {
+    json_error('فشل في تحليل الرد كـ JSON', 500);
+}
+
+json_success($parsed, 'تم تحليل الأمر');
--- a/app/modules_app/voice/transcribe.php
+++ b/app/modules_app/voice/transcribe.php
@@ -0,0 +1,61 @@
+<?php
+/**
+ * Voice Transcribe Proxy Endpoint
+ * POST /v1/voice/transcribe
+ * 
+ * Proxies audio file to Groq STT (Whisper) safely keeping API keys on backend.
+ */
+
+declare(strict_types=1);
+
+use App\Middleware\AuthMiddleware;
+use App\Middleware\RateLimitMiddleware;
+
+// Rate limit: 20 per minute
+RateLimitMiddleware::check(20, 60);
+
+$decoded = AuthMiddleware::check();
+
+if (!isset($_FILES['audio']) || $_FILES['audio']['error'] !== UPLOAD_ERR_OK) {
+    json_error('ملف الصوت مطلوب', 422);
+}
+
+$apiKey = env('GROQ_API_KEY');
+if (!$apiKey) {
+    json_error('Groq API Key غير متوفر', 500);
+}
+
+// Ensure it's a valid audio file (basic check)
+$tmpPath = $_FILES['audio']['tmp_name'];
+
+$cfile = curl_file_create($tmpPath, $_FILES['audio']['type'], $_FILES['audio']['name']);
+
+$postData = [
+    'file' => $cfile,
+    'model' => 'whisper-large-v3',
+    'language' => 'ar',
+    'response_format' => 'json'
+];
+
+$ch = curl_init('https://api.groq.com/openai/v1/audio/transcriptions');
+curl_setopt_array($ch, [
+    CURLOPT_POST => true,
+    CURLOPT_POSTFIELDS => $postData,
+    CURLOPT_RETURNTRANSFER => true,
+    CURLOPT_HTTPHEADER => [
+        'Authorization: Bearer ' . $apiKey
+    ]
+]);
+
+$response = curl_exec($ch);
+$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+$error = curl_error($ch);
+curl_close($ch);
+
+if ($httpCode !== 200) {
+    error_log("Groq Error: $response | $error");
+    json_error('فشل في تحويل الصوت إلى نص', 500);
+}
+
+$data = json_decode($response, true);
+json_success(['text' => $data['text'] ?? ''], 'تم التحويل بنجاح');