نظرة عامة

Riquid منظومة منتجات متعدّدة الوحدات تغطّي دورة التجارة من طرفها إلى طرفها — البيع والتنفيذ والتتبّع والتسويق. وهي مبنيّة لعملية تجارة بين الشركات تُدير متجرها الإلكتروني الخاصّ وتُدير في الوقت نفسه الخدمات اللوجستية والتقارير داخليًا. وبدلًا من تطبيق واحد متجانس، تتألّف المنظومة من ثلاث قواعد كود منفصلة للواجهة الأمامية — نواة عمليات بـ React + Vite، ومتجر إلكتروني بـ Next.js، وموقع أعمال بـ Next.js — تتشارك نظام تصميم موحّدًا.

التحدي

أي عملية تجارية ذات حجم حقيقي تتجاوز حدود المتجر الواحد سريعًا. فالبيع ليس سوى واجهة واحدة: الطلبات لا بدّ أن تُنفَّذ، والشحنات لا بدّ أن تُحدَّد مواقعها وتُتبَّع، والمبيعات لا بدّ أن تُقاس، والعمل يحتاج إلى وجه عامّ يتحدّث لغة المنتج البصرية نفسها. والمسار البديهي هو إلحاق كل واحد من هذه العناصر بأي قاعدة كود قائمة بالفعل، والنتيجة المتوقَّعة تطبيق واحد يحمل مسار دفع وتكامل Mapbox ومكتبة رسوم بيانية وصفحة هبوط تسويقية في حزمة واحدة — وكل واجهة تتنافس على قطار الإصدار نفسه. أمّا نمط الفشل البديل فهو فصلها وترك كلٍّ منها ينحرف على هواه، حتى يشعر العميل المنتقل من الموقع التسويقي إلى المتجر إلى واجهة التتبّع أنّه أمام ثلاثة منتجات لا صلة بينها. وكانت المشكلة هي تحقيق الفصل دون الانحراف: تطبيقات متمايزة بوتائر إصدار متمايزة، تُقرأ مع ذلك بوصفها نظامًا واحدًا.

تصميم النظام

تتألّف المنظومة من ثلاث واجهات أمامية قابلة للنشر. نواة العمليات (riquid-website) تطبيق React 18 يعمل على Vite 4، ويُوجَّه بـ React Router v6. وهي تحمل التكاملين اللذين سيكونان عبئًا ميتًا في حزمة متجر إلكتروني: Mapbox GL — مغلَّفًا بـ react-map-gl — لواجهات المواقع والخدمات اللوجستية، وChart.js عبر react-chartjs-2 لتحليلات المبيعات. وتُدار الحركة والعرض بـ Framer Motion وAOS وSwiper، مع react-intersection-observer لقيادة الظهور المرتبط بالتمرير وreact-countup لتحريك الأرقام. ويوفّر Tailwind CSS مع PostCSS وAutoprefixer طبقة التنسيق، ويعمل ESLint بالخيار --max-warnings 0، فتكون بوّابة الفحص اللغوي بوّابة صارمة لا مجرّد توصية.

والمتجر الإلكتروني (riquid-store) مشروع Next.js 14 بنمط App Router مكتوب بـ TypeScript، ومنشور على Vercel عبر ملف vercel.json وملف .env.production مُودَعين في المستودع. وتسكن حالة السلة وحالة العميل في Zustand الإصدار 5 — مخزن بدلًا من سياق يُمرَّر عبر الخصائص، ممّا يُبقي السلة قابلة للوصول من أي موضع في الشجرة دون سلسلة من المزوّدات. وتمرّ المدفوعات عبر روابط Stripe الخاصة بـ React، أي @stripe/react-stripe-js فوق @stripe/stripe-js، فيحدث إدخال بيانات البطاقة داخل إطارات Elements المستضافة لدى Stripe ولا تلامس بيانات البطاقة الخام حالة التطبيق إطلاقًا. وتُجلب بيانات الخادم بـ axios وتُخزَّن مؤقتًا ويُعاد التحقّق منها بـ SWR، ممّا يمنح سلوك stale-while-revalidate في قراءات الكتالوج والطلبات. وطبقة المكوّنات هي shadcn/ui فوق @base-ui/react، مع class-variance-authority وclsx وtailwind-merge لتركيب أسماء الأصناف المبنيّة على المتغيّرات، وlucide-react للأيقونات، وFramer Motion الإصدار 12 للانتقالات. وهي الوحدة الوحيدة التي تملك منظومة اختبار: Vitest مع jsdom، وTesting Library (react وjest-dom وuser-event) وملف vitest.setup.ts — فالوحدة التي تتعامل مع المال هي الوحدة التي تحصل على الاختبارات.

وموقع الأعمال (riquid-business) تطبيق Next.js 14 بـ TypeScript خفيف عن قصد، وهو أيضًا على Vercel، ويعمل على المنفذ 4601 في بيئة التطوير ليتمكّن من العمل جنبًا إلى جنب مع المتجر محليًا دون تعارض في المنافذ. وهو يتشارك مع المتجر مفردات التنسيق والأدوات المساعدة — Tailwind وtailwindcss-animate وclsx وtailwind-merge وlucide-react وZustand وaxios — لكنّه لا يحمل شيئًا من ثقل المدفوعات أو الاختبارات أو الخرائط. وتلك المفردات المشتركة هي ما يمسك المنظومة معًا: ثلاث قواعد كود تلتقي عند إعدادات Tailwind نفسها، وأدوات تركيب الأصناف نفسها، ومجموعة الأيقونات نفسها، حتى يكون المكوّن المكتوب لواجهة واحدة مفهومًا في أي واجهة أخرى. ولا شيء يُجبر الوحدات على التقدّم في صفّ واحد؛ فلكلٍّ منها ملف package.json الخاصّ، وإعدادات الفحص اللغوي الخاصّة، وعملية النشر الخاصّة.