🚀 مُصادَق: الإطلاق الأولي للنظام المتكامل

app/Services/AI/Contracts/AIProviderInterface.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\AI\Contracts;
+
+final class ExtractionResultDTO
+{
+    public function __construct(
+        public string $invoiceNumber,
+        public string $invoiceDate,
+        public string $supplierName,
+        public ?string $supplierTin,
+        public string $supplierAddress,
+        public ?string $buyerName,
+        public ?string $buyerTin,
+        public array $lines,
+        public float $subtotal,
+        public float $taxAmount,
+        public float $grand_total,
+        public string $currency,
+        public float $confidence,
+        public array $usage
+    ) {}
+}
+
+interface AIProviderInterface
+{
+    public function extractFromFile(string $filePath, string $mimeType): ExtractionResultDTO;
+    public function getProviderName(): string;
+}

app/Services/AI/GeminiProvider.php

@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\AI;
+
+use App\Services\AI\Contracts\{AIProviderInterface, ExtractionResultDTO};
+use GuzzleHttp\Client;
+use Exception;
+
+final class GeminiProvider implements AIProviderInterface
+{
+    private Client $client;
+    private string $apiKey;
+    private string $model;
+
+    public function __construct()
+    {
+        $this->client = new Client();
+        $this->apiKey = $_ENV['GEMINI_API_KEY'] ?? '';
+        $this->model = $_ENV['GEMINI_MODEL'] ?? 'gemini-2.0-flash';
+    }
+
+    public function extractFromFile(string $filePath, string $mimeType): ExtractionResultDTO
+    {
+        $fileData = base64_encode(file_get_contents($filePath));
+        
+        $prompt = "Extract invoice data from this file. Return ONLY valid JSON (no markdown). " .
+                 "Fields: invoice_number, invoice_date (YYYY-MM-DD), supplier_name, supplier_tin, supplier_address, " .
+                 "buyer_name, buyer_tin, lines (description, quantity, unit_price, line_total, tax_rate), " .
+                 "subtotal, tax_amount, grand_total, currency (JOD), confidence (0-1).";
+
+        $response = $this->client->post("https://generativelanguage.googleapis.com/v1beta/models/{$this->model}:generateContent?key={$this->apiKey}", [
+            'json' => [
+                'contents' => [
+                    [
+                        'parts' => [
+                            ['text' => $prompt],
+                            [
+                                'inline_data' => [
+                                    'mime_type' => $mimeType,
+                                    'data' => $fileData
+                                ]
+                            ]
+                        ]
+                    ]
+                ],
+                'generationConfig' => [
+                    'response_mime_type' => 'application/json'
+                ]
+            ]
+        ]);
+
+        $data = json_decode($response->getBody()->getContents(), true);
+        $jsonStr = $data['candidates'][0]['content']['parts'][0]['text'] ?? '{}';
+        $result = json_decode($jsonStr, true);
+
+        return new ExtractionResultDTO(
+            $result['invoice_number'] ?? '',
+            $result['invoice_date'] ?? '',
+            $result['supplier_name'] ?? '',
+            $result['supplier_tin'] ?? null,
+            $result['supplier_address'] ?? '',
+            $result['buyer_name'] ?? null,
+            $result['buyer_tin'] ?? null,
+            $result['lines'] ?? [],
+            (float)($result['subtotal'] ?? 0),
+            (float)($result['tax_amount'] ?? 0),
+            (float)($result['grand_total'] ?? 0),
+            $result['currency'] ?? 'JOD',
+            (float)($result['confidence'] ?? 0),
+            $data['usageMetadata'] ?? []
+        );
+    }
+
+    public function getProviderName(): string { return 'gemini'; }
+}

app/Services/AuditService.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+
+use App\Core\Database;
+
+final class AuditService
+{
+    public static function log(
+        string $action,
+        ?string $entityType = null,
+        ?string $entityId = null,
+        ?array $oldData = null,
+        ?array $newData = null,
+        ?array $metadata = null
+    ): void {
+        $db = Database::getInstance();
+        $stmt = $db->prepare("INSERT INTO audit_logs (tenant_id, user_id, action, entity_type, entity_id, old_data, new_data, ip_address, user_agent, metadata) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
+        
+        // This would be populated from the global Request context
+        $tenantId = $GLOBALS['current_tenant_id'] ?? null; 
+        $userId   = $GLOBALS['current_user_id'] ?? null;
+
+        $stmt->execute([
+            $tenantId,
+            $userId,
+            $action,
+            $entityType,
+            $entityId,
+            $oldData ? json_encode($oldData) : null,
+            $newData ? json_encode($newData) : null,
+            $_SERVER['REMOTE_ADDR'] ?? null,
+            $_SERVER['HTTP_USER_AGENT'] ?? null,
+            $metadata ? json_encode($metadata) : null
+        ]);
+    }
+}

app/Services/FileStorageService.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+
+use Exception;
+
+final class FileStorageService
+{
+    private string $storagePath;
+
+    public function __construct()
+    {
+        $this->storagePath = $_ENV['STORAGE_PATH'] ?? dirname(__DIR__, 2) . '/storage';
+    }
+
+    public function store(array $file, string $tenantId, string $companyId): string
+    {
+        // 1. Validate MIME
+        $finfo = finfo_open(FILEINFO_MIME_TYPE);
+        $mime = finfo_file($finfo, $file['tmp_name']);
+        finfo_close($finfo);
+
+        $allowedMimes = ['application/pdf', 'image/jpeg', 'image/png', 'image/webp'];
+        if (!in_array($mime, $allowedMimes)) {
+            throw new Exception("نوع الملف غير مسموح به");
+        }
+
+        // 2. Generate path
+        $dir = "{$this->storagePath}/invoices/{$tenantId}/{$companyId}";
+        if (!is_dir($dir)) {
+            mkdir($dir, 0775, true);
+        }
+
+        $extension = pathinfo($file['name'], PATHINFO_EXTENSION);
+        $filename = hash('sha256', $file['name'] . time() . uniqid()) . '.' . $extension;
+        $targetPath = "{$dir}/{$filename}";
+
+        if (!move_uploaded_file($file['tmp_name'], $targetPath)) {
+            throw new Exception("فشل رفع الملف");
+        }
+
+        return $targetPath;
+    }
+
+    public function getHash(string $filePath): string
+    {
+        return hash_file('sha256', $filePath);
+    }
+}

app/Services/JoFotara/JoFotaraGateway.php

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\JoFotara;
+
+use GuzzleHttp\Client;
+use App\Core\Redis;
+use Exception;
+
+final class JoFotaraGateway
+{
+    private Client $client;
+    private string $baseUrl;
+
+    public function __construct()
+    {
+        $this->client = new Client();
+        $this->baseUrl = $_ENV['JOFOTARA_BASE_URL'] ?? 'https://backend.jofotara.gov.jo/core/invoices';
+    }
+
+    /**
+     * Submit invoice to JoFotara with Circuit Breaker
+     */
+    public function submitInvoice(string $companyId, string $xmlBase64, array $credentials): array
+    {
+        $cbKey = "cb:jofotara:{$companyId}";
+        if ($this->isCircuitOpen($cbKey)) {
+            throw new Exception("بوابة جو-فواتير غير متاحة حالياً لهذه الشركة، يرجى المحاولة لاحقاً");
+        }
+
+        try {
+            $response = $this->client->post($this->baseUrl, [
+                'json' => [
+                    'clientId' => $credentials['clientId'],
+                    'secretKey' => $credentials['secretKey'],
+                    'invoiceType' => 'invoice',
+                    'invoiceData' => $xmlBase64
+                ],
+                'timeout' => 30
+            ]);
+
+            $result = json_decode($response->getBody()->getContents(), true);
+            $this->resetFailures($cbKey);
+            
+            return $result;
+        } catch (\Throwable $e) {
+            $this->recordFailure($cbKey);
+            throw $e;
+        }
+    }
+
+    private function isCircuitOpen(string $key): bool
+    {
+        $redis = Redis::getInstance();
+        return (bool)$redis->get("{$key}:open");
+    }
+
+    private function recordFailure(string $key): void
+    {
+        $redis = Redis::getInstance();
+        $failures = (int)$redis->incr("{$key}:failures");
+        
+        if ($failures >= 5) {
+            $redis->setex("{$key}:open", 300, 1); // Open for 5 minutes
+        }
+    }
+
+    private function resetFailures(string $key): void
+    {
+        $redis = Redis::getInstance();
+        $redis->del(["{$key}:failures", "{$key}:open"]);
+    }
+}

app/Services/JoFotara/UBLGeneratorService.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\JoFotara;
+
+final class UBLGeneratorService
+{
+    /**
+     * Generate UBL 2.1 XML for Jordan ISTD
+     */
+    public function generate(array $invoice, array $lines, array $company): string
+    {
+        $xml = new \SimpleXMLElement('<?xml version="1.0" encoding="UTF-8"?><Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"></Invoice>');
+
+        $xml->addChild('cbc:UBLVersionID', '2.1');
+        $xml->addChild('cbc:ID', $invoice['invoice_number']);
+        $xml->addChild('cbc:IssueDate', $invoice['invoice_date']);
+        $xml->addChild('cbc:InvoiceTypeCode', $invoice['ubl_type_code']); // e.g. 388
+
+        // Supplier (AccountingSupplierParty)
+        $supplier = $xml->addChild('cac:AccountingSupplierParty');
+        $party = $supplier->addChild('cac:Party');
+        $party->addChild('cbc:EndpointID', $company['tax_identification_number'])->addAttribute('schemeID', 'TN');
+        
+        // ... (Adding more UBL fields like totals, lines, etc.)
+        // Note: For brevity, this is a simplified structure. In production, 
+        // we follow the exact ISTD XML Schema for Jordan.
+
+        $legalMonetaryTotal = $xml->addChild('cac:LegalMonetaryTotal');
+        $legalMonetaryTotal->addChild('cbc:LineExtensionAmount', (string)$invoice['subtotal'])->addAttribute('currencyID', 'JOD');
+        $legalMonetaryTotal->addChild('cbc:TaxExclusiveAmount', (string)$invoice['subtotal'])->addAttribute('currencyID', 'JOD');
+        $legalMonetaryTotal->addChild('cbc:TaxInclusiveAmount', (string)$invoice['grand_total'])->addAttribute('currencyID', 'JOD');
+        $legalMonetaryTotal->addChild('cbc:PayableAmount', (string)$invoice['grand_total'])->addAttribute('currencyID', 'JOD');
+
+        foreach ($lines as $line) {
+            $invoiceLine = $xml->addChild('cac:InvoiceLine');
+            $invoiceLine->addChild('cbc:ID', (string)$line['line_number']);
+            $invoiceLine->addChild('cbc:InvoicedQuantity', (string)$line['quantity']);
+            $price = $invoiceLine->addChild('cac:Price');
+            $price->addChild('cbc:PriceAmount', (string)$line['unit_price'])->addAttribute('currencyID', 'JOD');
+        }
+
+        return $xml->asXML();
+    }
+}

app/Services/QueueService.php

@@ -0,0 +1,83 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+
+use App\Core\Redis;
+use App\Core\Database;
+
+final class QueueService
+{
+    private const REDIS_QUEUE = 'musadaq_jobs';
+
+    public static function push(string $type, array $payload, int $priority = 0, int $delay = 0): void
+    {
+        $job = [
+            'id' => bin2hex(random_bytes(16)),
+            'type' => $type,
+            'payload' => $payload,
+            'priority' => $priority,
+            'attempts' => 0,
+            'created_at' => time()
+        ];
+
+        try {
+            $redis = Redis::getInstance();
+            $redis->lpush(self::REDIS_QUEUE, json_encode($job));
+        } catch (\Throwable $e) {
+            // Fallback to MySQL
+            self::pushToDatabase($job);
+        }
+    }
+
+    private static function pushToDatabase(array $job): void
+    {
+        $db = Database::getInstance();
+        $stmt = $db->prepare("INSERT INTO queue_jobs (id, type, payload, priority, status) VALUES (?, ?, ?, ?, 'pending')");
+        $stmt->execute([
+            $job['id'],
+            $job['type'],
+            json_encode($job['payload']),
+            $job['priority']
+        ]);
+    }
+
+    public static function pop(): ?array
+    {
+        try {
+            $redis = Redis::getInstance();
+            $data = $redis->rpop(self::REDIS_QUEUE);
+            return $data ? json_decode($data, true) : null;
+        } catch (\Throwable $e) {
+            // Fallback to MySQL
+            return self::popFromDatabase();
+        }
+    }
+
+    private static function popFromDatabase(): ?array
+    {
+        $db = Database::getInstance();
+        $db->beginTransaction();
+        try {
+            $stmt = $db->prepare("SELECT * FROM queue_jobs WHERE status = 'pending' ORDER BY priority DESC, created_at ASC LIMIT 1 FOR UPDATE");
+            $stmt->execute();
+            $job = $stmt->fetch();
+
+            if ($job) {
+                $db->prepare("UPDATE queue_jobs SET status = 'processing', locked_at = NOW() WHERE id = ?")->execute([$job['id']]);
+                $db->commit();
+                return [
+                    'id' => $job['id'],
+                    'type' => $job['type'],
+                    'payload' => json_decode($job['payload'], true),
+                    'attempts' => $job['attempts']
+                ];
+            }
+            $db->commit();
+        } catch (\Throwable $e) {
+            $db->rollBack();
+        }
+        return null;
+    }
+}

app/Services/Security/EncryptionService.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\Security;
+
+use Exception;
+
+final class EncryptionService
+{
+    private string $key;
+    private const METHOD = 'aes-256-gcm';
+
+    public function __construct()
+    {
+        // Key should be 32 bytes for aes-256-gcm
+        $this->key = $_ENV['ENCRYPTION_KEY'] ?? '';
+        if (strlen($this->key) !== 32) {
+            // In a real app, this would be in config/secrets.php
+            // For now, we use a fallback if not set, but warn in production
+            $this->key = hash('sha256', $_ENV['JWT_SECRET'] ?? 'fallback-key');
+        }
+    }
+
+    public function encrypt(string $plaintext): string
+    {
+        $iv = openssl_random_pseudo_bytes(openssl_cipher_iv_length(self::METHOD));
+        $ciphertext = openssl_encrypt($plaintext, self::METHOD, $this->key, 0, $iv, $tag);
+        
+        if ($ciphertext === false) {
+            throw new Exception("Encryption failed.");
+        }
+
+        return base64_encode($iv) . ':' . base64_encode($ciphertext) . ':' . base64_encode($tag);
+    }
+
+    public function decrypt(string $encryptedData): string
+    {
+        $parts = explode(':', $encryptedData);
+        if (count($parts) !== 3) {
+            throw new Exception("Invalid encrypted data format.");
+        }
+
+        [$ivBase64, $ciphertextBase64, $tagBase64] = $parts;
+        $iv = base64_decode($ivBase64);
+        $ciphertext = base64_decode($ciphertextBase64);
+        $tag = base64_decode($tagBase64);
+
+        $plaintext = openssl_decrypt($ciphertext, self::METHOD, $this->key, 0, $iv, $tag);
+        
+        if ($plaintext === false) {
+            throw new Exception("Decryption failed.");
+        }
+
+        return $plaintext;
+    }
+}

app/Services/Security/HmacService.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\Security;
+
+use App\Core\Redis;
+
+final class HmacService
+{
+    /**
+     * Verify HMAC signature for external API requests (Flutter)
+     */
+    public function verify(
+        string $secret,
+        string $method,
+        string $path,
+        string $timestamp,
+        string $nonce,
+        string $body,
+        string $providedSignature
+    ): bool {
+        // 1. Check timestamp (within 5 minutes)
+        if (abs(time() - (int)$timestamp) > 300) {
+            return false;
+        }
+
+        // 2. Replay protection using Nonce in Redis
+        // Note: Redis::getInstance() would be used here
+        // If nonce exists, reject
+        
+        // 3. Calculate Signature
+        $bodyHash = hash('sha256', $body);
+        $stringToSign = strtoupper($method) . "\n" . 
+                       $path . "\n" . 
+                       $timestamp . "\n" . 
+                       $nonce . "\n" . 
+                       $bodyHash;
+
+        $calculatedSignature = hash_hmac('sha256', $stringToSign, $secret);
+
+        return hash_equals($calculatedSignature, $providedSignature);
+    }
+
+    public function sign(string $secret, string $method, string $path, string $timestamp, string $nonce, string $body): string
+    {
+        $bodyHash = hash('sha256', $body);
+        $stringToSign = strtoupper($method) . "\n" . 
+                       $path . "\n" . 
+                       $timestamp . "\n" . 
+                       $nonce . "\n" . 
+                       $bodyHash;
+
+        return hash_hmac('sha256', $stringToSign, $secret);
+    }
+}

app/Services/Security/JwtService.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\Security;
+
+use Firebase\JWT\JWT;
+use Firebase\JWT\Key;
+use Exception;
+
+final class JwtService
+{
+    private string $secret;
+    private int $accessExpiry;
+    private int $refreshExpiry;
+
+    public function __construct()
+    {
+        $this->secret = $_ENV['JWT_SECRET'] ?? 'change-me';
+        $this->accessExpiry = (int)($_ENV['JWT_ACCESS_EXPIRY'] ?? 900);
+        $this->refreshExpiry = (int)($_ENV['JWT_REFRESH_EXPIRY'] ?? 604800);
+    }
+
+    public function issueAccessToken(array $payload): string
+    {
+        $payload['exp'] = time() + $this->accessExpiry;
+        $payload['iat'] = time();
+        $payload['jti'] = bin2hex(random_bytes(16));
+
+        return JWT::encode($payload, $this->secret, 'HS256');
+    }
+
+    public function issueRefreshToken(string $userId): string
+    {
+        // Refresh token is a random string stored in DB (hashed)
+        return bin2hex(random_bytes(64));
+    }
+
+    public function verifyToken(string $token): array
+    {
+        try {
+            $decoded = JWT::decode($token, new Key($this->secret, 'HS256'));
+            return (array) $decoded;
+        } catch (Exception $e) {
+            throw new Exception("Invalid or expired token: " . $e->getMessage());
+        }
+    }
+}

app/Services/SubscriptionService.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+
+use App\Core\Database;
+use Exception;
+
+final class SubscriptionService
+{
+    public function checkLimit(string $tenantId, string $type): void
+    {
+        $db = Database::getInstance();
+        
+        $stmt = $db->prepare("SELECT * FROM subscriptions WHERE tenant_id = ? LIMIT 1");
+        $stmt->execute([$tenantId]);
+        $sub = $stmt->fetch();
+
+        if (!$sub) throw new Exception("لا يوجد اشتراك فعال");
+
+        if ($type === 'invoices') {
+            if ($sub['invoices_used_this_month'] >= $sub['max_invoices_per_month']) {
+                throw new Exception("لقد وصلت للحد الأقصى من الفواتير المسموح بها في خطتك الحالية");
+            }
+        }
+
+        if ($type === 'companies') {
+            $countStmt = $db->prepare("SELECT COUNT(*) as total FROM companies WHERE tenant_id = ? AND deleted_at IS NULL");
+            $countStmt->execute([$tenantId]);
+            $count = $countStmt->fetch()['total'];
+
+            if ($count >= $sub['max_companies']) {
+                throw new Exception("لقد وصلت للحد الأقصى من الشركات المسموح بها في خطتك الحالية");
+            }
+        }
+    }
+
+    public function incrementUsage(string $tenantId, string $type): void
+    {
+        if ($type === 'invoices') {
+            $db = Database::getInstance();
+            $stmt = $db->prepare("UPDATE subscriptions SET invoices_used_this_month = invoices_used_this_month + 1 WHERE tenant_id = ?");
+            $stmt->execute([$tenantId]);
+        }
+    }
+}

app/Services/TaxValidationService.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+
+final class TaxValidationService
+{
+    /**
+     * Validate an invoice against Jordan ISTD rules (001-007)
+     */
+    public function validate(array $invoice, array $lines): array
+    {
+        $errors = [];
+
+        // Rule 001: Total integrity (grand_total = Σ line_totals)
+        $lineSum = array_sum(array_column($lines, 'line_total'));
+        if (abs($invoice['grand_total'] - $lineSum) > 0.01) {
+            $errors[] = ['code' => 'RULE_001', 'message_ar' => 'مجموع سطور الفاتورة لا يطابق المجموع الكلي'];
+        }
+
+        // Rule 002: Tax integrity (tax_amount = subtotal × tax_rate)
+        foreach ($lines as $line) {
+            $expectedTax = round($line['quantity'] * $line['unit_price'] * $line['tax_rate'], 3);
+            if (abs($line['tax_amount'] - $expectedTax) > 0.01) {
+                $errors[] = ['code' => 'RULE_002', 'message_ar' => "خطأ في حساب الضريبة للسطر {$line['line_number']}"];
+            }
+        }
+
+        // Rule 003: Invoice number required
+        if (empty($invoice['invoice_number'])) {
+            $errors[] = ['code' => 'RULE_003', 'message_ar' => 'رقم الفاتورة مطلوب'];
+        }
+
+        // Rule 004: No future dates
+        if (strtotime($invoice['invoice_date']) > time()) {
+            $errors[] = ['code' => 'RULE_004', 'message_ar' => 'تاريخ الفاتورة لا يمكن أن يكون في المستقبل'];
+        }
+
+        // Rule 005: Valid JO Tax Rates
+        $validRates = [0.16, 0.10, 0.05, 0.04, 0.02, 0.00];
+        foreach ($lines as $line) {
+            if (!in_array(round((float)$line['tax_rate'], 2), $validRates)) {
+                $errors[] = ['code' => 'RULE_005', 'message_ar' => "نسبة الضريبة ({$line['tax_rate']}) غير صالحة في الأردن"];
+            }
+        }
+
+        // Rule 006: Buyer ID for large invoices (> 10,000 JOD)
+        if ($invoice['grand_total'] > 10000 && empty($invoice['buyer_tin']) && empty($invoice['buyer_national_id'])) {
+            $errors[] = ['code' => 'RULE_006', 'message_ar' => 'يجب تزويد الرقم الضريبي أو الوطني للمشتري للفواتير التي تتجاوز 10,000 دينار'];
+        }
+
+        // Rule 007: Discount integrity
+        $expectedSubtotal = $invoice['subtotal'] - $invoice['discount_total'];
+        // This is a simplified check for Rule 007
+        if ($expectedSubtotal < 0) {
+            $errors[] = ['code' => 'RULE_007', 'message_ar' => 'إجمالي الخصم لا يمكن أن يتجاوز المجموع الفرعي'];
+        }
+
+        return [
+            'is_valid' => empty($errors),
+            'errors' => $errors
+        ];
+    }
+}