# التوثيق التقني
## نظام تحليل العقود والمناقصات بالذكاء الاصطناعي - شركة شبه الجزيرة للمقاولات

<p align="center">
  <img src="../static/images/logo.png" alt="شعار النظام" width="200"/>
  <br>
  <em>إصدار التوثيق: 1.0.2 - تاريخ التحديث: 2025/03/01</em>
</p>

## جدول المحتويات

1. [نظرة عامة](#نظرة-عامة)
2. [المعمارية التقنية](#المعمارية-التقنية)
3. [متطلبات النظام](#متطلبات-النظام)
4. [الإعداد والتثبيت](#الإعداد-والتثبيت)
5. [بيئة Hybrid Face](#بيئة-hybrid-face)
6. [هيكل قاعدة البيانات](#هيكل-قاعدة-البيانات)
7. [وحدات النظام](#وحدات-النظام)
8. [واجهات برمجة التطبيقات (APIs)](#واجهات-برمجة-التطبيقات-apis)
9. [الأمان والمصادقة](#الأمان-والمصادقة)
10. [الأداء وقابلية التوسع](#الأداء-وقابلية-التوسع)
11. [استراتيجية النسخ الاحتياطي واستعادة البيانات](#استراتيجية-النسخ-الاحتياطي-واستعادة-البيانات)
12. [إرشادات التطوير](#إرشادات-التطوير)
13. [اختبار النظام](#اختبار-النظام)
14. [التكامل مع الأنظمة الخارجية](#التكامل-مع-الأنظمة-الخارجية)
15. [سجل التغييرات](#سجل-التغييرات)

## نظرة عامة

### عن النظام

نظام تحليل العقود والمناقصات بالذكاء الاصطناعي هو منصة متكاملة تعتمد على تقنيات الذكاء الاصطناعي ومعالجة اللغة العربية الطبيعية لمساعدة شركة شبه الجزيرة للمقاولات في تحليل وتسعير المناقصات وإدارة المشاريع.

### المكونات الرئيسية

1. **واجهة المستخدم (Frontend)**: تطبيق ويب تفاعلي مبني بواسطة Streamlit
2. **خدمات الخلفية (Backend)**: مجموعة من الخدمات والوحدات البرمجية بلغة Python
3. **قاعدة البيانات**: SQLite للتطوير والنشر المحلي، MySQL للنشر المؤسسي
4. **محركات الذكاء الاصطناعي**: نماذج معالجة اللغة الطبيعية والتعلم الآلي
5. **خدمات التكامل**: واجهات برمجة للتكامل مع الأنظمة الخارجية

## المعمارية التقنية

### المخطط العام للنظام

```mermaid
graph TD
    User[المستخدم] --> UI[واجهة المستخدم Streamlit]
    UI --> API[طبقة API]
    API --> Core[النواة]
    Core --> DB[(قاعدة البيانات)]
    Core --> NLP[معالجة اللغة العربية]
    Core --> ML[نماذج التعلم الآلي]
    Core --> FS[نظام الملفات]
    Core --> External[أنظمة خارجية]
    
    subgraph Core Modules
        NLP
        ML
        Doc[تحليل المستندات]
        Pricing[التسعير]
        Risk[تحليل المخاطر]
        Res[إدارة الموارد]
        Proj[إدارة المشاريع]
        Rep[التقارير]
    end
```

### نمط المعمارية

النظام يعتمد على نمط المعمارية طبقية (Layered Architecture) ونمط وحدات الخدمة (Service Modules):

1. **طبقة العرض**: واجهة المستخدم Streamlit
2. **طبقة الخدمات**: واجهات برمجة التطبيقات RESTful
3. **طبقة الأعمال**: وحدات المعالجة المنطقية
4. **طبقة البيانات**: الوصول إلى قاعدة البيانات وتخزين الملفات

## متطلبات النظام

### متطلبات الأجهزة

| المكون | الحد الأدنى | الموصى به |
|--------|-------------|-----------|
| المعالج | Intel Core i5 (8 أنوية) | Intel Core i7 (12 أنوية) أو أعلى |
| الذاكرة | 16GB RAM | 32GB RAM أو أكثر |
| التخزين | 10GB + مساحة للمستندات | SSD بسعة 50GB أو أكثر |
| الشبكة | اتصال إنترنت 10Mbps | اتصال إنترنت 50Mbps أو أسرع |
| الشاشة | دقة 1080p | دقة 1440p أو أعلى |

### متطلبات البرمجيات

| البرمجيات | الإصدار المطلوب |
|-----------|-----------------|
| نظام التشغيل | Windows 10/11، MacOS 12+، Ubuntu 20.04+ |
| Python | 3.9 أو أحدث |
| بيئة Hybrid Face | 2.5 أو أحدث |
| متصفح | Chrome 90+، Firefox 88+، Edge 90+ |
| MySQL (اختياري) | 8.0 أو أحدث |

### المكتبات الأساسية

```python
# المكتبات الأساسية المستخدمة
streamlit==1.10.0
pandas==1.5.0
numpy==1.23.0
scikit-learn==1.1.0
nltk==3.7.0
spacy==3.4.0
transformers==4.20.0
pyarabic==0.6.15
sqlalchemy==1.4.40
plotly==5.9.0
pymysql==1.0.2
pdfplumber==0.7.0
python-docx==0.8.11
openpyxl==3.0.10
ezdxf==0.17.2
```

## الإعداد والتثبيت

### إعداد بيئة التطوير

```bash
# إنشاء بيئة Python افتراضية
python -m venv venv
source venv/bin/activate  # Linux/MacOS
venv\Scripts\activate  # Windows

# تثبيت المكتبات المطلوبة
pip install -r requirements.txt
pip install -r arabic_support_requirements.txt
```

### تثبيت نماذج معالجة اللغة العربية

```bash
# تثبيت نموذج اللغة العربية لـ SpaCy
python -m spacy download ar_core_news_lg

# تحميل موارد NLTK للغة العربية
python -m nltk.downloader stopwords
python -m nltk.downloader punkt
python -m nltk.downloader wordnet
```

### إعداد قاعدة البيانات

#### SQLite (للتطوير المحلي)

```bash
# إنشاء قاعدة بيانات SQLite
python setup_db.py --mode=local
```

#### MySQL (للنشر المؤسسي)

```bash
# إعداد قاعدة بيانات MySQL
python setup_db.py --mode=enterprise \
  --db-host=YOUR_DB_HOST \
  --db-user=YOUR_DB_USER \
  --db-pass=YOUR_DB_PASS \
  --db-name=tender_analysis_system