# دليل اختبار سيناريو العهد وتسوياتها (Advances & Settlements)

## مقدمة عن السيناريو الأساسي
تدور دورة حياة "العهدة" (Advance) مالياً وإدارياً حول عدة مراحل رئيسية:
1. **الإنشاء (Create):** يقوم الموظف أو المسؤول بإنشاء طلب العهدة.
2. **الاعتماد (Approve):** تعتمد الإدارة أو المدير المباشر هذه العهدة للبدء في استخدامها.
3. **تسجيل المعاملات / الفواتير (Record Transactions):** يتم تسجيل الفواتير والمصروفات التي سُحبت من هذه العهدة.
4. **الصرف / الدفع (Disburse):** يتم تسليم المبلغ الفعلي للموظف كدفعة نقدية (أو تحويل) بناءً على ما تم اعتماده للعهدة.
5. **التسوية والإغلاق (Settlement / Close):** حالة العهدة تتغير بناءً على مقارنة المبالغ المصروفة مالياً (Disbursements) بالمبالغ المستهلكة/المفوترة فعلياً (Expenses).

## آخر التغييرات التي تمت على النظام (Why the update?)
في السابق كانت دورة العمل في النظام تُجبر المستخدم على صرف الدفعة (Disbursement) فوراً بعد الاعتماد لكي تبدأ حالة العهدة بالتحول إلى `disbursed` ويسمح لك لاحقاً بإضافة الفواتير أو المصروفات الخاصة بها.

**الفوائد والتحديثات الجديدة:**
أصبح النظام الآن يعكس الواقع المالي بشكل أكثر مرونة:
- **إمكانية تسجيل الفواتير مبكراً:** يمكن الآن استدعاء وتوثيق المعاملات والفواتير المشتراة (Record Transactions) **مباشرة بعد الاعتماد (Approved)** وحتى قبل أن تقوم الإدارة المالية بصرف المبالغ وتصرفها كسيولة فعلية (Disbursement).
- **إدارة ديناميكية للحالات:** تبقى حالة العهدة "معتمدة" (`approved`) حتى يتم صرف أموال حقيقية بداخلها، ولن يتم كسر حالة العهدة.
- **تحديث تلقائي لحالة التسوية:** عند اتخاذ قرار الدفع (Disbursement) أخيراً، سيقوم النظام تلقائياً بقراءة كافة الفواتير التي تمت جدولتها مُسبقاً في الفترة السابقة، وسيحول حالة العهدة تلقائياً بناءً على العمليات الحسابية إمّا لـ `partially_settled` (مسّواة جزئياً) أو `fully_settled` (مسوّاة بالكامل).
- **منع طلبات التعويض الخاطئة:** تم منع النظام من إنشاء طلبات تعويض (Compensation Requests) وهميّة للموظفين في حال كانت المصروفات المسجلة أكبر من الـ `0` ولكن الإدارة لم تقم بصرف أي ريال للاعتماد كدفعة تأسيسية بعد (`$totalDisbursed == 0`).

---

## الروابط (Endpoints) للواجهة البرمجية (API) المُستخدمة

جميع المسارات تبدأ بـ `/api/v1/construction`

| العملية | المسار (Endpoint) | الطريقة (Method) | الوصف |
|---------|-------------------|------------------|-------|
| 1. الإنشاء | `/advances` | `POST` | لإنشاء العهدة الجديدة. |
| 2. الاعتماد | `/advances/{id}/approve` | `POST` | الموافقة على العهدة. |
| 3. تسجيل معاملة | `/advances/{id}/transactions` | `POST` | إضافة الفواتير/المشتريات على العهدة. |
| 4. الصرف | `/advances/{id}/disburse` | `POST` | صرف مبالغ مالية العهدة للموظف. |
| 5. الإغلاق/التسوية | `/advances/{id}/close` | `POST` | إنهاء وتسوية العهدة بالكامل. |

*(يتم استبدال `{id}` برقم العهدة الفعلي المفحوص)*

---

## حالات الاختبار (Test Cases)

يجب على المختبر التركيز على الحالات التالية للتأكد من سلامة السيناريو الجديد والقديم:

### ✅ [الحالة الأولى] دورة العمل الجديدة (السير المالي الحديث والتسجيل المُبكر)
1. **الإنشاء:** أرسل طلب `POST /advances` مع تحديد النوع كعهدة مالية وبمبلغ معين (مثلاً 1000). وتأكد أن الحالة الابتدائية هي `pending`.
2. **الاعتماد:** أرسل طلب `POST /advances/{id}/approve`. بعد نجاح الطلب، تأكد أن الحالة أصبحت `approved`.
3. **التسجيل المسبق للفواتير:** قبل إجراء أي خطوة للصرف، أرسل طلب `POST /advances/{id}/transactions` بمصاريف قيمتها مثلاً (400).
   - **النتيجة المتوقعة:** 
     - النظام يقبل تسجيل المعاملة بنجاح دون أخطاء برمجية.
     - يجب أن تبقى حالة العهدة الأساسية `approved` (لأن الصرف الإجمالي هو صفر لم نقم بصرف أي أموال).
     - يتم حفظ العملية كمصاريف (`expenses`) بمبلغ 400.
4. **تفعيل الصرف:** أرسل طلب `POST /advances/{id}/disburse` لنفس العهدة وبمبلغ صرف يعادل مثلاً (800).
   - **النتيجة المتوقعة:** 
     - النظام يقبل الصرف.
     - الدالة الداخلية تستدعي حالة التسويات (Settlements) وتقوم بتغيير حالة العهدة من `approved` إلى `partially_settled`.

### ✅ [الحالة الثانية] دورة العمل القديمة (التراجع والتحقق للحفاظ على المسبق)
للتأكد أن سير العمل السابق والمتعارف عليه لن يتعطل بسبب التدقيق الجديد:
1. قم بإنشاء واعتماد عهدة بقيمة 1000.
2. قم بالصرف مباشرةً `POST /advances/{id}/disburse` بقيمة كامل الملبغ (1000).
   - *النتيجة:* تصبح الحالة `disbursed`.
3. قم بتسجيل المعاملات `POST /advances/{id}/transactions` بمبالغ متفرقة مثلاً 500 ثم 200.
   - *النتيجة المتوقعة:* النظام يقبل الحركات وتستمر حالة التسوية في التفاعل كالمعتاد طالما الصرف أكبر من الصفر. يتغير الوضع إلى `partially_settled`.

### ✅ [الحالة الثالثة] اختبار مانع التعويض المبكر (No Pre-mature Compensation Request)
للتأكد أن النظام لا يولد مشكلة الدفع الزائد التلقائي:
1. إنشاء واعتماد عهدة.
2. تسجيل فاتورة `POST /advances/{id}/transactions` بمبلغ 500 (وتذكر انه حتى اللحظة لم يتم عمل أي Disburse).
3. **النتيجة المتوقعة:** يجب ألا يقوم النظام بإنشاء أي إشعار أو طلب بقاعدة بيانات "طلبات التعويض" (CompensationRequest). ويجب أن يتم إنهاء نقطة الفحص بنجاح بدون فشل.