نظام إدارة الترقيات (PMS) 🚀

Promotion Management System

📋 نظرة عامة

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

---

✨ المميزات الرئيسية

🎯 إدارة الترقيات المتقدمة

• حساب آلي للنقاط: نظام ذكي لحساب نقاط الترقية بناءً على معايير محددة
• معالجة جماعية: إمكانية معالجة ترقيات متعددة دفعة واحدة
• تتبع شامل: متابعة حالة كل ترشيح بدقة مع سجل كامل للعمليات
• تقارير تفصيلية: تقارير احترافية قابلة للتصدير (Excel, PDF, Word)
• إحصائيات متقدمة: لوحة تحكم شاملة مع رسوم بيانية تفاعلية

👥 إدارة متقدمة للمستخدمين والصلاحيات

• نظام RBAC: صلاحيات متقدمة مبنية على الأدوار (Admin, Supervisor, Data Entry, Reviewer, User)
• صلاحيات دقيقة: تحكم كامل في صلاحيات كل مستخدم على مستوى الإجراءات
• إدارة الجلسات: نظام جلسات متقدم مع انتهاء تلقائي وحماية من التعدد
• سجلات المراجعة: تتبع كامل لجميع العمليات والتعديلات

📄 إدارة الوثائق الذكية

• رفع متعدد: دعم رفع ملفات متعددة (PDF, Word, Images)
• معاينة فورية: عرض الوثائق مباشرة داخل النظام
• مراجعة احترافية: نظام مراجعة الوثائق مع تعليقات وموافقات
• بحث متقدم: البحث في الوثائق والملفات المرفوعة
• نسخ احتياطية: نظام متكامل للنسخ الاحتياطي (إنشاء، تحميل، استرجاع، حذف)

🤖 شات بوت ذكي

• ذكاء اصطناعي: تصنيف تلقائي للأسئلة وردود ذكية
• دعم عربي كامل: مصمم خصيصاً للغة العربية
• اقتراحات تفاعلية: أسئلة مقترحة بناءً على السياق
• واجهة حديثة: تصميم عصري وسهل الاستخدام

🎨 واجهة مستخدم احترافية

• تصميم متجاوب: متوافق تماماً مع جميع الأجهزة (Mobile, Tablet, Desktop, Large Screens)
• Dark Mode: وضع ليلي مريح للعين
• Material-UI: مكتبة Material-UI الاحترافية
• أداء عالي: تحميل سريع وتفاعل سلس
• تجربة مستخدم متقدمة: UX/UI محسّن باستمرار

⚡ تقنيات متقدمة

• WebSocket: للعمليات الطويلة (تصدير الاستمارات) مع تحديثات فورية
• Caching ذكي: تخزين مؤقت على Frontend و Backend للأداء الأمثل
• API موثق: Swagger UI لتوثيق كامل لجميع نقاط API
• معالجة متزامنة: معالجة العمليات الكبيرة في الخلفية
• تحسين الأداء: استعلامات محسّنة وفهرسة ذكية للبيانات

---

🏗️ البنية التقنية

Backend (Python/FastAPI)

backend/
├── api/                    # RESTful API Endpoints
│   ├── chatbot.py         # شات بوت AI
│   ├── persons.py         # إدارة الأفراد
│   ├── promotion.py       # معالجة الترقيات
│   ├── permissions.py     # نظام الصلاحيات
│   ├── documents.py       # إدارة الوثائق
│   ├── admin_api.py       # لوحة الإدارة
│   └── export_nomination.py  # تصدير الاستمارات
├── models/                # نماذج البيانات (SQLAlchemy)
├── services/              # منطق الأعمال
│   ├── documents.py       # خدمات الوثائق
│   └── websocket.py       # WebSocket للعمليات الطويلة
├── core/                  # وحدات أساسية
│   └── security.py        # التشفير والأمان
└── main.py                # نقطة الدخول الرئيسية

Frontend (React/Vite)

frontend/src/
├── components/            # المكونات القابلة لإعادة الاستخدام
│   ├── ChatbotInterface.jsx      # واجهة الشات بوت
│   ├── DocumentManager.jsx       # إدارة الوثائق
│   ├── PermissionButton.jsx      # أزرار بصلاحيات
│   └── SessionManager.jsx        # إدارة الجلسات
├── hooks/                 # React Custom Hooks
│   ├── usePermissions.js  # صلاحيات المستخدم
│   ├── useSession.js      # إدارة الجلسات
│   └── useResponsive.js   # التصميم المتجاوب
├── theme/                 # نظام الألوان والثيمات
├── constants/             # الثوابت والإعدادات
└── App.jsx                # التطبيق الرئيسي

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

• SQLite: قاعدة بيانات محلية سهلة النقل
• جداول رئيسية: users, persons, promotions, documents, roles, permissions
• علاقات متقدمة: Foreign Keys مع Cascade
• فهرسة محسّنة: لأداء استعلامات أسرع

---

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

1️⃣ متطلبات النظام

• Python: 3.8 أو أحدث
• Node.js: 16 أو أحدث
• SQLite3: مدمج مع Python
• نظام التشغيل: Windows, macOS, Linux

2️⃣ تثبيت المشروع

# 1. استنساخ المشروع
git clone https://github.com/balckice999/PMS.git
cd PMS

# 2. إنشاء البيئة الافتراضية
python -m venv pro

# 3. تفعيل البيئة
# Windows
pro\Scripts\activate
# macOS/Linux
source pro/bin/activate

# 4. تثبيت مكتبات Python
pip install -r requirements.txt

# 5. تثبيت مكتبات Node.js
cd frontend
npm install
cd ..

3️⃣ تشغيل النظام

✅ الطريقة الموصى بها (أمر واحد)

Windows:

# استخدام السكريبت المبسط
.\dev.ps1

# أو مباشرة
.\pro\Scripts\python.exe run_dev.py

macOS/Linux:

# تشغيل مباشر
python3 run_dev.py

🔗 الروابط بعد التشغيل

• الواجهة الأمامية: http://localhost:5173
• السيرفر الخلفي: http://localhost:8000
• وثائق API: http://localhost:8000/docs

🔐 بيانات تسجيل الدخول الافتراضية

اسم المستخدم: admin
كلمة المرور: admin123

⚠️ مهم: غيّر كلمة المرور فوراً بعد أول تسجيل دخول!

4️⃣ إيقاف النظام

# ببساطة اضغط
Ctrl + C

---

🐳 التثبيت باستخدام Docker

متطلبات Docker

• Docker: 20.10 أو أحدث
• Docker Compose: 2.0 أو أحدث

التثبيت السريع

# 1. استنساخ المشروع
git clone https://github.com/balckice999/PMS.git
cd PMS

# 2. تشغيل في وضع التطوير (Development)
# Windows PowerShell
.\docker-run.ps1 dev

# Linux/macOS
./docker-run.sh dev

# أو مباشرة
docker-compose up --build

أوضاع التشغيل

🔧 وضع التطوير (Development)

# Windows
.\docker-run.ps1 dev

# Linux/macOS
./docker-run.sh dev

# أو مباشرة
docker-compose -f docker-compose.dev.yml up --build

المميزات:

• ✅ Hot-reload للكود (تحديث فوري)
• ✅ الوصول إلى الكود المصدري
• ✅ أسهل في التطوير والتصحيح

الروابط:

• Frontend: http://localhost:5173
• Backend: http://localhost:8000
• API Docs: http://localhost:8000/docs

🚀 وضع الإنتاج (Production)

# Windows
.\docker-run.ps1 prod

# Linux/macOS
./docker-run.sh prod

# أو مباشرة
docker-compose -f docker-compose.prod.yml up --build -d

المميزات:

• ✅ بناء محسّن للأداء
• ✅ Nginx للواجهة الأمامية
• ✅ تشغيل في الخلفية (detached mode)

الروابط:

• Frontend: http://localhost
• Backend: http://localhost:8000
• API Docs: http://localhost:8000/docs

أوامر Docker المساعدة

# عرض جميع الأوامر المتاحة
.\docker-run.ps1 help    # Windows
./docker-run.sh help     # Linux/macOS

# إيقاف الحاويات
.\docker-run.ps1 stop
./docker-run.sh stop

# عرض السجلات
.\docker-run.ps1 logs
./docker-run.sh logs

# عرض السجلات (Production)
.\docker-run.ps1 logs prod
./docker-run.sh logs prod

# إعادة بناء الحاويات
.\docker-run.ps1 rebuild
./docker-run.sh rebuild

# عرض حالة الحاويات
.\docker-run.ps1 status
./docker-run.sh status

# تنظيف شامل (حذف الحاويات والمجلدات)
.\docker-run.ps1 clean
./docker-run.sh clean

إدارة البيانات

جميع البيانات (قاعدة البيانات، الوثائق، الصور، التقارير) محفوظة في Docker Volume:

# عرض المجلدات
docker volume ls

# عرض تفاصيل مجلد البيانات
docker volume inspect pms_pms_data

# نسخ احتياطي للبيانات
docker run --rm -v pms_pms_data:/data -v $(pwd):/backup alpine tar czf /backup/pms-backup.tar.gz -C /data .

إعدادات البيئة

يمكنك تخصيص الإعدادات عبر ملفات البيئة:

• .env.example - قالب الإعدادات
• .env.dev - إعدادات التطوير
• .env.prod - إعدادات الإنتاج

مهم: غيّر جميع المفاتيح السرية في .env.prod قبل النشر!

استكشاف الأخطاء

المشكلة: الحاويات لا تبدأ

# تحقق من حالة Docker
docker ps
docker-compose ps

# تحقق من السجلات
docker-compose logs backend
docker-compose logs frontend

المشكلة: قاعدة البيانات لا تُهيأ

# تحقق من صلاحيات المجلد
docker-compose exec backend ls -la /app/data

# إعادة تهيئة قاعدة البيانات
docker-compose exec backend python init_database.py

المشكلة: الواجهة الأمامية لا تتصل بالخلفية

# تحقق من متغيرات البيئة
docker-compose exec frontend env | grep VITE

# تحقق من الشبكة
docker network inspect pms_pms-network

المشكلة: المنفذ مستخدم

# Windows - إيجاد العملية المستخدمة للمنفذ
netstat -ano | findstr :8000
netstat -ano | findstr :5173

# Linux/macOS
lsof -i :8000
lsof -i :5173

نقل المشروع إلى جهاز آخر

1. استنساخ المشروع:

   git clone https://github.com/balckice999/PMS.git
   cd PMS

2. تشغيل Docker:

   docker-compose up --build

3. جاهز! 🎉

البيانات محفوظة تلقائياً في Docker Volumes وستستمر حتى بعد إيقاف الحاويات.

---

📊 لوحة التحكم والإحصائيات

المميزات المتاحة

• KPI Cards: عرض سريع للأرقام الرئيسية
• رسوم بيانية:
  • توزيع الأفراد حسب الرتبة (Pie Chart)
  • تحليل النقاط (Bar Chart)
  • مؤهلات الأفراد (Multiple Charts)
• جداول تفاعلية: بيانات قابلة للفرز والبحث
• تصدير شامل: Excel و PDF للتقارير والبيانات

---

🔐 نظام الصلاحيات

الأدوار المتاحة

الدور	الصلاحيات الأساسية
Admin	صلاحيات كاملة على النظام
Supervisor	إدارة البيانات + المراجعة
Data Entry	إدخال وتعديل البيانات
Reviewer	مراجعة واعتماد البيانات
User	عرض البيانات فقط

مستويات الحماية

• ✅ Frontend: أزرار وصفحات محمية بـ PermissionGuard
• ✅ Backend: جميع API محمية بـ Token Authentication
• ✅ Database: تشفير كلمات المرور بـ bcrypt
• ✅ Sessions: انتهاء تلقائي للجلسات + تحذيرات

---

📱 التصميم المتجاوب

النظام متجاوب بالكامل مع:

• Mobile (< 480px): قائمة Drawer + أزرار كبيرة
• Tablet (481px - 768px): شبكة 2 أعمدة
• Desktop (769px - 1399px): شبكة 3-4 أعمدة
• Large Screens (≥ 1400px): شبكة 4-5 أعمدة

تقنيات التجاوب المستخدمة

• Material-UI breakpoints و useMediaQuery
• CSS Grid و Flexbox
• clamp() للخطوط الديناميكية
• Responsive Font Sizes من MUI

---

🤖 دليل استخدام الشات بوت

الأسئلة المدعومة

الفئة	أمثلة
الترحيب	مرحبا، السلام عليكم، أهلاً
حساب النقاط	كم عدد نقاطي؟ كيف أحسب نقاطي؟
شروط الترقية	ما هي الشروط؟ متطلبات الترقية؟
التقديم	كيف أتقدم؟ خطوات التقديم؟
المستندات	أي مستندات مطلوبة؟ الوثائق؟
المواعيد	متى ينتهي التسجيل؟ آخر موعد؟
المتابعة	كيف أتابع طلبي؟ حالة الطلب؟
التواصل	رقم الاتصال؟ كيف أتواصل؟

---

🛠️ API Endpoints (مختصر)

المصادقة والجلسات

• POST /login - تسجيل الدخول
• POST /logout - تسجيل الخروج
• GET /me/current - معلومات المستخدم الحالي

الأفراد والترقيات

• GET /api/persons - قائمة الأفراد
• POST /api/persons - إضافة فرد جديد
• POST /api/promotion/process - معالجة الترقيات
• GET /api/eligible-list - قائمة المؤهلين

الصلاحيات

• GET /api/permissions/users/{user_id}/permissions/public - صلاحيات المستخدم

الوثائق

• POST /api/documents/upload - رفع وثيقة
• GET /api/documents/{id} - عرض وثيقة
• POST /api/documents/{id}/review - مراجعة وثيقة

الإدارة والنسخ الاحتياطي

• GET /api/admin/users - إدارة المستخدمين
• POST /api/admin/system/backup - إنشاء نسخة احتياطية
• GET /api/admin/system/backups - قائمة النسخ الاحتياطية
• POST /api/admin/system/backups/{filename}/restore - استرجاع نسخة

الشات بوت

• POST /api/chatbot/chat - إرسال رسالة
• GET /api/chatbot/health - صحة النظام

📚 للتوثيق الكامل: http://localhost:8000/docs

---

🔧 استكشاف الأخطاء

مشاكل شائعة وحلولها

المشكلة	الحل
ERR_CONNECTION_REFUSED	تأكد من تشغيل Backend بـ .\dev.ps1
الشات بوت لا يظهر	سجّل الدخول أولاً
"ليس لديك صلاحية"	تحقق من صلاحيات المستخدم في لوحة الإدارة
صفحة بيضاء	افتح Developer Tools (F12) وتحقق من الأخطاء
البورت مشغول	أوقف العمليات المشغولة: .\stop_system.ps1

السجلات (Logs)

backend/logs/          # سجلات Backend
frontend/             # سجلات المتصفح (F12)
.cursor/debug.log     # سجلات التطوير

---

📦 النسخ الاحتياطية

إنشاء نسخة احتياطية

# من لوحة الإدارة → النسخ الاحتياطية → "إنشاء نسخة جديدة"
# أو عبر API
curl -X POST http://localhost:8000/api/admin/system/backup

استعادة نسخة احتياطية

# من لوحة الإدارة → النسخ الاحتياطية → "استرجاع"

📌 تلقائي: يتم إنشاء نسخة احتياطية تلقائياً قبل كل عملية استرجاع!

---

🎯 خارطة الطريق

• تكامل مع Active Directory / LDAP
• تطبيق موبايل (React Native)
• إشعارات فورية (Push Notifications)
• نظام تقارير متقدم (Business Intelligence)
• دعم تعدد اللغات (i18n)
• تكامل مع أنظمة خارجية (API Gateway)

---

👨‍💻 التطوير والمساهمة

إضافة ميزة جديدة

1. Backend: أضف API جديد في backend/api/
2. Frontend: أضف المكون في frontend/src/components/
3. الصلاحيات: حدث setup_default_permissions.py
4. اختبار: اختبر محلياً قبل النشر

الأدوات المستخدمة

• Backend: FastAPI, SQLAlchemy, Pydantic, Uvicorn
• Frontend: React, Vite, Material-UI, Axios, Recharts
• Database: SQLite3
• Security: bcrypt, JWT tokens
• Real-time: WebSocket

---

📞 الدعم والتواصل

للحصول على الدعم الفني:

• 📧 البريد الإلكتروني: [email protected]
• 📱 الهاتف: 0559795330
• 🐛 الإبلاغ عن مشاكل: افتح Issue على GitHub

---

📜 الترخيص

هذا المشروع مرخص تحت رخصة MIT - يمكنك استخدامه وتعديله بحرية.

---

🏆 الشكر والتقدير

تم تطوير هذا النظام بواسطة: عبيد المطيري - جوازات ميناء نيوم - تقنية المعلومات 🎖️

---

📅 آخر تحديث: ديسمبر 2025
🔢 الإصدار: 2.0
⭐ النجوم: إذا أعجبك المشروع، لا تنس إضافة نجمة على GitHub!