# توثيق تسلسل الحالات (Status Workflow)

هذا المستند يوضح التسلسل المنطقي للحالات في دورة:
- الصفقة (`marketer_opportunities`)
- العرض (`marketer_opportunity_bids`)
- الفاتورة (`invoices`)
- الحجز المالي (`wallet_holds`)
- الحركة المالية (`wallet_transactions`)
- نزاعات الفواتير (`invoice_disputes`)

المرجع التشغيلي هنا من منظور نظام **المكتب العقاري ↔ المسوق** متعدد المستخدمين.

---

## 1) حالات الصفقة `marketer_opportunities.status`

### جميع الحالات
- `draft` = مسودة داخلية للمسوق (غير ظاهرة للمكتب).
- `open` = صفقة مفتوحة لاستقبال العروض.
- `bidding` = قيد التنافس/العروض.
- `closed` = أغلقت بعد الترسية النهائية.
- `expired` = انتهت المدة بدون إغلاق نهائي.
- `cancelled` = ألغيت.

### التسلسل الطبيعي
1. `draft` (داخلي للمسوق فقط)
2. `open` أو `bidding`
3. `closed` عند الترسية النهائية على فائز واحد

### تسلسل بديل
- `open/bidding` -> `expired` (انتهاء الوقت)
- `open/bidding` -> `cancelled` (إلغاء)

---

## 2) حالات العرض `marketer_opportunity_bids.status`

### جميع الحالات
- `submitted` = مقدم/فعال للمنافسة.
- `accepted` = فائز (عرض مقبول).
- `rejected` = مرفوض.
- `withdrawn` = مسحوب من المكتب.

### التسلسل الطبيعي
1. المكتب يقدم عرض: `submitted`
2. عند قرار المسوق النهائي:
   - عرض واحد فقط -> `accepted`
   - بقية العروض -> `rejected`

### سحب/تعديل العرض
- قبل القبول فقط:
  - `submitted` -> `withdrawn` (مع استرجاع الحجز)
  - `submitted` -> `submitted` (تعديل المبلغ/الملاحظات مع ضبط الحجز)

### قواعد أمان
- ممنوع تعديل أو سحب العرض بعد `accepted`.
- المكاتب لا تنفذ قبول/رفض جماعي (صلاحية المسوق فقط).

---

## 3) حالات الفاتورة `invoices.status`

> توجد قيم عربية وإنجليزية مستخدمة في النظام. يفضل التوحيد مستقبلاً على مجموعة واحدة.

### جميع الحالات المتداولة
- `pending` / `معلقة`
- `completed` / `مكتملة`
- `paid` / `مدفوعة`
- `cancelled` / `ملغاة`
- `failed` / `فاشلة`

### التسلسل المنطقي الموصى به
1. عند حجز المبلغ وانتظار تفاعل: `pending` / `معلقة`
2. عند التسوية النهائية بعد الترسية: `completed` / `مكتملة` (أو `paid` إذا سياسة النظام تعتمد المدفوعة)
3. عند إلغاء وتراجع صحيح: `cancelled` / `ملغاة`
4. عند فشل معالجة مالية: `failed` / `فاشلة`

### قاعدة مهمة
- إذا كانت الصفقة `closed` بترسية نهائية، لا يجب أن تبقى الفاتورة `pending`.

---

## 4) حالات الحجز المالي `wallet_holds.status`

### جميع الحالات
- `active` = مبلغ محجوز.
- `released` = تم تحرير/إطلاق الحجز.
- `expired` = انتهت صلاحية الحجز.
- `cancelled` = ألغي الحجز.

### الحالة المساندة
- `wallet_holds.payout_status`:
  - `pending`
  - `transferred`

### التسلسل الطبيعي
1. عند تقديم/تحديث عرض: `active`
2. عند خسارة العرض أو سحب العرض: `released` + `payout_status=pending`
3. عند التسوية النهائية للفائز: `released` + `payout_status=transferred`

---

## 5) حالات الحركة المالية `wallet_transactions`

### `type` (أنواع الحركة)
- `hold` = حجز
- `release` = تحرير
- `commit` = تسوية نهائية
- `payment` = دفع
- `refund` = استرداد
- `withdraw` = سحب
- `deposit` = إيداع
- `transfer` = تحويل

### `status` (حالة الحركة)
- `pending`
- `completed`
- `failed`
- `cancelled`

### التسلسل المرتبط بالصفقة
- رفع عرض/تقديم عرض -> `hold` (completed)
- تعديل نزولي أو سحب/خسارة -> `release` (completed)
- قبول فائز وإغلاق نهائي -> `commit` (completed)

---

## 6) حالات نزاعات الفواتير `invoice_disputes.status`

### جميع حالات النزاع (حسب تعريف الجدول)
- `جديد`
- `قيد المراجعة`
- `بانتظار الرد من الطرف الآخر`
- `قيد التفاوض`
- `مرفوع للتحكيم`
- `تحكيم قيد التنفيذ`
- `بانتظار قرار المنصة`
- `صدر قرار التحكيم`
- `مرفوض`
- `تمت التسوية`
- `انتهى قانونياً`
- `مؤرشف`
- `مغلق نهائياً`

### التسلسل الطبيعي للنزاع
1. `جديد`
2. `قيد المراجعة`
3. `بانتظار الرد من الطرف الآخر` أو `قيد التفاوض`
4. (اختياري) مسار التحكيم:
   - `مرفوع للتحكيم` -> `تحكيم قيد التنفيذ` -> `بانتظار قرار المنصة` -> `صدر قرار التحكيم`
5. إنهاء النزاع:
   - `تمت التسوية` أو `مرفوض` أو `انتهى قانونياً`
6. الأرشفة/الإغلاق:
   - `مؤرشف` -> `مغلق نهائياً`

---

## 7) التسلسل التشغيلي الكامل (End-to-End)

1. المسوق ينشر الصفقة: `open/bidding`
2. المكاتب تقدم عروض: عروض `submitted` + حجوزات `active`
3. تعديل عرض المكتب قبل القبول:
   - زيادة المبلغ -> زيادة `hold`
   - تخفيض المبلغ -> `release` جزئي
4. سحب المكتب لعرضه قبل القبول:
   - العرض -> `withdrawn`
   - الحجز -> `released`
   - الرصيد يرجع للمحفظة
5. عند قبول المسوق النهائي:
   - فائز واحد فقط -> `accepted`
   - كل الآخرين -> `rejected`
   - حجوزات الخاسرين -> `released` تلقائي
   - الصفقة -> `closed`
   - الفاتورة -> `completed/paid` (وليس `pending`)
   - حجز الفائز -> `released` مع تسوية `commit`

---

## 8) قواعد التزام (Business Rules)

- يمنع ظهور `draft` للمكتب العقاري.
- يمنع للمكتب تنفيذ إجراءات المسوق (قبول/رفض جميع العروض).
- يمنع تعديل السعر بعد قبول العرض.
- لا توجد أكثر من ترسية فائزة لنفس الصفقة.
- يجب ربط الفاتورة المرجعية مع:
  - `opportunity_id`
  - `opportunity_bid_id`
  - `wallet_hold_id`
  - `markter_id`

---

## 9) ملاحظة توحيد قياسي

لمنع تضارب القيم بين عربي/إنجليزي، يوصى باعتماد معيار موحد في قاعدة البيانات:
- إما اعتماد إنجليزي قياسي داخلي + ترجمة في الواجهة
- أو اعتماد عربي قياسي داخلي ثابت

مع طبقة Mapping واحدة في الواجهة لعرض النصوص بشكل موحد.
