دراسة حالة لمشروع متكامل
OneGate
البوّابة الواحدة للتوريد والشحن B2B — يقدّم العملاء في الخارج طلباتهم، ويسعّر الوكلاء المورّدين والشحن، وتنتقل الطلبات من العيّنة إلى التوريد بالجملة.
- الدور
- مطوّر ويب متكامل — منفردًا
- المدة
- 6 أسابيع — مستمر
- السنة
- 2026
- التقنيات
- React · TypeScript · Express.js · MongoDB · Redis
- مباشر
- onegate.llc
01 / المشكلة
وكالة استيراد تُدار عبر المحادثات وجداول البيانات.
كان العملاء الراغبون في توريد بضائع من الخارج أو شحن حمولات يتعاملون مع الوكالة عبر محادثات متفرّقة: يسعّر الموظفون المورّدين والعيّنات والشحن يدويًا، وتصل المدفوعات كإثباتات تحويل بنكي داخل سلاسل الرسائل، ولا أحد يملك رؤية واحدة لموقع الطلب بين مراحل التوريد والعيّنة والجملة.
المستخدمون المستهدفون
مستوردون B2B وبائعو تجارة إلكترونية — ناطقون بالعربية والإنجليزية — إضافةً إلى وكلاء التوريد ووكلاء الشحن والمدراء والمشرفين داخل الوكالة.
02 / الحل
منصّة واحدة، بوّابة واحدة.
منصّة محكومة بالأدوار يقدّم فيها العملاء طلبات التوريد أو الشحن ويتابعونها عبر التسعير وجولات العيّنات وتسعير الجملة والتسليم — مع رفع إثباتات الدفع والتحقّق منها من قِبل المشرفين وإصدار فواتير PDF. خمسة مسارات طلب مختلفة تتشارك محرّك دورة حياة واحدًا محروسًا، وكل حدث تجاري يُشعر الأدوار المعنيّة في الزمن الحقيقي.
لماذا هذه التقنيات
- MongoDB — مستند طلب واحد متداخل ومتغيّر الشكل لكل مسار
- Redis — طابور البريد وحدود المعدّل المشتركة ونشر/اشتراك SSE
- أصل واحد عبر Caddy — كعكات جلسة من الطرف الأول وبدون CORS
- عنقود Node — خدمة متعدّدة العمليات على خادم VPS واحد
03 / الميزات
ما الذي تقوم به المنصّة.
المصادقة وستة أدوار
جلسات ومصادقة Google وحدود ضد التخمين عبر ستة أدوار محدودة الصلاحيات
طلبات متعدّدة المسارات
خمسة مسارات طلب عبر آلات حالة محروسة للمرحلة والحالة
مدفوعات يدوية
إثباتات مرفوعة يتحقّق منها المشرفون، مع فواتير PDF من جهة العميل
إشعارات في الزمن الحقيقي
نشر/اشتراك Redis يتفرّع إلى تدفّقات SSE على كل عامل
ست لوحات حسب الدور
أكثر من 50 صفحة موجّهة مع تحليلات وعربية/إنجليزية ودعم RTL كامل
رفع مباشر إلى R2
روابط PUT موقّعة مسبقًا مع قوائم صارمة لأنواع المحتوى
04 / التحديات التقنية
الأجزاء الصعبة — وكيف تجاوزتها.
خمسة مسارات طلب، آلة حالة واحدة
الطلب نفسه قد يكون رحلة كاملة توريد ← عيّنة ← جملة، أو شراء جملة مباشرًا، أو مهمة شحن فقط — ويعدّله العملاء ونوعان من الوكلاء والمشرفون. انتقال واحد غير مشروع يُفسد تدفّقات مال حقيقية.
كيف حللتها
مستند واحد يحمل flowType و activePhase وقوائم حالة لكل مرحلة؛ وكل انتقال دالة خدمة مخصّصة تعيد التحقّق من الملكية والمسار والمرحلة والحالة قبل الكتابة. العروض المؤكَّدة تُجسّد أسعار الوحدة داخل المستند الفرعي للجملة، فيسير التسعير الثابت على آلية الدفع القائمة، وتُخصَّص أرقام الطلبات المقروءة دون تسابق عبر عدّاد ذرّي.
الزمن الحقيقي عبر عنقود عمليات
تعمل الواجهة البرمجية على أربعة عمّال منفصلين كحدّ أقصى إضافةً إلى عامل بريد مستقل. اتصال SSE يعيش على عملية واحدة بالضبط، لكن الحدث الذي يجب أن يصله قد ينشأ على أي عملية أخرى.
كيف حللتها
تُحفَظ الإشعارات في MongoDB ثم تُنشَر عبر نشر/اشتراك Redis؛ ويحتفظ كل عامل باتصال اشتراك مخصّص وسجلّ خاص بالتدفّقات المفتوحة لديه، فلا يمرّر إلا الأحداث المطابقة. تعليقات النبض تمنع الوسطاء من قطع التدفّقات الخاملة، والإشعار يُرسَل دون انتظار حتى لا يعطّل عطلٌ في Redis أي إجراء تجاري.
البقاء صحيحًا مع التوسّع الأفقي
تشعيب العمّال يكسر بصمت كل ما يعتمد على حالة داخل العملية — عدّادات حدود المعدّل، وكشف عنوان العميل خلف الوسيط، والتوزيع العادل للعمل الوارد.
كيف حللتها
حدود المعدّل تخزّن عدّاداتها في Redis ليصمد السقف عبر كل العمّال — مع السماح بالمرور إن سقط Redis؛ و trust proxy مثبّت على قفزة واحدة بالضبط. الطلبات الواردة تُسنَد تلقائيًا إلى أقل الوكلاء حِملًا عبر تجميع يخلط المتساوين، وهو ما يعيد توزيع العمل أيضًا عند مغادرة وكيل.
05 / البنية
كيف يتكامل النظام.
REACT 19 SPA
ست لوحات أدوار · PWA · عربي/إنجليزي RTL
EXPRESS 5 API
better-auth · Zod · عنقود Node
MONGODB
الطلبات · المدفوعات · الإشعارات
CLOUDFLARE R2
رفع مباشر موقّع مسبقًا
REDIS
طابور · حدود المعدّل · نشر/اشتراك
SMTP + BULLMQ
عامل بريد مع إعادة المحاولة
خدمات خارجية
06 / لقطات الشاشة
المنتج، عن قرب.
07 / النتائج
ما الذي غيّره على أرض الواقع.
سير عمل الوساطة كاملًا لدى الوكالة — التسعير وجولات العيّنات وتسعير الجملة والتحقّق من المدفوعات — صار يمرّ عبر تسجيل دخول واحد بدل جداول البيانات وسلاسل المحادثات. كل دور من الأدوار الستة يرى طابوره بالضبط، وكل تغيّر في الحالة يُشعر المعنيّين به فورًا، والمنصّة تُنشَر باستمرار عبر خطّ CI يشغّل مجموعة اختبارات شاملة قبل كل إصدار.
08 / حزمة التقنيات
بُني بهذه الأدوات.
أُطر العمل
- React 19
- Express 5
- Node.js
- Vite
المكتبات
- better-auth
- React Query
- BullMQ
- Zod
- Tailwind CSS
- Recharts
البنية التحتية
- MongoDB
- Redis
- Docker
- Caddy
- Cloudflare R2
- GitHub Actions CI/CD
09 / مساهمتي
ما الذي بنيته، تحديدًا.
- بنيتُ محرّك دورة حياة الطلبات: خمسة أنواع مسارات بآلات حالة للمرحلة والحالة، وحرّاس انتقال لكل دور، وتجسيد العروض، وترقيم ذرّي للطلبات.
- بنيتُ إشعارات في الزمن الحقيقي آمنة على العنقود: نشر/اشتراك Redis إلى سجلّات SSE لكل عامل مع نبضات، وحفظ مُقلَّم بالمهلة، وواجهة جرس الإشعارات.
- أعددتُ بنية الإنتاج من الطرف إلى الطرف: نقطة دخول لعنقود Node مع إيقاف سلس، وطبقات Docker Compose، و TLS بنفس الأصل عبر Caddy، وخطّ CI ← سجلّ الصور ← نشر SSH مشروطًا بمجموعة اختبارات Playwright.
- طوّرتُ ستّ لوحات أمامية محكومة بالأدوار (نحو 50 صفحة موجّهة) مع تعريب إنجليزي/عربي RTL، وتغليف PWA، ورسوم تحليلية، وعروض أسعار وفواتير PDF من جهة العميل.
- بنيتُ الإسناد التلقائي المتوازن للوكلاء: اختيار الأقل حِملًا عبر التجميع مع خلط المتساوين وإعادة التوزيع عند مغادرة وكيل؛ وضبطتُ طبقة better-auth وحصّنتها (ربط الحسابات، حدود لكل مسار).