-- ============================================================
-- سجل خصومات الالتزامات — الطرف المالي من محرك الالتزامات
--
-- ‏لماذا جدول جديد بدل إعادة استخدام `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;