# Database Design — Financing Application Management System

نظام ديناميكي قابل للتهيئة بالكامل من لوحة الإدارة. لا توجد حقول/مستندات/ضمانات Hardcoded —
كلها تُعرّف عبر **configuration tables**.

---

## 1) Text ERD (Entities & Relationships)

```
┌──────────────────────────── ACCESS CONTROL ────────────────────────────┐
users ──< model_has_roles >── roles ──< role_has_permissions >── permissions   (Spatie)
users 1───* applications (assigned_to / created_by)
users 1───* audit_logs
└────────────────────────────────────────────────────────────────────────┘

┌──────────────────────── CONFIGURATION (Dynamic) ───────────────────────┐
finance_products 1───* product_form_fields *───1 form_fields
finance_products 1───* document_checklists *───1 required_documents
finance_products 1───* finance_product_guarantees *───1 guarantees
application_statuses  (self-referential via allowed_transitions JSON)
funding_entities
└────────────────────────────────────────────────────────────────────────┘

┌──────────────────────────── APPLICANTS ────────────────────────────────┐
customers (individual)  ─┐
                         ├─< applications (polymorphic: applicant_type/applicant_id)
companies (business)    ─┘
leads 1───0..1 applications        leads *───1 customers / finance_products
└────────────────────────────────────────────────────────────────────────┘

┌──────────────────────────── APPLICATION CORE ──────────────────────────┐
applications *───1 finance_products
applications *───1 application_statuses (current_status_id)
applications *───1 funding_entities (nullable)

applications 1───* application_field_values   *───1 form_fields      (EAV answers)
applications 1───* application_stage_logs      *───1 application_statuses (from/to)
applications 1───* application_notes
applications 1───* application_documents       *───1 required_documents
                                               *───1 attachments
applications 1───1 application_financial_data
applications 1───* application_credit_analysis
applications 1───* application_funding_offers  *───1 funding_entities
applications 1───* application_approvals
applications 1───1 contracts                   *───0..1 application_funding_offers
└────────────────────────────────────────────────────────────────────────┘

┌──────────────────────────── CROSS-CUTTING ─────────────────────────────┐
attachments  (polymorphic: attachable_type/attachable_id — any model)
audit_logs   (polymorphic: auditable_type/auditable_id + ip/user_agent)
activity_log (Spatie — model change log)
└────────────────────────────────────────────────────────────────────────┘
```

---

## 2) Tables (25) and their role

| # | Table | Type | Role |
|---|-------|------|------|
| 1 | users | core | الموظفون (+ Spatie roles) |
| 2 | roles / permissions / … | Spatie | الأدوار والصلاحيات |
| 3 | customers | applicant | الأفراد |
| 4 | companies | applicant | المنشآت |
| 5 | finance_products | **config** | المنتجات التمويلية |
| 6 | guarantees | **config** | كتالوج الضمانات |
| 7 | finance_product_guarantees | **config pivot** | ضمانات كل منتج |
| 8 | funding_entities | **config** | جهات التمويل |
| 9 | form_fields | **config** | كتالوج الحقول الديناميكية |
| 10 | product_form_fields | **config pivot** | حقول كل منتج (section/required/order) |
| 11 | required_documents | **config** | كتالوج المستندات |
| 12 | document_checklists | **config pivot** | مستندات كل منتج |
| 13 | application_statuses | **config** | الحالات + الانتقالات المسموحة |
| 14 | leads | sales | العملاء المحتملون |
| 15 | applications | core | الطلب المركزي (applicant polymorphic) |
| 16 | application_field_values | EAV | قيم الحقول الديناميكية المُدخلة |
| 17 | application_stage_logs | audit | سجل انتقالات الحالة |
| 18 | application_notes | data | ملاحظات الطلب |
| 19 | attachments | polymorphic | الملفات الفيزيائية |
| 20 | application_documents | data | مستندات الطلب + حالة المراجعة |
| 21 | application_financial_data | data (1:1) | البيانات المالية المُهيكلة |
| 22 | application_credit_analysis | data | التحليل الائتماني |
| 23 | application_funding_offers | data | عروض جهات التمويل |
| 24 | application_approvals | data | موافقات المراجعة |
| 25 | contracts | data | العقود/الطباعة |
| + | audit_logs | audit | سجل التدقيق العام |

> `application_field_values` أُضيف كجدول داعم ضروري لمنظومة الحقول الديناميكية
> (لا معنى لـ form_fields/product_form_fields بدون مكان لتخزين القيم).

---

## 3) كيف يصبح كل شيء ديناميكيًا؟

**حقول مختلفة لكل منتج:** عرّف الحقل مرة في `form_fields`، ثم اربطه بالمنتج في
`product_form_fields` مع (section, is_required, sort_order, overrides). عند فتح طلب
لمنتج ما، يُبنى النموذج من هذه السجلات، وتُخزَّن الإجابات في `application_field_values`.

**مستندات مختلفة لكل منتج:** `required_documents` (الكتالوج) + `document_checklists`
(أي مستند لأي منتج + إلزامي/شرطي). تُنشأ صفوف `application_documents` بناءً عليها.

**ضمانات مختلفة لكل منتج:** `guarantees` + `finance_product_guarantees`
(is_required + condition).

**حالات قابلة للتهيئة:** `application_statuses` تحمل اللون والترتيب و
`allowed_transitions` (JSON بأكواد الحالات التالية) — أي يمكن إعادة رسم
الـ workflow من اللوحة دون كود.

---

## 4) Workflow (data-driven)

```
draft → submitted → operations_review → credit_review → management_review
      → approved → sent_to_funding_entity → contract_printed → completed

فروع: operations_review → missing_documents (↺) | rejected
       credit_review → missing_documents (↺) | rejected
       management_review → rejected
```

كل انتقال يُكتب في `application_stage_logs (from_status_id, to_status_id, action,
performed_by, comment)`. الانتقالات المسموحة تُقرأ من `application_statuses.allowed_transitions`.