تكامل نقاط الولاء في زد: ابنِ حول السجل لا الرصيد

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

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

هذا شرح مبني على الوثائق الحالية وليس إعلان إطلاق. تحققت من الوثائق المشار إليها في 27 سبتمبر 2026. وهي توثق عمليات القراءة والإعداد والتعديل، لكنها لا تعد بتسليم Exactly-once ولا تعرض Idempotency Header لتعديلات النقاط. لذلك يعامل التصميم نتيجة الشبكة الغامضة كمشكلة تسوية بدل افتراض أن إعادة المحاولة آمنة.

نمذج الحالات لا رصيدًا واحدًا

لا تحوّل كل استجابة إلى عمود واحد باسم `loyalty_points`. احتفظ على الأقل بمعرف المتجر والعميل، والرصيد المتاح المرصود، والرصيد المعلق الموجب والسالب، ووقت الملاحظة لدى المزود، وحالة المزامنة. احتفظ بسجل حركات المزود منفصلًا أو ببصمات ثابتة للحركات التي عالجتها. النسخة المحلية مخصصة لقراءات واجهة المتجر وبحث الدعم والتحليلات؛ وليست سجلًا منافسًا.

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

يمكن أن تبدو القراءة المحلية العملية هكذا:

create table loyalty_customer_projection (
  store_id text not null,
  customer_id text not null,
  available_points numeric not null,
  pending_points numeric not null,
  pending_negative_points numeric not null,
  observed_at timestamptz not null,
  history_cursor_fingerprint text,
  sync_state text not null,
  primary key (store_id, customer_id)
);

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

ضع سجل أوامر أمام كل تعديل للنقاط

تقبل واجهة تعديل نقاط العميل معرف العميل واتجاه `+` أو `-` وعدد النقاط وسببًا. وتتضمن الاستجابة الموثقة بيانات الحركة الناتجة. لكن الوثائق لا تعرض مفتاح Idempotency يرسله المستدعي. لذلك قد تؤدي إعادة POST بعد انتهاء المهلة إلى إضافة النقاط أو خصمها مرتين.

أنشئ أمرًا داخليًا قبل الطلب. امنحه Business Key فريدًا مثل `return:{return_id}:loyalty-reversal`، وسجل العميل والاتجاه والنقاط وسببًا مفهومًا، وافرض التفرد في قاعدة بياناتك. ثم أرسل الأوامر التي لم تُرسل فقط. بعد النجاح، اقرأ ملخص العميل أو سجله واربط الحركة المرصودة بالأمر.

planned -> sent -> confirmed
              \-> unknown -> reconciled-confirmed
                          \-> review-required

إذا انقطع الاتصال بعد الإرسال، ضع النتيجة في حالة `unknown`. لا ترسل POST مجددًا مباشرة. ابحث في السجل عن عميل واتجاه ومبلغ وسبب ونافذة زمنية مطابقة. إن كان الدليل واضحًا، فأكد الأمر الأصلي. وإن ظل غائبًا بعد مهلة مناسبة، فأعد المحاولة عبر مشغل مضبوط أو عامل بسياسة محاولات صريحة. وإذا كان يمكن لحدثين تجاريين حقيقيين امتلاك القيم نفسها، فأضف مرجع دعم أو طلب فريدًا إلى السبب عندما يكون ذلك مناسبًا واحتفظ باستجابة المزود.

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

افصل إعداد البرنامج عن استبدال العميل

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

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

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

نفّذ التسوية لأن استجابة النجاح ليست النظام كله

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

استخدم ترددات مختلفة حسب الخطر. سوِّ تعديل نقاط نتيجته مجهولة خلال دقائق. حدّث قراءة واجهة المتجر عند تسجيل دخول العميل أو وصوله إلى الدفع. وراجع العملاء غير النشطين بوتيرة أبطأ كثيرًا. أضف Jitter وConcurrency محدودة حتى لا يصنع متجر كبير اندفاعة API. وإذا لم تكن Pagination أوRate Limits للسجل صريحة في الوثائق التي تعتمدها، فقسها بأمان واجعل حجم الصفحة والتوازي قابلين للضبط.

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

قيّد الوصول وراقب أنماط الفشل

تستخدم الوثائق Scopes مختلفة للعمليات: تستخدم قراءات العميل `loyalty_program.read`، والكتابات `loyalty_program.read_write`، بينما تسمي بعض صفحات الإعدادات والتحليلات `third_loyalty_read`. اطلب الحد الأدنى الذي يحتاجه كل مكوّن. يجب ألا تحمل خدمة قراءة واجهة المتجر بيانات اعتماد قادرة على تعديل النقاط، وألا تشارك مهمة التحليلات Token عامل التعديلات. عالج 401 و403 و422 كلًا على حدة؛ فمشكلات Authentication وAuthorization وBusiness Input غير الصالح ليست أعطال بنية تحتية قابلة للمحاولة بالطريقة نفسها.

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

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

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

إعداد: Noor Yasser