كيف وسعنا Medusa لبناء سوق مستندات قانونية

تبيع JuraDocs مستندات قانونية، لكن المنتج الحقيقي هو الثقة. يحتاج المشتري إلى معرفة أن البائع محام حقيقي، وأن الملف آمن للنشر، وأن التحويل يمكن تفسيره إذا أُعيدت محاولة دفع أو webhook أو تحويل لاحقاً. نظام تجارة عادي لا يضمن ذلك وحده.

قدمت لنا Medusa المنتجات والسلال والطلبات والمستخدمين والمتاجر وسير العمل وأساس لوحة الإدارة. احتاجت JuraDocs إلى طبقة السوق القانونية حول هذا الأساس: صلاحيات المهن، والتحقق من البائعين عبر السجلات، ووصول الملفات حسب الدور، وتقسيم الرسوم، وسجلات التحويل، والفواتير، وأدوات التشغيل.

لذلك أبقينا Medusa كنظام التجارة تحت JuraDocs، ثم جعلنا مفاهيم السوق القانونية واضحة بدلاً من دفنها في metadata المنتجات.

أبقينا نموذج Medusa بدلاً من مقاومته

توصي وثائق Medusa الخاصة بالأسواق باستخدام نماذج بائعين مخصصة، وروابط بين الوحدات، ومسارات محمية للبائعين، وتخصيص سير العمل. هذا كان قريباً جداً مما احتاجته JuraDocs. لم نعمل fork من Medusa، بل ربطنا مجال JuraDocs بسجلات Medusa عبر نماذج قابلة للربط، فبقيت سجلات التجارة نظيفة، وبقيت ملكية البائع والصلاحيات وحالة التحويل قابلة للاستعلام.

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

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

أصبح التسجيل سير عمل لا نموذجاً

تدفق التسجيل العادي ينشئ مستخدماً وربما ملف عميل ثم يتوقف. في JuraDocs يوجد قرار أكبر عند التسجيل، والمهنة هي التي تحدده: هل هذا حساب يشتري فقط، أم حساب يجب أن يصبح بائعاً وله ملف بائع ومتجر؟

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

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

هذا هو الفرق بين جدول بائعين وبوابة ثقة. يجب أن تعرف JuraDocs إن كان الشخص مؤهلاً لنشر مادة قانونية مدفوعة قبل أن يعمل أي سير منتج.

للمستند القانوني دورة حياة

تستطيع Medusa دعم أنماط التجارة الرقمية، لكن JuraDocs احتاجت دورة حياة أكثر صرامة للمستندات. الملف الأصلي، والملف المعالج، والملف الذي يراه المشتري ليست دائماً الشيء نفسه.

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

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

أصبح الدفع تسوية واعية بالبائع

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

بعد نجاح هذه الفحوص، يجب أن ينتج النقر الواحد ثلاثة أشياء متفقة: الطلب، ودفع Stripe، وسجل لكل بائع يوضح ما يستحقه. هذه هي النقطة التي تتجاهلها أغلب شروحات multi-vendor. عرض عدة بائعين في صفحة واحدة سهل. الصعب هو أن ينتج الشراء طلباً وخصماً وتحويلات بائعين متطابقة وقابلة للاسترداد إذا فشل شيء في المنتصف.

أصبحت حصص البائع دفتر التحويلات

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

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

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

أصبحت idempotency جزءاً من التصميم

كود الدفع يُعاد تنفيذه. المتصفحات تعيد المحاولة. المستخدمون ينقرون مرتين. تصل webhooks أكثر من مرة. وقد يتوقف worker في منتصف العمل. إذا لم يتحمل النظام ذلك، فهو غير جاهز لمال سوق حقيقي.

يعتمد تصميم الدفع على سجلات idempotency: مفتاح، والفاعل خلف الطلب، وطريقة لمقارنة جسم الطلب، وحالة المعالجة، والرد الذي يمكن إعادته، ومراجع كافية لاسترداد الطلب أو جلسة الدفع. إذا عاد الطلب نفسه، يستطيع النظام إرجاع النتيجة نفسها. وإذا استُخدم المفتاح نفسه لطلب مختلف، يرفض التعارض. وإذا تعلقت المعالجة، لدى النظام مسار استرداد بدلاً من تجاهل ما حدث.

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

• تحمي idempotency الدفع من الطلبات والجلسات المكررة.
• تحمي سجلات webhook المعالجات من تنفيذ العمل نفسه مرتين.
• تحمي أقفال المعالجة تحويلات البائعين من workers متزامنين.
• تجعل حالة إعادة المحاولة وقوائم الفشل مشكلات التحويل مرئية تشغيلياً.

كان عمل الإدارة جزءاً من المنتج

في JuraDocs، شاشات الإدارة هي المكان الذي تتعامل فيه المنصة مع الثقة والاستثناءات. يشمل ذلك المستخدمين المدارين، وإنشاء البائعين والعملاء، وصلاحيات المهن، والبحث في سجلات النقابات، وحالات التحذير، وإعداد الفواتير، والمراجعات، والإحصاءات، وإعدادات معالجة المستندات، ورؤية التحويلات.

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

ما قدمته Medusa وما أضفناه

قدمت Medusa العمود الفقري التجاري: كائنات الكتالوج، والسلال، والطلبات، والعملاء، والمتاجر، وسير العمل، والوحدات، والروابط، وبنية خلفية يمكن توسيعها دون البدء من الصفر.

بنينا طبقة JuraDocs: التسجيل المهني، وربط البائع بالمتجر، وصلاحيات المهن، ومعالجة المستندات القانونية، وحماية الوصول إلى الملفات، وفحوص الشراء، ولوحات البائعين، وتهيئة Stripe Connect، وحصص البائعين، والتحويلات القابلة لإعادة المحاولة، والفواتير، وضوابط الإدارة، وتجربة متعددة اللغات للمشتري والبائع.

التفصيل المهم أن هذه ليست ميزات منفصلة موزعة حول التطبيق. إنها تلمس التدفق نفسه. مهنة البائع تحدد إن كان يستطيع البيع. ملفه كبائع يحدد ملكية المتجر. ملكية المتجر تحدد ملكية المنتج. ملكية المنتج تؤثر في التحقق عند الدفع. الدفع ينشئ حصص البائعين. وحصص البائعين تقود التحويلات ولوحات البائعين والفواتير والاسترداد الإداري.

ما الذي أنصح به فريقاً آخر

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

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

الخلاصة

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

الدرس بسيط: أعطتنا Medusa أساس التجارة. وأصبحت JuraDocs قابلة للحياة عندما أصبحت الثقة وسلامة المستندات ومحاسبة البائعين مفاهيم أساسية حول ذلك الأساس.