دليل استيراد وتصدير CSV

توفر Kononia أدوات مدمجة لترحيل مجموعات كبيرة من جهات الاتصال داخل وخارج People CRM باستخدام ملفات CSV.

1. مواصفات الاستيراد

لاستيراد جهات الاتصال، انتقل إلى دليل الأشخاص وانقر على استيراد ملف CSV.

الأعمدة المطلوبة

يجب أن يتضمن ملف CSV الخاص بك الرؤوس التالية كحد أدنى:

الاسم_الأول (مطلوب): الاسم الأول لجهة الاتصال.
الاسم_الأخير (مطلوب): الاسم الأخير لجهة الاتصال.

الحقول المدعومة

يتحقق محلل الاستيراد من الرؤوس عن طريق تحويلها إلى أحرف صغيرة واستبدال المسافات بشرطات سفلية (على سبيل المثال، يصبح “تاريخ الميلاد” “تاريخ_الميلاد”). يتم دعم الرؤوس التالية:

الاسم_الأول، الاسم_الأخير، الاسم_المفضل، البريد الإلكتروني، الهاتف، الهاتف_الجوال، الجنس، تاريخ_الميلاد، الحالة_الاجتماعية، حالة_العضوية، تاريخ_العضوية، الحرم الجامعي، الدور_العائلي، رقم_الظرف، address_line1، address_line2، city، state، zip، country، email_opt_in، sms_opt_in، directory_visible

قواعد التحليل وتطبيع البيانات

التحويل المنطقي: بالنسبة إلى email_opt_in وsms_opt_in وdirectory_visible، يقوم النظام بتسوية القيم true أو 1 أو yes (غير حساسة لحالة الأحرف) إلى true. يتم تحويل كافة القيم الأخرى إلى “خطأ”.
الاقتباسات: قم بلف الحقول التي تحتوي على فواصل أو فواصل أسطر بين علامتي اقتباس مزدوجتين (على سبيل المثال، "123 Main St, Apt 4A"). يتم تخطي علامات الاقتباس المزدوجة الموجودة داخل القيم كعلامات اقتباس مزدوجة (""`).
سياق المؤسسة: تعمل أداة الاستيراد المساعدة تلقائيًا على حل “معرف_المؤسسة” النشط للمستخدم النشط وإرفاقه بكل سجل مستورد.

معاينة التحقق من الصحة

بمجرد تحديد ملف CSV، تقوم الأداة بتحليل المحتوى محليًا وتوفير مربع حوار مقسم إلى علامتي تبويب:

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

تنفيذ الدفعة

يتم تحميل السجلات على دفعات متسلسلة مكونة من 100 سجل لمنع انتهاء مهلات الشبكة والبقاء ضمن قيود الحد الأقصى لقاعدة البيانات. عند الانتهاء، يتم تلقائيًا إبطال ذاكرة التخزين المؤقت لـ React Query لمفتاح الاستعلام ["people"].

2. مواصفات التصدير

يؤدي النقر فوق الزر تصدير ملف CSV الموجود في الدليل إلى تنزيل كامل لقائمة أعضاء المؤسسة.

تجاوز ترقيم الصفحات: لتجاوز حد استجابة Supabase القياسي، تستعلم أداة التصدير المساعدة عن السجلات في كتل متسلسلة من 1000 سجل حتى يتم سحب كافة الإدخالات.
مخطط التصدير: يتضمن التصدير جميع الأعمدة المدعومة البالغ عددها 23 عمودًا المذكورة أعلاه، مرتبة أبجديًا حسب الاسم_الأخير.
تشفير الأحرف: يتم تجميع الملف الذي تم إنشاؤه بتنسيق text/csv;charset=utf-8; Blob ويتم تنزيله من خلال المتصفح باستخدام اسم ملف ذو طابع زمني (على سبيل المثال، people-export-2026-06-05.csv).