كيفية بناء أداة استيراد CSV لتطبيق SaaS

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

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

إذا كانت المهمة الفورية استيرادًا إداريًا في Supabase، فاستخدم أولًا الشرح العملي للاستيراد المدمج.

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

قد ينص عقد مختصر لجهات الاتصال على ما يلي:

Operation: insert new contacts
Target: one approved application table
Source fields: external_contact_ref, email, display_name
Tenant: supplied by an authorized import job
Primary key: generated by the database
External identity: unique within tenant + source system
Missing display name: NULL
Existing external identity: report conflict; do not overwrite
Accepted set: frozen after review; edits require revalidation

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

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

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

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

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

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

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

احتفظ بالمعرّفات كسلاسل نصية. فقد يزيل التحويل الرقمي التلقائي الأصفار في البداية أو يقرّب رقم حساب طويلًا. تُوثّق خيارات المحلّل، مثل تحديد الأنواع ديناميكيًا ومعالجة العناوين والإبلاغ عن الأخطاء في Papa Parse، في مرجع API الخاص به؛ فاخترها عن قصد.

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

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

قد يعني عنوان مثل «Owner» في المصدر مندوب مبيعات، أو مساحة عمل، أو منشئ السجل القديم. اعرض وصف الوجهة وعينات من القيم، ولا تكتفِ بدرجة تشابه. احتفظ بخريطة الربط المؤكدة مع المهمة حتى يستطيع الدعم تفسير النتيجة لاحقًا.

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

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

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

نفّذ التحقق على طبقات، مع تقديم خطأ مفيد في أبكر نقطة موثوقة:

1. بنية الملف: الترميز المدعوم، والسجلات، والعناوين، والحدود.
2. قيم الحقول: الإلزامية، والأنواع، والنطاقات، والتنسيقات المقبولة.
3. العلاقات داخل الملف: التكرارات والمراجع المتكررة غير المتسقة.
4. قواعد العمل: الحالات المسموح بها، ودلالات الهوية، والصلاحيات.
5. فحوص الوجهة: القيود المنطبقة، ووجود المراجع، وسلوك الكتابة الفعلي.

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

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

تعرض المعاينة المفيدة أعداد السجلات المقبولة والمستبعدة، والتصحيحات المطلوبة، والتحويلات المعتمدة، والمستأجر المستهدف، والعملية. وضّح الفحوص التي أُجريت على وجهة فعلية، وتلك التي كانت ساكنة أو محلية.

سمِّ جولة التحقق التي لا تكتب بيانات بهذا الوصف الدقيق. المعاملة التي تجري عمليات كتابة فعلية ثم تتراجع عنها ليست بالضرورة تجربة بلا آثار جانبية: فقد لا تُعكس القيم المخصصة من المتتاليات والآثار التي بدأت خارج النظام. اختبر سلوك الكتابة مسبقًا في بيئة معزولة مخصصة لذلك.

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

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

عادةً ما يشير مرجع مثل «الشركة 42» إلى صف في النظام القديم. ابحث عن مقابل مفتاح خارجي معتمد ضمن نطاق الأسماء الصحيح للمستأجر والمصدر. عدم وجود تطابق ووجود عدة تطابقات حالتا فشل مختلفتان؛ واختيار الصف الأول يخفي الالتباس. أبقِ القيود النهائية للمفاتيح الأجنبية واتساق المستأجر مفروضة.

توضح الأدلة المفصلة بشأن صلاحية تحديد المستأجر وحلّ مراجع المفاتيح الأجنبية هذه الحدود. يتطلب ترتيب العمل عبر عدة جداول والتعامل مع الدورات خطة علاقات صريحة؛ وهما ليسا من ميزات ربط الأعمدة.

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

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

BEGIN
  authorize access to this job
  lock the existing job row FOR UPDATE
  look up receipt for (job_id, batch_number)
  if receipt exists:
    require matching payload hash and contract version
    return recorded result without inserting again
  else:
    check job state and the next expected batch
    validate and insert the approved rows
    insert receipt with identity, hash and result
    advance the job's committed progress
COMMIT

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

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

إذا كان يجب إرسال إشعارات أو webhooks بعد التثبيت، فيمكن لصندوق صادر يُكتب ضمن المعاملة تسجيل عمليات التسليم المنتظرة. ويظل التسليم بحاجة إلى قواعد مستقلة لإعادة المحاولة وعدم تكرار الأثر. أبقِ محتويات الصفوف المستوردة خارج حمولات الأحداث الاعتيادية.

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

إذا ثُبّتت الدفعات 1–4 وفشلت الدفعة 5، فأبلغ عن المجموعة الفرعية المثبتة وعن الباقي الذي فشل أو لم تُجرَ محاولته. قد يوقف زر الإلغاء العمل اللاحق؛ لكنه لا يستطيع أن يضمن التراجع عن دفعات مثبتة. تحتاج عملية التراجع إلى تغيير تعويضي منفصل يخضع للمراجعة، بما يشمل آثاره على المراجع والتعديلات اللاحقة.

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

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

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

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

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

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