# توثيق قاعدة البيانات — Database Schema

**DB:** `saiadmin_sudb999` | **Engine:** InnoDB | **Charset:** utf8mb4_unicode_ci  
**Tables:** 109 (97 original + 12 migration)

---

## مجموعات الجداول

### 👤 Users & Auth (7 جداول)
| الجدول | الوصف | الحجول الرئيسية |
|--------|-------|----------------|
| `users` | المستخدمون | id, phone, email, plan_key, wallet_balance, provider_verified |
| `staff_members` | فريق الإدارة | id, username, password_hash, role |
| `provider_profiles` | ملفات المزودين | id, user_id, specialty, rating, is_verified |
| `user_subscriptions` | سجل الاشتراكات | id, user_id, plan_key, started_at, expires_at |
| `subscription_plans` | خطط الاشتراك | plan_key, price_sdg, ai_limit, doc_credit_sdg |
| `subscription_credits` | رصيد وثائق شهري | user_id, remaining_sdg, period_month, period_year |
| `achievement_badges` | شارات الإنجاز | badge_key, name_ar, icon, points |

### 💰 Finance & Billing (12 جدول)
| الجدول | الوصف |
|--------|-------|
| `wallet` | محفظة المستخدم (balance + hold_balance) |
| `wallet_transactions` | سجل المعاملات |
| `invoices` | الفواتير |
| `payment_receipts` | إيصالات الدفع |
| `payment_proofs` | إثبات الدفع |
| `billing_reserves` | حجوزات BillingEngine |
| `financial_ledger` | دفتر الأستاذ العام |
| `financial_entries` | القيود المحاسبية |
| `platform_settings` | إعدادات التسعير (26 إعداد) |
| `exchange_rates` | سجل سعر الصرف |
| `document_prices` | أسعار الوثائق (10 أنواع × 3 خطط) |
| `provider_payouts` | مستحقات المزودين |

### 📅 Bookings & Services (8 جداول)
| الجدول | الوصف |
|--------|-------|
| `bookings` | الحجوزات الرئيسية |
| `consultation_sessions` | جلسات الاستشارة |
| `consultation_messages` | رسائل المحادثة |
| `service_catalog` | فهرس الخدمات |
| `provider_availability` | جدول توافر المزودين |
| `booking_reviews` | تقييمات الحجوزات |
| `events` | الفعاليات |
| `service_requests` | طلبات الخدمة |

### 🤖 AI & Engine (10 جداول)
| الجدول | الوصف |
|--------|-------|
| `execution_log` | سجل كل طلب AI |
| `flow_sessions` | جلسات الـ StepController |
| `flow_messages` | رسائل الـ flows |
| `policy_versions` | سياسات PolicyEngine |
| `ai_feedback` | تقييم ردود AI |
| `ie_rules_override` | تجاوزات قواعد IE |
| `kv_cache` | كاش مفاتيح-قيم |
| `rate_limits` | حدود معدل الطلبات |
| `fraud_flags` | علامات الاحتيال |
| `audit_logs` | سجل العمليات الإدارية |

### 🏢 Corporate & B2B (4 جداول)
| الجدول | الوصف |
|--------|-------|
| `corporate_inquiries` | طلبات حلول الشركات (30 حقل) |
| `corporate_proposals` | الدراسات المولَّدة بالـ AI |
| `corporate_services_catalog` | فهرس خدمات الشركات |
| `investment_applications` | طلبات الاستثمار |

### 💡 Suggestions & Community (5 جداول)
| الجدول | الوصف |
|--------|-------|
| `user_suggestions` | مقترحات المستخدمين (30 حقل) |
| `suggestion_votes` | التصويت على المقترحات |
| `support_tickets` | تذاكر الدعم الفني |
| `support_ticket_replies` | ردود التذاكر |
| `content_reports` | بلاغات المحتوى |

### 📄 BDE & Documents (5 جداول)
| الجدول | الوصف |
|--------|-------|
| `bde_documents` | الوثائق التجارية المولَّدة |
| `bde_templates` | قوالب الوثائق (7 قوالب) |
| `contracts` | العقود |
| `legal_briefs` | المذكرات القانونية |
| `translations` | الترجمات |

### 🌍 Community & Market (6 جداول)
| الجدول | الوصف |
|--------|-------|
| `market_items` | منتجات سوق الجيران |
| `pulse_posts` | منشورات نبض الحي |
| `posts` | المنشورات العامة |
| `community_initiatives` | المبادرات المجتمعية |
| `neighborhood_zones` | الأحياء السودانية (18 ولاية) |
| `pharmacy_registry` | قائمة الصيدليات |

### 🔔 Notifications (2 جدول)
| الجدول | الوصف |
|--------|-------|
| `notifications` | إشعارات المستخدمين |
| `fcm_tokens` | رموز Firebase |

### 📊 CRM & Marketing (4 جداول)
| الجدول | الوصف |
|--------|-------|
| `crm_notes` | ملاحظات CRM |
| `crm_timeline` | سجل أحداث CRM |
| `broadcast_logs` | سجل البث الجماعي |
| `inquiries` | استفسارات عامة |

---

## الجداول الحرجة — تفصيل

### users
```sql
CREATE TABLE users (
  id                 INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  phone              VARCHAR(20) UNIQUE NOT NULL,
  email              VARCHAR(200) UNIQUE,
  full_name          VARCHAR(150) NOT NULL,
  password_hash      VARCHAR(255) NOT NULL,
  plan_key           ENUM('free','plus','pro','corp') DEFAULT 'free',
  user_type          ENUM('user','provider','admin','staff','mod') DEFAULT 'user',
  provider_verified  TINYINT(1) DEFAULT 0,
  achievement_points INT UNSIGNED DEFAULT 0,
  kyc_level          TINYINT DEFAULT 0,
  created_at         DATETIME DEFAULT CURRENT_TIMESTAMP
);
```

### wallet
```sql
CREATE TABLE wallet (
  id             INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  user_id        INT UNSIGNED UNIQUE NOT NULL,
  balance        DECIMAL(12,2) DEFAULT 0.00,
  hold_balance   DECIMAL(12,2) DEFAULT 0.00,  -- BillingEngine holds
  total_earned   DECIMAL(12,2) DEFAULT 0.00,
  total_spent    DECIMAL(12,2) DEFAULT 0.00,
  updated_at     DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```

### wallet_transactions (ref_type)
```sql
ref_type ENUM(
  'topup',          -- شحن المحفظة
  'booking',        -- حجز خدمة
  'payout',         -- صرف للمزود
  'transfer',        -- تحويل
  'refund',          -- استرداد
  'commission',      -- عمولة المنصة
  'subscription',    -- اشتراك شهري
  'doc_issuance',    -- إصدار وثيقة
  'credit_deduct',   -- خصم رصيد
  'corporate'        -- دفعة شركة
)
```

### platform_settings (19 إعداد رئيسي)
```
usd_to_sdg_rate          = 4100     ← المحرك الرئيسي للتسعير
sub_plus_price_sdg        = 20000   ← سعر Plus
sub_pro_price_sdg         = 50000   ← سعر Pro
credit_plus_sdg           = 15000   ← رصيد وثائق Plus
credit_pro_sdg            = 50000   ← رصيد وثائق Pro
corp_starter_base_usd     = 99
corp_business_base_usd    = 249
corp_scale_base_usd       = 599
commission_rate           = 0.10    ← 10% عمولة
pay_limit_free_daily_sdg  = 20000
pay_limit_plus_daily_sdg  = 200000
```

### user_suggestions (نظام المقترحات)
```sql
type    ENUM('improvement','bug','solution','new_service','positive')
status  ENUM('pending','under_review','accepted','rejected','implemented','duplicate')
priority_label ENUM('urgent','high','medium','low','duplicate','out_of_scope')
-- Agent analysis fields:
priority_score, ai_summary, affected_estimate,
effort_level, effort_hours, revenue_impact,
team_responsible, risk_level, roadmap_quarter
```

---

## العلاقات الرئيسية (ERD المبسَّط)

```
users ──────────────────────┐
  │                         │
  ├── wallet (1:1)          │
  ├── bookings (1:N)        │
  ├── user_subscriptions    │
  ├── subscription_credits  │
  ├── user_suggestions      │
  └── notifications         │
                            │
bookings ───────────────────┤
  │                         │
  ├── invoices (1:1)        │
  ├── consultation_sessions │
  └── booking_reviews       │
                            │
invoices ───────────────────┤
  ├── payment_receipts      │
  └── payment_proofs        │
                            │
corporate_inquiries ────────┘
  └── corporate_proposals (1:1)
```

---

## ترتيب التشغيل (Setup Order)

```bash
1. sudanna_v22_schema_complete.sql  # 97 جدول أصلي
2. migration_fix.sql                # 12 جدول جديد + ALTER
3. seed.sql                         # البيانات الأولية
```

---

## Indexes المهمة

```sql
-- أداء الاستعلامات الشائعة
execution_log: INDEX (user_id, created_at)
bookings:      INDEX (provider_id, status, slot_time)
user_suggestions: INDEX (status, priority_label, votes_count)
platform_settings: UNIQUE (setting_key)
exchange_rates:    INDEX (is_active, created_at)
```
