39354-vm/docs/flatlogic-cicd-backend.md

Flatlogic CI/CD + External DB + Ingestion API

هذا الإعداد يجعل المشروع يعمل بهذه الصورة:

• GitHub هو مصدر الحقيقة للكود.
• Bolt / Replit يدفعان التعديلات إلى نفس المستودع أو يرسلان repository_dispatch.
• GitHub Actions تبني المشروع وتتحقق منه ثم تنشره إلى VM الخاص بـ Flatlogic.
• Flatlogic / API Server يدير بيانات المنتجات القادمة من أدوات السحب وويبهوكات شي إن.
• Supabase / PostgreSQL هو مخزن البيانات الخارجي للمنتجات والفئات وسجل أحداث التكامل.

ما تمت إضافته

• .github/workflows/ci.yml
  • Typecheck + Build لكل Push / Pull Request.
• .github/workflows/deploy-flatlogic.yml
  • ينشر تلقائيًا إلى VM عند التحديث على main أو master.
  • يدعم repository_dispatch لأنواع:
    • bolt_sync
    • replit_sync
    • flatlogic_deploy
• scripts/flatlogic-deploy.sh
  • يسحب آخر نسخة من GitHub.
  • يثبت الحزم.
  • يشغل typecheck و build.
  • يطبق schema قاعدة البيانات عبر Drizzle.
  • يعيد تشغيل extra-store و flatlogic-api عبر PM2.
• .env.example
  • كل متغيرات البيئة المطلوبة للـ DB والـ API والأمان.
• API endpoints جديدة داخل artifacts/api-server.

الأسرار المطلوبة في GitHub Actions

أضف هذه القيم في GitHub → Settings → Secrets and variables → Actions:

أسرار النشر إلى Flatlogic VM

• FLATLOGIC_HOST
• FLATLOGIC_USER
• FLATLOGIC_SSH_KEY
• FLATLOGIC_PROJECT_DIR
• FLATLOGIC_DEPLOY_BRANCH (اختياري)

أسرار الـ backend

• DATABASE_URL
• DB_SSL = require
• DB_POOL_MAX = 20
• DB_QUERY_TIMEOUT_MS = 15000
• DB_STATEMENT_TIMEOUT_MS = 15000
• ADMIN_TOKEN
• API_INGEST_KEY
• WEBHOOK_SECRET
• SHEIN_WEBHOOK_SECRET
• API_PORT = 8080
• STORE_PORT = 3001

إعداد قاعدة البيانات الخارجية (Supabase / PostgreSQL)

الحد الأدنى المقترح لاستيعاب 2000 منتج من Extra + Shein:

• استخدم Postgres خارجي أو Supabase.
• يفضل في Supabase استخدام transaction pooler داخل DATABASE_URL.
• الإعدادات الافتراضية المضافة في الكود:
  • DB_POOL_MAX=20
  • DB_QUERY_TIMEOUT_MS=15000
  • DB_STATEMENT_TIMEOUT_MS=15000
  • keepAlive=true
• أضف الـ schema بالأمر:

pnpm --filter @workspace/db run push

ملاحظة: الجدول products صار يدعم الآن source, external_id, source_url, currency, availability, metadata, last_synced_at مع فهارس مخصصة للبحث والتزامن.

API Endpoints الجديدة

1) Bulk ingestion للمنتجات

POST /api/ingest/products/bulk

Headers:

x-api-key: <API_INGEST_KEY>
content-type: application/json

Body مثال:

{
  "source": "shein",
  "webhook_id": "apify-run-123",
  "products": [
    {
      "external_id": "shein-10001",
      "sku": "SKU-10001",
      "name": "فستان صيفي",
      "brand": "SHEIN",
      "price": 149,
      "original_price": 199,
      "stock": 25,
      "availability": "in_stock",
      "sizes": ["S", "M", "L"],
      "colors": ["Black", "Pink"],
      "images": ["https://example.com/1.jpg"],
      "category": {
        "slug": "dresses",
        "name": "فساتين"
      },
      "source_url": "https://example.com/product/10001"
    }
  ]
}

2) Upsert منتج مفرد

POST /api/ingest/products/upsert

نفس الحماية عبر x-api-key.

3) Webhook تحديثات شي إن

POST /api/webhooks/shein/products

Headers:

x-api-key: <API_INGEST_KEY>
x-webhook-signature: sha256=<hmac_sha256_of_raw_body>
content-type: application/json

Body مثال:

{
  "webhook_id": "shein-webhook-987",
  "event": "price.updated",
  "products": [
    {
      "external_id": "shein-10001",
      "price": 139,
      "stock": 12,
      "availability": "low_stock",
      "sizes": ["S", "M"]
    }
  ]
}

4) Pipeline status

GET /api/integrations/pipeline/status

• محمي بـ Authorization: Bearer <ADMIN_TOKEN>
• يعرض:
  • حالة إعداد الأمان
  • حالة الـ DB
  • عدد المنتجات حسب المصدر
  • آخر أحداث التكامل

ربط Bolt / Replit مع GitHub

أفضل سيناريو:

1. اجعل Bolt أو Replit يدفعان إلى نفس مستودع GitHub.
2. كل Push إلى main يشغل:
   • ci.yml
   • ثم deploy-flatlogic.yml
3. النتيجة: يتم تحديث الموقع والـ backend تلقائيًا.

إذا كانت الأداة لا تدفع مباشرة إلى GitHub، استخدم repository_dispatch من GitHub API بنوع:

• bolt_sync
• replit_sync

ملاحظات تشغيلية

• الواجهة الأمامية الآن تدعم VITE_API_BASE_URL إذا أردت backend مختلفًا عن نفس الدومين.
• في وضع التطوير، Vite يمرر /api إلى http://127.0.0.1:8080 عبر proxy.
• إذا لم تكن أسرار الـ backend موجودة، فسيستمر المتجر الأمامي بالعمل، لكن تشغيل خدمة الـ API سيتم تخطيه أثناء النشر.