المتجرمجرد البداية.

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

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

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

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

اشتغلنا على لوحة التاجر وواجهة المتجر والخدمات اللي بتوصلهم ببعض. الكود الحالي فيه إدارة منتجات فعلية ورقمية، متغيرات للمنتج، مجموعات وتصنيفات، مخزون، طلبات، عروض، توصيل، أدوات تشغيل، تحليلات، ومحرر لتصميم المتجر.

فيه كمان تنفيذ لمساعد Varq AI، وحزم قوالب، وواجهات headless، وأدوات للمطورين من خلال CLI وMCP. وجود التنفيذ هنا مش معناه إن كل ميزة اتفعلت تجاريا أو اتعتمدت عند كل مزود خارجي. كل جزء له مرحلة وأدلة قبول مناسبة ليه.

لوحة التاجر وواجهة العميل ليهم استخدام مختلف. التاجر ممكن يقضي وقت طويل بيعدّل ويفلتر ويراجع. العميل عايز يلاقي المنتج ويفهمه ويكمل طلبه. استخدمنا تطبيق Next.js لكل تجربة، وخدمات TypeScript مشتركة في طبقة الـAPI للتعامل مع منطق الدومين.

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

البنية دي منصة مقسمة لمجالات واضحة. مش بندّعي إن كل مجال microservice مستقل. المهم إن كل سلوك يبقى له مكان معروف: الكتالوج مسؤول عن المنتجات، القوالب مسؤولة عن التصميم وإصداراته، التجارة مسؤولة عن الطلب والدفع، والـworkers مسؤولة عن الشغل اللي عمره أطول من طلب المتصفح.

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

تطبيقات الويب في الملفات الحالية بتستخدم Next.js 15.5.27 وReact 18.3.1. TypeScript موجود في الواجهات والخدمات، وبيساعدنا نخلي العقود المشتركة واضحة. Tailwind CSS ومكونات مبنية على Radix بيدعموا نظام الواجهة، وdnd-kit بيدير التفاعل الهيكلي جوه محرر المتجر.

الـAPI مبني بـExpress، مع MongoDB وMongoose. اختيار قاعدة بيانات بتتعامل مع مستندات مناسب لوجود إعدادات منتجات وتصميمات متغيرة، بس الاختيار لوحده مش بيحل مشاكل التجارة. لازم يتحدد إيه اللي ينفع يتعدل، وإيه اللي بيمثل حدث حصل خلاص، وإيه اللي محتاج تنسيق بين أكتر من خطوة.

LiquidJS بيدعم مسار حزم القوالب المخصصة. Sharp وأدوات تخزين متوافقة مع S3 موجودين في شغل الميديا. تنفيذ الـAI بيستخدم SDK وprovider adapters. وفيه مشروع MCP منفصل بأدوات البناء بتاعته.

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

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

في Varqio، المحرر بيدير مستند التصميم، والمعاينة بتشتغل من خلال runtime المتجر نفسه. يعني مش بنرسم نسخة تقريبية من الصفحة جوه لوحة التاجر ونحاول نخليها شبه الحقيقي. أدوات الاختيار والتحرير بتشتغل حوالين العرض الفعلي للمتجر.

فيه registry مشترك بيعرف الأقسام والبلوكات المدعومة. إعدادات التاجر ليها تعريف، والتخزين ليه شكل، والـruntime ليه طريقة عرض. لما نضيف مكون جديد، المطلوب إن السلسلة دي تكتمل. ظهور الاسم في قائمة الإضافة لوحده مش كفاية.

مثال توضيحي: نفس الـHero على اللابتوب والموبايل

التاجر عامل عنوان كبير ومسافات واسعة على الديسكتوب. على الموبايل، العنوان محتاج عرض أضيق ومساحة أقل فوق وتحت. لو عندنا قيمة واحدة لكل الأجهزة، هنفضل نضحي بتجربة عشان التانية.

عشان كده، التصميم بيدعم إعدادات حسب الجهاز مع inheritance. الموبايل يقدر ياخد القيمة الأساسية، أو يغيرها لما فيه سبب. كده عندنا مستند واحد بتفاصيل responsive، مش تلات صفحات مستقلة لازم التاجر يراجعهم كل مرة.

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

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

استخدمنا dnd-kit في التعامل مع المؤشر واللمس والكيبورد. الترتيب والحركة بيغيروا مستند منظم. الـhistory بيميز بين عملية هيكلية، زي نقل قسم، وبين تعديلات صغيرة متقاربة، زي كتابة عنوان. ده بيخلي Undo أقرب للفعل اللي المستخدم فاكره.

الـautosave كان محتاج نفس الدقة. طلب الحفظ ممكن يتبعت، والتاجر يكمل تعديل قبل الرد. لو الرد القديم استبدل المحتوى الحالي، يبقى النظام مسح شغل أحدث وهو بيحاول يحفظ. الكود الحالي بيقبل نتيجة التطبيع من الحفظ لما المستند الحالي لسه مطابق للي اتبعت؛ غير كده بيحافظ على التعديل الجديد.

مثال توضيحي: الرد وصل متأخر

التاجر غيّر العنوان، وبعدها غيّر الوصف. رد حفظ العنوان وصل بعد تعديل الوصف. المطلوب إن الوصف الجديد يفضل موجود، وإن الحفظ يكمل عليه. استبداله بلقطة قديمة هيدي إحساس إن المحرر بيتصرف عكس المستخدم.

كمان فصلنا المسودة عن النشر. الـdraft مساحة شغل، والنسخة المنشورة snapshot ثابتة. الرجوع لتصميم قديم كمسودة مش هو نفس تغيير النسخة الحية. فيه savepoints وإصدارات تساعد على الاسترجاع، بس ده مش معناه إننا بنقدّم تحرير تعاوني لحظي أو نظام فروع مفتوح؛ دي قدرات تانية محتاجة تنفيذها وأدلتها.

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

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

وفي نفس الوقت، فيه فصل للنسخة المحلية لما محتاجة تختلف. صفحة حملة ممكن تبدأ من مجموعة مشتركة، وبعدها تحتاج صياغة أو ترتيب خاص. إعادة الاستخدام مش معناها فرض نفس النتيجة في كل مكان.

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

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

بنينا النموذج عشان يعبّر عن الاختلاف ده، ومعاه تصنيفات ومجموعات وحقول مخصصة. الحقل المكتوب بنوع واضح ينفع يتعرض ويتراجع ويتعامل معاه النظام بشكل أفضل من ملاحظة عشوائية متخزنة كنص وخلاص.

الاستيراد والتصدير كمان ليهم lifecycle. لما التاجر يرفع كمية منتجات، المتصفح مش المفروض يبقى هو الضامن إن العملية تكمل. وجود jobs وحالات ونتائج بيدي الشغل الطويل مكانه الطبيعي، وبيخلي الفشل الجزئي قابل للفهم بدل ما يبقى مجرد رسالة غامضة.

مثال توضيحي: المنتج اتغير بعد ما اتباع

العميل اشترى بسعر معين ووصف معين. التاجر عدّل المنتج بعدها. الطلب القديم لازم يفضل بيمثل اللي اتفق عليه وقت الشراء. عشان كده فيه فرق بين بيانات الكتالوج الحالية ولقطة البيانات داخل الطلب.

المبدأ ده مهم في الدعم والتقارير والمراجعة. لو كل حاجة بترجع لنسخة المنتج الحالية، يبقى تاريخ الطلب بيتغير من غير ما حد يعدّل الطلب نفسه. الفصل بين الكيان الحالي والحدث التاريخي بيحافظ على معنى العملية.

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

التنفيذ فيه checkout sessions ومحاولات دفع وأحداث من المزود وحالات للطلب وشغل للمخزون والتجهيز. المبلغ بيتخزن بوحدة العملة الصغرى ومعاه العملة، مش كرقم عشري شكل عرضه هو اللي بيحدد معناه.

الـworkers بتكمل بعض الشغل بعيد عن عمر request المتصفح. ده يسمح بمتابعة العملية واسترجاع الشغل اللي اتقطع حسب قواعده، بدل ما نجاح الطلب يتوقف على إن نفس الاتصال يفضل مفتوح.

مثال توضيحي: نتيجة الدفع اتبعتت مرتين

المزود بعت النتيجة، النظام تعامل معاها، بس رد الاستلام ماوصلش للمزود. فبعتها تاني. هنا تكرار الرسالة مش معناه عملية شراء جديدة. لازم النتيجة التجارية تفضل واحدة.

شغل Kashier الظاهر في commit سبتمبر امتد للـconnector والدفع والفواتير والأحداث والواجهة. ده بيوضح إن التكامل مش زرار بيتضاف في checkout. هو مجموعة علاقات لازم تتفق على نفس النتيجة.

الاختبارات المحلية بتثبت سلوك التنفيذ في ظروفها. اعتماد رحلة دفع أو استرجاع فعلية عند المزود محتاج بيئة اختبار ونتائج فعلية منه. عشان كده مش بنقدّم نجاح simulation باعتباره اعتماد كامل لخدمة خارجية.

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

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

مثال توضيحي: ١٢ محاولة وخصم واحد

عندنا ١٢ checkout مختلفين بيتنافسوا على استخدام واحد. المقبول إن السعة المسموحة بس هي اللي تتخصص. إعادة نفس المحاولة لازم تلاقي نتيجتها، والحجز المتحرر ينفع يرجع حسب القواعد، وتقليل الحد ماينفعش يرجّع مكان قديم خارج السعة للمنافسة.

دي مواصفات أقوى من جملة «الكوبون بيشتغل». هي بتوصف اللي هيحصل مع التزامن والتكرار وتغير الإعدادات. المثال متصل باختبار MongoDB مؤقت موثق، مش قصة حادثة إنتاج بنضيفها للدراسة عشان تبان مثيرة.

الموجود في المخزن مش هو المحجوز، والمُتاح للبيع مش هو اللي اتخصص للتجهيز. خلط الأرقام دي بيدي شاشة بسيطة، لكنه بيصعب تشغيل التجارة.

الكود فيه مواقع مخزون، حجوزات، تعديلات، خدمات للتوزيع والتوازن، والتعامل مع مخزون الطلب المدفوع. وفيه خدمات تجهيز بتربط الطلب التجاري بالشغل المطلوب عشان يخرج للعميل.

ده معناه إن «اتدفع» و«اتجهّز» و«اتشحن» مش نفس الحالة. التاجر محتاج يشوف كل واحدة ومعناها. لو الطلب مدفوع ولسه محتاج تخصيص قطعة أو تجهيز شحنة، الواجهة لازم توضّح الشغل المتبقي بدل ما تخبيه ورا علامة نجاح واحدة.

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

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

في محرر المتجر، اقتراح المساعد بيوصل لنفس مستند التصميم اللي التاجر بيعدّله بإيده. ده يمنع ظهور طريقتين مختلفتين لبناء نفس الميزة: واحدة للواجهة وواحدة للـAI.

كمان فيه دورة لاستخدام الرصيد: حجز قبل التنفيذ وتسوية بعده، مع التعامل مع النتيجة غير المؤكدة. انقطاع stream مش كفاية عشان نقول إن مفيش تكلفة، وبداية الطلب مش كفاية عشان نقول إنه اكتمل كله.

مثال توضيحي: الاقتراح بقى قديم

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

وجود الشغل ده في الكود مش معناه إننا قسنا جودة كل موديل أو زمن استجابة كل مزود أو وفّرنا نسبة محددة من وقت التاجر. القياسات دي محتاجة تقييم فعلي، ومش هنستبدلها بأرقام تسويقية.

الترجمة مهمة، بس لو اسم المنتج العربي طويل وخرج بره الصف، التجربة لسه مش مكتملة. ولو الأرقام والـSKU اتقلب ترتيبهم جوه النص، المستخدم هيتعب حتى لو كل الكلمات مترجمة صح.

راجعنا في تصميم التجربة فكرة اتجاه الكتابة، والمحتوى المختلط، والمساحات، والتنقل، والحوارات، وعرض الحالات. لوحة التاجر فيها light وdark، لكن هوية المتجر ليها إعداداتها المستقلة. تغيير شكل لوحة التاجر مش المفروض يغير البراند اللي العميل بيشوفه.

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

صور الدراسة مأخوذة من بيئة ديمو محلية وبيانات صناعية. كل صورة ليها اسم شاشة وحجم وموضع مقترح في المقال. ده بيساعد القارئ يفهم اللي قدامه، ويساعد فريق الموقع يستخدم الأصول من غير ما ينسب بيانات الديمو لعملاء حقيقيين.

التاريخ الموجود في Git بيدينا نقاط واضحة، من غير ما نخترع مواعيد سبرنتات أو حجم فريق أو مواقف حصلت في ميتنجات.

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

شغل الدومينات كمان بيوضح إن اسم النطاق ودرجة جاهزيته وارتباطه بالخطة التجارية مش سؤال واحد. الفصل بينهم بيخلّي الواجهة أصدق في وصف اللي ناقص بدل زرار «متصل» بيختصر حالات مختلفة.

الـbuild بيقول إن الكود اتبنى. اختبار المنطق بيقول إن سلوك معين نجح في شروط معينة. اختبار متصفح بيقول إن رحلة حصلت فعلا في الواجهة. اختبار مزود بيقول إن الطرف الخارجي رد بالنتيجة المتوقعة. مش بنستخدم واحد مكان التاني.

بالنسبة للمحرر، المهم إن المستند يتحفظ ويتعرض بنفس المعنى في المعاينة والمتجر. بالنسبة للعروض، المهم إن التزامن يحترم السعة. بالنسبة للعمليات الطويلة، المهم إن الانقطاع والتكرار ليهم نتيجة مفهومة.

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

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

Varqio بتجمع تصميم المنتج مع هندسة التجارة. عندنا واجهات للتاجر والعميل، وبينهم علاقات واضحة: المنتج بالشراء، المسودة بالنشر، نتيجة الدفع بالطلب، المخزون بالتجهيز، والمساعد بنفس مستند التحرير.

خصصنا التجربة في الحاجات اللي التاجر بيتعامل معاها كل يوم: تنظيم المنتجات، شكل المتجر، مراجعة التغييرات، متابعة التشغيل، والانتقال بين العربي والإنجليزي. واشتغلنا على مشاكل أقل ظهورا، زي الردود المتأخرة، الأحداث المتكررة، تعارض الإصدارات، والتغليف للنشر.

المرحلة الجاية هي استكمال أدلة التأهيل لتجربة تجار محدودة. مش محتاجين نخترع أرقام نمو عشان نحكي قصة هندسية قوية. التنفيذ والقرارات والأمثلة الواضحة بيقدموا صورة أدق عن الشغل.

لو بتبني منتج تجارة فيه التعقيد ده، Softworks تقدر تساعدك تربط رحلة المستخدم بتصميم الواجهة والخدمات والبيانات. البداية عندنا بتكون من العملية اللي لازم تنجح، وبعدها بنبني النظام اللي يخلي أجزائها متفقة.

Varqio منصة تجارة ولا أداة تصميم مواقع؟

منصة تجارة جواها أداة لبناء واجهة المتجر. الكتالوج والشراء والطلبات بيمثلوا السلوك التجاري، والقالب بيعبّر عن هوية التاجر.

المعاينة بتختلف عن المتجر المنشور؟

القرار المعماري هو استخدام runtime المتجر نفسه في المعاينة، مع مستندات وإصدارات منظمة. ده بيقلل أسباب الاختلاف وبيخلي الاتفاق بينهم قابل للاختبار.

كل الميزات متفعلة لكل التجار؟

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

الأمثلة دي حصلت لعملاء فعلا؟

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

الصور فيها بيانات حقيقية؟

الصور المرفقة للديمو المحلي، وبياناتها صناعية. الهدف شرح الواجهة، مش عرض نشاط تجاري حقيقي.