الاصطلاحات

المبلغ عدد صحيح#

كل قيمة مالية عدد صحيح بالوحدات الصغرى للعملة. فالمجموع 185000 بالليرة السورية يعني 1,850.00 لا مئة وخمسة وثمانين ألفاً. لا تُحوّل المبالغ إلى أعداد عشرية أبداً: اقسم على معامل الوحدة الصغرى لحظة العرض فقط، وأجرِ كل العمليات الحسابية على الأعداد الصحيحة.

التواريخ بصيغة ISO 8601 وبتوقيت UTC#

كل طابع زمني بصيغة ISO 8601 وينتهي بحرف Z. حوّله إلى التوقيت المحلي للتاجر عند العرض إن شئت، لكن خزّنه وقارنه بتوقيت UTC — ففارق التوقيت في سوريا ليس ثابتاً طوال العام، و«طلبات اليوم» المحسوبة بالتوقيت المحلي ستضم أو تسقط ساعةً كاملة بصمت.

المعرّفات مبهمة#

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

القوائم تأخذ وسيط options#

تتشارك استعلامات القوائم شكلاً واحداً: وسيط `options` يضم `take` و`skip` و`sort` و`filter`، ويعيد `items` و`totalItems`. تصفَّح بـ take و skip، واقرأ totalItems لتعرف متى تتوقف بدل أن تطلب حتى تصلك صفحة فارغة.

query {
  products(options: {
    take: 50,
    skip: 100,
    sort: { updatedAt: DESC },
    filter: { enabled: { eq: true } }
  }) {
    totalItems            # page until skip + take >= totalItems
    items { id name slug }
  }
}

الزبائن يخصون متجراً واحداً#

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

كل شيء مقيّد بمتجر واحد#

رمز المتجر في طلبك هو ما يحدد ما هو موجود. ومعرّف يخص تاجراً آخر لا يعيد خطأ صلاحيات — بل ببساطة لا يوجد، لأنه من منظور مفتاحك غير موجود. يفرض الخادم هذا على كل طلب، فلا حاجة لأن ترشّح النتائج احترازياً.