# سودانا AI OS v23 — Sudanna AI Operating System

<div align="center">

![Version](https://img.shields.io/badge/version-v23-00d97e)
![PHP](https://img.shields.io/badge/PHP-8.1+-blue)
![MySQL](https://img.shields.io/badge/MySQL-8.0+-orange)
![License](https://img.shields.io/badge/license-Proprietary-red)

**منصة ذكاء اصطناعي متكاملة للسودان — 14 مساعد · 610 قاعدة استدلال · 95 API endpoint**

[📖 التوثيق](#التوثيق) · [🚀 البدء السريع](#البدء-السريع) · [🔌 API](#api) · [🏗️ المعمارية](#المعمارية)

</div>

---

## نظرة عامة

سودانا هو نظام تشغيل ذكاء اصطناعي متكامل مصمم للسوق السوداني. يُقدِّم خدمات الطب عن بعد، الاستشارات القانونية، التوثيق التجاري، حلول الشركات، ومقترحات المستخدمين — كل ذلك عبر محركات AI متخصصة ومحكومة بـ HARD GATE للحماية.

## الأرقام الرئيسية

| المؤشر | القيمة |
|--------|--------|
| PHP files | 184 |
| Engine classes | 40 |
| API endpoints | 95 |
| Database tables | 109 |
| IE inference rules | 610 |
| AI assistant domains | 14 |
| PolicyEngine cases | 28 |
| Active flows | 9 |
| Admin panel tabs | 39 |
| Exchange rate | 1 USD = 4,100 SDG |

---

## متطلبات التشغيل

### Server Requirements
```
OS:           Ubuntu 22.04+ / Debian 11+
PHP:          8.1+ (with extensions: pdo_mysql, mbstring, json, curl, zip, gd)
MySQL:        8.0+ (or MariaDB 10.6+)
Nginx:        1.18+ (recommended) or Apache 2.4+
RAM:          Minimum 2GB (4GB recommended)
Storage:      20GB SSD minimum
SSL:          Required (Let's Encrypt)
```

### PHP Extensions Required
```bash
php8.1-fpm php8.1-mysql php8.1-mbstring php8.1-curl
php8.1-json php8.1-zip php8.1-gd php8.1-xml php8.1-intl
```

### External Services
```
AI Providers:   Google Gemini API (primary) · Claude API (secondary) · OpenAI (fallback)
Payment:        Sudan payment gateway (HMAC webhook)
SMS/Email:      SMTP server
Push:           Firebase Cloud Messaging (FCM)
```

---

## البدء السريع

### 1. استنساخ المشروع
```bash
git clone https://github.com/sudanna/ai-os.git /var/www/sudanna
cd /var/www/sudanna
```

### 2. إعداد قاعدة البيانات
```bash
mysql -u root -p -e "CREATE DATABASE saiadmin_sudb999 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -u root -p saiadmin_sudb999 < sudanna_v22_schema_complete.sql
mysql -u root -p saiadmin_sudb999 < migration_fix.sql
mysql -u root -p saiadmin_sudb999 < seed.sql
```

### 3. إعداد config.php
```php
// في config.php — عدِّل هذه القيم:
define('DB_HOST', 'localhost');
define('DB_NAME', 'saiadmin_sudb999');
define('DB_USER', 'your_db_user');
define('DB_PASS', 'your_db_password');
define('SITE_URL', 'https://yourdomain.com/s26');

// AI API Keys
define('GEMINI_API_KEY',  'your_gemini_key');
define('CLAUDE_API_KEY',  'your_claude_key');
define('OPENAI_API_KEY',  'your_openai_key');

// Exchange rate (admin-controlled via platform_settings)
define('USD_TO_SDG_RATE', 4100);
```

### 4. إعداد Nginx
```nginx
server {
    listen 443 ssl http2;
    server_name yourdomain.com;
    root /var/www/sudanna;
    index index.html index.php;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.1-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~* \.(js|css|png|jpg|gif|ico|svg|woff2)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}
```

### 5. التحقق من التشغيل
```bash
php /var/www/sudanna/go_live_proof.php
# يجب أن يُعيد: ✅ 184 PHP files valid | 0 errors
```

---

## هيكل المشروع

```
sudanna/
├── engine/                    # 40 محرك PHP
│   ├── Gateway.php            # نقطة الدخول الوحيدة
│   ├── AssistantEngine.php    # 14 domain + routing
│   ├── InferenceEngine.php    # 610 rules + 19 sector
│   ├── BillingEngine.php      # Hold model + chargeDocument
│   ├── FinancialAgent.php     # Double-entry ledger
│   ├── PolicyEngine.php       # 28 case + DSL
│   ├── StepController.php     # 9 flows
│   ├── PricingEngine.php      # Exchange rate + SDG pricing
│   ├── CorporateAgent.php     # B2B analysis + ROI
│   └── SuggestionsAgent.php   # Feedback analysis + Jaccard
│
├── api/                       # 95 API endpoint
│   ├── public/                # عام — لا auth
│   ├── auth/                  # تسجيل + دخول
│   ├── booking/               # حجوزات
│   ├── payment/               # مدفوعات
│   ├── corporate/             # حلول الشركات
│   ├── suggestions/           # مقترحات المستخدمين
│   ├── subscription/          # اشتراكات
│   └── admin/                 # لوحة الإدارة
│
├── app/                       # شاشات المستخدم
│   ├── medical.php            # الطب عن بعد
│   ├── legal.php              # الاستشارات القانونية
│   ├── corporate-solutions.php # حلول الشركات (5-phase wizard)
│   └── suggestions.php        # مقترحات المستخدمين
│
├── admin.php                  # لوحة الإدارة (39 tab)
├── index.html                 # الصفحة الرئيسية
├── hub.html                   # Hub المنصة
├── developer.html             # بوابة المطورين (13 tab)
├── config.php                 # الإعدادات المركزية
├── sudanna_v22_schema_complete.sql  # 97 جدول أصلي
├── migration_fix.sql          # 12 جدول جديد
└── seed.sql                   # بيانات البذر
```

---

## التوثيق

| الوثيقة | الوصف |
|---------|-------|
| [docs/ENGINES.md](docs/ENGINES.md) | شرح المحركات الـ 40 |
| [docs/API.md](docs/API.md) | توثيق الـ 95 API endpoint |
| [docs/SCHEMA.md](docs/SCHEMA.md) | الـ 109 جدول + العلاقات |
| [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | الرفع على DigitalOcean |
| [docs/PRICING.md](docs/PRICING.md) | نظام التسعير + Exchange rate |
| [docs/FLOWS.md](docs/FLOWS.md) | الـ 9 flows + StepController |
| [docs/SECURITY.md](docs/SECURITY.md) | الأمان + HARD GATE |
| [docs/CHANGELOG.md](docs/CHANGELOG.md) | سجل التغييرات |
| [docs/CORPORATE.md](docs/CORPORATE.md) | حلول الشركات |
| [docs/SUGGESTIONS.md](docs/SUGGESTIONS.md) | نظام المقترحات |
| [developer.html](developer.html) | بوابة المطورين التفاعلية |

---

## الترخيص

حقوق الملكية محفوظة © 2024-2026 سودانا للحلول الذكية. جميع الحقوق محفوظة.
