منظومة Oikosmou — دليل النشر الكامل

١. نظرة عامة على النظام

تتكوّن منظومة Oikosmou من أربعة مكوّنات تتواصل عبر REST API واحد:

# تدفّق البيانات
User App  ─┐
           ├──►  FastAPI Backend  ──►  PostgreSQL 16
Admin Web ─┘            │
Landing PWA ───────────►┘   (REST/HTTPS + JWT)

٢. المتطلبات الأساسية

٣. التنزيل من GitHub

# استنساخ المستودع
git clone git@github.com:bodoorzahera/oikosmou.git
# أو عبر HTTPS
git clone https://github.com/bodoorzahera/oikosmou.git
cd oikosmou

بنية المجلدات بعد الاستنساخ:

oikosmou/
├── oikosmou_backend/     # FastAPI + Alembic + Docker
├── oikosmou_app/         # تطبيق المستخدم Flutter
├── oikosmou_admin/       # لوحة الإدارة Flutter Web
├── oikosmou_shared/      # الحزمة المشتركة Dart
├── landing/              # صفحة الهبوط PWA
├── database/             # ← نسخة SQL كاملة (schema + بيانات)
├── downloads/            # APK جاهز للتثبيت
├── deploy.html           # ← هذا الملف
└── Features.html         # صفحة الميزات الدعائية

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

النظام يأتي مع نسخة قاعدة بيانات كاملة في مجلد database/ (٢٠٦ لون، ٢٠ منتج، ٥ متاجر، عروض، تصاميم، وحسابات تجريبية). لديك طريقتان:

الطريقة أ — Docker (الأسرع، موصى بها)

cd oikosmou_backend
docker compose up -d            # PostgreSQL 16 على المنفذ 5433
# انتظر حتى تصبح الحاوية healthy، ثم استعِد البيانات:
cat ../database/oikosmou_full.sql | docker compose exec -T db psql -U oikosmou -d oikosmou

الطريقة ب — توليد البيانات من الصفر عبر Alembic + Seed

cd oikosmou_backend
source venv/bin/activate
alembic upgrade head                 # إنشاء كل الجداول (٢١ جدول)
python -m app.scripts.seed_data      # تعبئة البيانات التجريبية

٥. الخادم الخلفي (Backend)

cd oikosmou_backend

# 1) بيئة افتراضية وتثبيت المكتبات
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 2) إعداد متغيّرات البيئة (موجود مسبقاً في .env)
#    عدّل DATABASE_URL والمفاتيح حسب الحاجة — انظر القسم ٧

# 3) تشغيل الخادم (تطوير)
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 4) أو للإنتاج (متعدّد العمّال)
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

٦. الواجهات (Frontend)

لوحة الإدارة (Flutter Web)

cd oikosmou_admin
flutter pub get
# التشغيل للتطوير:
flutter run -d chrome
# أو بناء نسخة ويب للنشر:
flutter build web --release       # الناتج في build/web/

تطبيق المستخدم (Flutter)

cd oikosmou_app
flutter pub get
flutter run                       # على جهاز/محاكي
flutter build apk --release       # بناء APK
# APK جاهز أيضاً في: downloads/oikosmou-latest.apk

صفحة الهبوط (Landing)

# مجلد ثابت static — يُرفع كما هو على أي استضافة ويب
cd landing
python3 -m http.server 8080       # معاينة محلية

٧. متغيّرات البيئة والمفاتيح

كل إعدادات الـ Backend في oikosmou_backend/.env. أهمّ المفاتيح:

توليد مفاتيح VAPID لإشعارات الويب

cd oikosmou_backend && source venv/bin/activate
python -c "from py_vapid import Vapid01; v=Vapid01(); v.generate_keys(); print(v)"
# أو استخدم vapid_keys.json الموجود ثم انسخ المفاتيح إلى .env

مفتاح SECRET_KEY عشوائي للإنتاج

python -c "import secrets; print(secrets.token_urlsafe(48))"

٨. أفضل ٣ حلول استضافة مجانية

النظام يحتاج ٣ أشياء على الإنترنت: (أ) خادم Python للـ API، (ب) قاعدة PostgreSQL، (ج) استضافة ملفات ثابتة للوحة الإدارة وصفحة الهبوط. الحلول الثلاثة التالية توفّر ذلك مجاناً بالكامل:

الحل ١ — Render + Neon + Netlify

الخطوات

# 1. أنشئ حساباً على neon.tech ومشروعاً جديداً (اختر منطقة قريبة)
# 2. انسخ Connection String، ثم استعِد البيانات:
psql "postgresql://USER:PASS@ep-xxx.neon.tech/oikosmou?sslmode=require" \
     -f database/oikosmou_full.sql

Root Directory : oikosmou_backend
Build Command  : pip install -r requirements.txt
Start Command  : gunicorn app.main:app -w 2 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:$PORT

DATABASE_URL = postgresql+asyncpg://USER:PASS@ep-xxx.neon.tech/oikosmou?ssl=require
SECRET_KEY   = <مفتاح عشوائي 48 حرف>
CORS_ORIGINS = ["https://YOUR-ADMIN.netlify.app","https://YOUR-LANDING.netlify.app"]
SMTP_HOST=smtp.gmail.com  SMTP_PORT=587  SMTP_USER=...  SMTP_PASSWORD=...

# عدّل baseUrl في api_constants.dart ليشير لرابط Render، ثم:
cd oikosmou_admin && flutter build web --release
# اسحب مجلد build/web إلى Netlify Drop (app.netlify.com/drop)
# أو عبر CLI:
npx netlify-cli deploy --dir=build/web --prod
# كرّر نفس الشيء لمجلد landing/

الحل ٢ — Railway (متكامل) + Cloudflare Pages

# على railway.app أنشئ مشروعاً جديداً ثم:
# New → Database → Add PostgreSQL  (يُنشئ DATABASE_URL تلقائياً)
# استعِد البيانات عبر رابط الاتصال العام:
psql "$RAILWAY_DATABASE_PUBLIC_URL" -f database/oikosmou_full.sql

Root Directory : oikosmou_backend
# Railway يبني من Dockerfile مباشرة. أضف المتغيّرات:
DATABASE_URL = ${{Postgres.DATABASE_URL}}   # مرجع داخلي + حوّله لصيغة asyncpg
SECRET_KEY   = <مفتاح عشوائي>
PORT         = 8000

cd oikosmou_admin && flutter build web --release
npx wrangler pages deploy build/web --project-name=oikosmou-admin
# و landing/ بنفس الطريقة

الحل ٣ — Fly.io + Supabase + GitHub Pages

# أنشئ مشروعاً على supabase.com، ثم من Settings → Database انسخ الرابط:
psql "postgresql://postgres:PASS@db.xxx.supabase.co:5432/postgres" \
     -f database/oikosmou_full.sql

curl -L https://fly.io/install.sh | sh      # تثبيت flyctl
cd oikosmou_backend                          # ← لازم: هنا يوجد Dockerfile و fly.toml
fly launch --no-deploy --copy-config         # يستخدم fly.toml الجاهز بدل إعادة الكشف
fly secrets set DATABASE_URL="postgresql+asyncpg://postgres:PASS@db.xxx.supabase.co:5432/postgres" \
                SECRET_KEY="<عشوائي>"
fly deploy

cd oikosmou_admin
flutter build web --release --base-href /oikosmou-admin/
# ادفع محتوى build/web إلى فرع gh-pages في مستودع منفصل:
cd build/web && git init && git add -A && git commit -m "deploy"
git branch -M gh-pages
git remote add origin git@github.com:bodoorzahera/oikosmou-admin.git
git push -f origin gh-pages
# فعّل Pages من Settings → Pages → Branch: gh-pages

٩. تهيئة استضافة الواجهة (Webhost) — تفاصيل مهمّة

لوحة الإدارة وتطبيق الويب من نوع SPA (تطبيق صفحة واحدة) تستخدم توجيهاً داخلياً عبر GoRouter. أي استضافة ثابتة تحتاج إعداداً ليعمل التحديث (refresh) على المسارات الفرعية:

Netlify — ملف _redirects داخل build/web/

/*    /index.html   200

Vercel — ملف vercel.json

{ "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }] }

Apache — ملف .htaccess

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>

Nginx

server {
  listen 80;
  root /var/www/oikosmou_admin;     # محتوى build/web
  index index.html;
  location / { try_files $uri $uri/ /index.html; }
  location /api/ { proxy_pass http://127.0.0.1:8000; }   # وكيل للـ API (اختياري)
}

إشعارات الويب (Service Worker) لصفحة الهبوط

صفحة landing/ تتضمّن sw.js وmanifest.json لإشعارات Web Push. يجب أن تُخدَّم عبر HTTPS (كل المنصّات أعلاه توفّره مجاناً) ليعمل الـ Service Worker.

١٠. قائمة تحقّق الإنتاج

١١. حلّ المشاكل الشائعة