المجموعات والبيانات

المجموعات هي جداول بيانات خاصة ببوتك. يمكنك تخزين الطلبات والأوامر والإجابات من المحادثات ونقاط اللعبة وتسجيل الجلسات — وكل ما يجمعه البوت من المستخدمين أو يتلقاه من التكاملات. يوجد القسم في القائمة اليسرى ضمن: البيانات → المجموعات.

ما هي المجموعة

تتكون المجموعة من حقول (مخطط يصف الأعمدة) وسجلات (صفوف من البيانات). كل سجل هو مجموعة قيم وفق حقول المجموعة؛ يُخزَّن داخلياً كمستند JSON مرن، لذا تتحمّل المجموعة إضافة حقول جديدة دون أي مشكلة.

يكون اسم المجموعة فريداً داخل البوت الواحد ويُستخدم كمعرّف في إجراءات التفاعلات (مثل leads وorders وscores).

أنواع الحقول

عند إنشاء المجموعة تحدد قائمة الحقول ونوع كل منها:

text — نص (الاسم، البريد الإلكتروني، التعليق).
number — رقم (المبلغ، الكمية، النقاط).
bool — نعم/لا (true / false).
datetime — تاريخ ووقت.
json — كائن أو مصفوفة متداخلة للقيم المركّبة.

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

إنشاء مجموعة

افتح البيانات → المجموعات واضغط إضافة.
حدد الاسم (بالأحرف اللاتينية بدون مسافات — يسهل الإشارة إليه في التفاعلات).
اضغط حقل لإضافة الأعمدة المطلوبة وحدد نوع كل منها.
عند الحاجة، حدد قواعد الاحتفاظ (انظر أدناه) ثم احفظ.

السجلات: العرض والتحرير

على بطاقة المجموعة زر بأيقونة جدول — يفتح نافذة البيانات بسجلات المجموعة:

عرض — تظهر جميع الصفوف في قائمة، حقل في كل خلية، بدءاً من الأحدث.
إضافة سجل — يفتح نموذجاً وفق مخطط المجموعة؛ يُحرَّر كل حقل بحسب نوعه (مفتاح تبديل لـbool، حقل إدخال JSON لـjson، إلخ).
تعديل (قلم) — تعديل صف موجود.
حذف (سلة) — حذف صف.

تُملأ السجلات أيضاً تلقائياً بواسطة إجراءات تفاعلات البوت (انظر أدناه). التحرير اليدوي والكتابة التلقائية يعملان على المجموعة ذاتها.

الاحتفاظ بالبيانات (Retention)

لمنع نمو المجموعة إلى ما لا نهاية، حدد قواعد الحذف التلقائي:

الاحتفاظ بحد أقصى من السجلات — عند تجاوز الحد تُحذف أقدم السجلات.
الاحتفاظ لمدة أقصاها (بالأيام) — تُحذف السجلات الأقدم من الفترة المحددة.

يُنفَّذ الحذف بواسطة عملية خلفية دورية؛ يمكن الجمع بين القاعدتين.

العمل مع البيانات من التفاعلات

ترتبط المجموعات ارتباطاً مباشراً بمحرر التفاعلات. في إجراءات التفاعل تتوفر:

إنشاء سجل — يضيف صفاً؛ تُؤخذ القيم من القوالب (مثل {{user.id}} و{{message.text}}). يمكن تحديد مفتاح إزالة التكرار حتى يُحدَّث الاستدعاء المتكرر الصف ذاته بدلاً من إضافة مكررات.
تحديث السجلات — يعدّل الصفوف المطابقة لشرط معين.
استعلام السجلات — يقرأ الصفوف في سياق التنفيذ كمصفوفة للتكرار عليها لاحقاً.
حذف السجلات — يحذف الصفوف وفق شرط.
حلقة (for-each) — تمر على مصفوفة من السياق وتُنفّذ الإجراءات المتداخلة لكل عنصر (مثل إرسال رسالة لكل عنصر في قائمة من المجموعة).

يمكن للبوت بذلك إدارة CRM وتجميع الطلبات ومنح النقاط وإنشاء التقارير دون قاعدة بيانات خارجية.

الوصول من Mini App

يمكن قراءة سجلات المجموعة من Telegram Mini App الخاصة ببوتك: تطلب الواجهة الأمامية بيانات المجموعة بالاسم مع المرشحات والحدود. يتيح ذلك عرض طلبات المستخدم أو سجله أو لوحة المتصدرين مباشرةً داخل Telegram.

نصائح

أعطِ الحقول أسماء قصيرة للآلات (email وtotal وpaid) — يسهل إدراجها في قوالب التفاعلات.
للكتابة الآمنة من التكرار (مثل «طلب واحد لكل مستخدم»)، استخدم مفتاح إزالة التكرار.
فعّل قواعد الاحتفاظ للسجلات المؤقتة والسجلات الزمنية لمنع تضخم المجموعة.
النوع json مناسب حين تكون بنية القيمة غير محددة مسبقاً.