refactor: migrate amount fields to decimal and implement location service restriction for unsupported regions

payment_server/WalletDB.sql

@@ -118,7 +118,7 @@ CREATE TABLE `driverWallet` (
   `driverID` varchar(100) NOT NULL,
   `paymentID` varchar(200) NOT NULL,
   `dateCreated` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
-  `amount` varchar(10) CHARACTER SET latin1 COLLATE latin1_swedish_ci NOT NULL,
+  `amount` decimal(12,3) NOT NULL,
   `paymentMethod` varchar(20) NOT NULL,
   `dateUpdated` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP
 ) ENGINE=InnoDB DEFAULT CHARSET=latin1;
@@ -528,7 +528,7 @@ CREATE TABLE `siroWallet` (
   `id` int NOT NULL,
   `driverId` varchar(100) NOT NULL,
   `passengerId` varchar(100) NOT NULL,
-  `amount` varchar(10) NOT NULL,
+  `amount` decimal(12,3) NOT NULL,
   `paymentMethod` varchar(50) NOT NULL,
   `token` varchar(100) NOT NULL,
   `createdAt` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP

payment_server/migrations/2026_07_24_fix_wallet_amount_varchar.sql

@@ -0,0 +1,29 @@
+-- 2026_07_24_fix_wallet_amount_varchar.sql
+-- Siro audit S5 (docs/21 في Tripz): driverWallet.amount و siroWallet.amount كانا varchar(10)
+-- — المال مخزَّن نصاً و SUM() يُجري جمعاً نصياً. يوسّعهما إلى DECIMAL(12,3) NOT NULL.
+--
+-- آمن رجعياً: كل الإدخالات الحالية في الكود تمرّر أرقاماً (موجبة أو سالبة) عبر PDO
+-- params، فلا قيمة نصية غير رقمية موجودة فعلياً. DECIMAL(12,3) يحتفظ بالإشارة
+-- (driverWallet يخزّن دفتر أستاذ بقيود موجبة وسالبة، لا رصيداً تراكمياً) — لذلك
+-- لا CHECK (amount >= 0) هنا، خلافاً لعمود الرصيد التراكمي في Tripz.
+--
+-- التطبيق: mysql < 2026_07_24_fix_wallet_amount_varchar.sql
+-- التراجع: انظر نهاية الملف (معلَّق، فعّله يدوياً عند الحاجة فقط)
+
+START TRANSACTION;
+
+ALTER TABLE `driverWallet`
+  MODIFY COLUMN `amount` DECIMAL(12,3) NOT NULL;
+
+ALTER TABLE `siroWallet`
+  MODIFY COLUMN `amount` DECIMAL(12,3) NOT NULL;
+
+COMMIT;
+
+-- ── تحقّق يدوي بعد التنفيذ ─────────────────────────────────────────
+-- SELECT driverID, SUM(amount) AS balance FROM driverWallet GROUP BY driverID LIMIT 5;
+-- تأكد أن balance رقم صحيح منطقي (لا نص مبتور كما كان يحدث مع SUM() على varchar).
+
+-- ── تراجع (لا يُنفَّذ تلقائياً) ─────────────────────────────────────
+-- ALTER TABLE `driverWallet` MODIFY COLUMN `amount` VARCHAR(10) CHARACTER SET latin1 COLLATE latin1_swedish_ci NOT NULL;
+-- ALTER TABLE `siroWallet`   MODIFY COLUMN `amount` VARCHAR(10) NOT NULL;

payment_server/v2/main/sms_webhook/finalize_payout.php

@@ -53,13 +53,16 @@ if (!function_exists('finalizePayout')) {
      * تقوم بتسجيل كل المعاملات في محافظ السائق والشركة وتحديث حالة الدفعات.
      */
     function finalizePayout(PDO $con, int $payoutId) {
+        global $encryptionHelper;
         logPayoutError("START", "Starting finalization for payout ID: {$payoutId}");
 
+        $inTransaction = false;
+
         try {
             // 1. جلب بيانات طلب السحب المكتمل
             $stmt = $con->prepare("SELECT * FROM `payout_requests` WHERE id = :id AND status = 'completed' LIMIT 1");
             $stmt->execute([':id' => $payoutId]);
-            $payout = $stmt->fetch(PDO::FETCH_ASSOC); 
+            $payout = $stmt->fetch(PDO::FETCH_ASSOC);
 
             if (!$payout) {
                 logPayoutError("FETCH_PAYOUT", "Payout request not found or not completed.", ['payoutId' => $payoutId]);
@@ -87,6 +90,10 @@ if (!function_exists('finalizePayout')) {
             $netAmount = (float)$payout['amount']; // The amount requested
             $totalDeducted = $netAmount + $payoutFee; // Total deducted
 
+            // --- S4 Fix: كل الكتابات (2–6) في معاملة واحدة، مع تراجع كامل عند أي فشل ---
+            $con->beginTransaction();
+            $inTransaction = true;
+
             // 2. إنشاء معرف دفع رئيسي لهذه المعاملة
             // نسجل المبلغ الإجمالي المخصوم بالسالب
             $paymentID = generatePaymentID($con, $driverId, -$totalDeducted, 'payout');
@@ -102,11 +109,12 @@ if (!function_exists('finalizePayout')) {
             // 4. Update the reserved deduction in driverWallet with the real paymentID
             $updateDriver = $con->prepare("UPDATE driverWallet SET paymentID = :paymentID, paymentMethod = 'payout' WHERE driverID = :driverID AND paymentMethod = 'payout_reserved' AND amount = :amount LIMIT 1");
             $updateDriver->execute([
-                ':driverID' => $driverId, 
+                ':driverID' => $driverId,
                 ':paymentID' => $paymentID,
                 ':amount' => -$totalDeducted
             ]);
-            
+            if ($updateDriver->rowCount() === 0) throw new Exception('No matching reserved driverWallet row to finalize');
+
             $con->prepare("UPDATE payment_tokens SET isUsed = TRUE WHERE token = :token")->execute([':token' => $tokenDriver]);
             logPayoutError("DRIVER_WALLET", "Updated reserved transaction of {$totalDeducted} in driverWallet.");
 
@@ -122,17 +130,24 @@ if (!function_exists('finalizePayout')) {
             if ($insertSiro->rowCount() === 0) throw new Exception('Insert to siroWallet failed');
             $con->prepare("UPDATE payment_tokens SET isUsed = TRUE WHERE token = :token")->execute([':token' => $tokenSiro]);
             logPayoutError("SIRO_WALLET", "Fee transaction of {$payoutFee} recorded in siroWallet.");
-            
+
             // 6. تحديث حالة الدفعات التي تم سحبها في جدول 'payments'
-            // هذا السطر يقوم بتحديث كل الدفعات المعلقة للسائق، معتبراً أن عملية السحب تغطيها
+            // السائق يسحب رصيده الكامل فقط (لا خيار سحب جزئي في التطبيق)، لذلك
+            // تحديث كل الدفعات المعلّقة لهذا السائق صحيح دائماً عند وصولنا هذه الخطوة.
             $updatePayments = $con->prepare("UPDATE payments SET isGiven = TRUE WHERE driverID = :driverId AND isGiven = FALSE");
             $updatePayments->execute([':driverId' => $driverId]);
             logPayoutError("UPDATE_PAYMENTS", "Marked pending payments as 'isGiven' for driver {$driverId}. Rows affected: " . $updatePayments->rowCount());
 
+            $con->commit();
+            $inTransaction = false;
+
             logPayoutError("SUCCESS", "Payout finalization completed successfully for payout ID: {$payoutId}");
             return true;
 
         } catch (Throwable $e) {
+            if ($inTransaction && $con->inTransaction()) {
+                $con->rollBack();
+            }
             logPayoutError("EXCEPTION", "An exception occurred: " . $e->getMessage(), ['payoutId' => $payoutId]);
             return false;
         }