Update: 2026-08-08 12:58:16

payment_server/migrations/2026_08_08_obligation_settlements.sql

@@ -0,0 +1,49 @@
+-- ============================================================
+-- سجل خصومات الالتزامات — الطرف المالي من محرك الالتزامات
+--
+-- ‏لماذا جدول جديد بدل إعادة استخدام `add_s2s_reward.php`؟
+--
+-- ‏لأن تلك النقطة لا تضمن عدم التكرار. لا مفتاح فريد على
+-- ‏`driverWallet.paymentID`، ولا فحص تكرار فيها إلا لتحديات
+-- ‏`daily_/weekly_`. تعليق `backend/food/admin/courier_settlement.php`
+-- ‏يقول إن paymentID «يمنع ازدواج الصرف عند إعادة المحاولة» — وهذا غير
+-- ‏صحيح، لا شيء في الكود ولا في المخطّط يفرضه.
+--
+-- ‏وهذا مقبول تقريباً للإيداعات (إيداع مكرّر خطأ يُسترد)، وغير مقبول
+-- ‏إطلاقاً للخصومات: محرك التسوية يعيد المحاولة بطبعه، وخصم مكرّر من
+-- ‏رصيد سائق هو أسوأ عطل ممكن في المنصة — يفقد ثقته ولا يعود.
+--
+-- ‏ولا يمكن ببساطة إضافة مفتاح فريد على `driverWallet.paymentID`: الجدول
+-- ‏يحمل سنوات من صفوف قد تحمل معرّفات مكرّرة أصلاً، وإضافة القيد قد تفشل
+-- ‏أو تكسر مسارات دفع قائمة. فالضمان يُبنى هنا، خارجه.
+--
+-- ‏العقد: صفّ واحد لكل `settlement_ref`. محاولة ثانية بنفس المرجع لا
+-- ‏تخصم شيئاً وتُرجع نتيجة المحاولة الأولى كما هي.
+-- ============================================================
+
+CREATE TABLE IF NOT EXISTS `obligation_settlements` (
+  `id`              INT NOT NULL AUTO_INCREMENT,
+
+  -- ‏المرجع الذي يبنيه محرك التسوية: obl_{ledgerId}_{attempts}
+  -- ‏مبنيّ على عدّاد المحاولات لا على التاريخ، لأن العدّاد لا يزيد إلا
+  -- ‏بعد تحديث دفتر الالتزامات بنجاح: نداء نجح هنا وضاع ردّه في الطريق
+  -- ‏يُعاد لاحقاً بالمرجع نفسه فيستردّ نتيجته الأولى. مرجعٌ مبنيّ على
+  -- ‏التاريخ كان سيصل غداً بمرجع جديد ويخصم المبلغ مرتين.
+  `settlement_ref`  VARCHAR(120) NOT NULL,
+
+  `driver_id`       VARCHAR(100) NOT NULL,
+  `product_code`    VARCHAR(60)  NOT NULL,
+
+  `requested_amount` DECIMAL(12,3) NOT NULL COMMENT 'ما طلبه المحرك',
+  `deducted_amount`  DECIMAL(12,3) NOT NULL COMMENT 'ما خُصم فعلاً بعد السقف',
+
+  -- ‏لقطة الأساس الذي حُسب عليه السقف. بدونها لا يمكن لاحقاً شرح
+  -- ‏«لماذا خُصم ثلاثة لا خمسة؟» — والسائق سيسأل.
+  `day_earnings`    DECIMAL(12,3) NOT NULL DEFAULT 0,
+  `cap_percent`     DECIMAL(5,2)  NOT NULL DEFAULT 0,
+
+  `created_at`      TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uq_settlement_ref` (`settlement_ref`),
+  KEY `idx_driver_date` (`driver_id`, `created_at`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;