Claude Code لصحة استيراد/تصدير البيانات: خطوات عملية

ماذا يحدث عادة مع استيرادات CSV و JSON

نادراً ما تفشل الاستيرادات لأن الكود "خاطئ". إنها تفشل لأن البيانات الحقيقية فوضوية وغير متناسقة ومن أشخاص لم يروا افتراضاتك.

مشاكل CSV عادةً تتعلق بالشكل والتنسيق. مشاكل JSON عادةً تتعلق بالمعنى والأنواع. كلاهما يمكن أن يكسر بطرق تبدو بسيطة لكنها تنتج نتائج مربكة.

تظهر هذه المشاكل مرارًا وتكرارًا في تذاكر الدعم:

• حقول مطلوبة مفقودة (email, id, country) أو أعمدة أُعيد تسميتها بواسطة شخص "نظف" الملف
• تواريخ غريبة (01/02/03، 2024-13-01، أرقام تسلسلية من Excel، مناطق زمنية مختلطة)
• أعمدة إضافية أو كائنات JSON متداخلة غير متوقعة أضافها أداة أخرى
• انجراف في النوع ("00123" يصبح 123، true/false يصبح "yes"/"no")
• تكرارات وتقارب في السجلات (نفس id مرتين، أو نفس الشخص بحروف مختلفة)

الصحة ليست مجرد "هل استورد؟". عليك أن تقرر أي النتائج مسموح بها، لأن المستخدمين يلاحظون الأخطاء الصامتة أكثر من الفشل الصارخ.

معظم الفرق يمكنها الاتفاق على ثلاث نتائج:

• Accepted: جميع الصفوف أو السجلات صالحة وتم استيرادها
• Rejected: لا شيء يُستورد لأن الملف غير موثوق (عناوين خاطئة، ترميز سيئ، JSON غير قابل للقراءة)
• Partially accepted: السجلات الصالحة تُستورد، والسجلات غير الصالحة تُتخطى مع أسباب واضحة

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

حدد أهدافًا تقلل الدورة: محاولات أقل، إصلاحات أسرع، نتائج متوقعة. قبل أن تكتب القواعد، قرر ماذا يعني "جزئي" (وهل تسمح به أم لا)، كيف ستبلغ عن مشاكل على مستوى الصف، وماذا يجب أن يفعل المستخدمون بعد ذلك (تعديل الملف، مطابقة الحقول، أو تصدير نسخة مصححة). إذا كنت تستخدم منصة توليد مثل Koder.ai (koder.ai) لإنشاء المحققات والاختبارات بسرعة، يظل عقد الاستيراد هو ما يحافظ على ثبات هذا السلوك أثناء تطور المنتج.

قرر عقد الاستيراد قبل كتابة القواعد

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

ابدأ بالصيغ، وكن صريحًا. "CSV" يمكن أن يعني فاصلة أو فاصلة منقوطة، صف عنوان أم لا، UTF-8 أم "ما أنتجته Excel". بالنسبة لـ JSON، قرر هل تقبل كائنًا واحدًا، أم مصفوفة من السجلات، أم JSON Lines (كائن JSON واحد لكل سطر). إذا قبلت JSON متداخلًا، حدد المسارات التي تقرأها وتلك التي تتجاهلها.

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

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

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

قائمة فحص عقد يمكنك لصقها في مواصفات:

• الصيغ والترميز المقبول (فاصل CSV، JSON مقابل JSON Lines، دعم التداخل)
• قواعد الحقول (مطلوب/اختياري/قيم افتراضية، القيم المسموح بها)
• قواعد التطبيع (القص، الحالة، صيغ التواريخ/الأرقام)
• تعريف التكرار والتعامل معه (نطاق الكشف، السلوك المختار)
• موقع التحقق (عميل، خادم، أم كلاهما)

مثال: استيراد "العملاء". إذا كان البريد الإلكتروني هو المفتاح الفريد، قرر هل " [email protected] " يساوي "[email protected]"، هل يُسمح بالبريد المفقود عند وجود external_id، وهل يجب رفض التكرارات داخل الملف حتى لو لم يكن هناك تطابق في قاعدة البيانات. بمجرد تثبيت هذا العقد، يصبح السلوك المتناسق عبر الواجهة وAPI أسهل بكثير، سواءً نُفِّذ في Koder.ai أو في أي مكان آخر.

قواعد تحقق قابلة للقراءة والاختبار

غالبًا ما تبدأ الاستيرادات الفوضوية بدالة validate() عملاقة واحدة. النهج الأنظف هو قواعد متعددة الطبقات بأسماء واضحة ودوال صغيرة. هذا يجعل التغييرات أسهل للمراجعة والاختبارات أسهل للكتابة.

ابدأ بقواعد مستوى الحقل: تحقق قيمة واحدة يمكن أن تمر أو تفشل بمفردها (النوع، النطاق، الطول، القيم المسموح بها، regex). اجعلها مملة ومتوقعة. أمثلة: email يطابق نمط بريد أساسي، age عدد صحيح بين 0 و120، status أحد active|paused|deleted.

أضف قواعد عبر الحقول فقط حيث تهم. هذه التحققات تعتمد على عدة حقول، والأخطاء تختبئ هنا. أمثلة كلاسيكية: يجب أن يكون startDate قبل endDate، أو total يساوي subtotal + tax - discount. اكتب هذه القواعد بحيث تشير إلى حقول محددة، لا إلى "سجل غير صالح" فقط.

فصّل قواعد مستوى السجل عن قواعد مستوى الملف. قاعدة مستوى السجل تفحص صفًا واحدًا (CSV) أو كائنًا واحدًا (JSON). قاعدة مستوى الملف تتحقق من التحميل ككل: وجود عناوين مطلوبة، المفتاح الفريد لا يتكرر عبر الصفوف، عدد الأعمدة يطابق التوقعات، أو أن الملف يعلن نسخة مدعومة.

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

هيكل يبقى قابلًا للقراءة:

• Normalize: تحويل المدخلات الخام إلى شكل معياري.
• Validate fields: فحوصات صغيرة قابلة لإعادة الاستخدام لكل حقل.
• Validate relationships: تحقق عبر الحقول مع أهداف واضحة.
• Validate file rules: العناوين، التكرارات، ودعم الإصدارات.
• Test each layer: اختبارات وحدة لكل قاعدة، بالإضافة إلى بعض ملفات النهاية للنهاية.

رقّم قواعدك. ضع schemaVersion (أو "profile" الاستيراد) في الملف أو طلب الـ API. عندما تغير ما يعنيه "صالِح"، يمكنك إعادة استيراد تصديرات قديمة باستخدام النسخة القديمة. هذا القرار الوحيد يمنع الكثير من تذاكر "كان يعمل بالأمس".

صمم تنسيق تقارير أخطاء يمكن للناس العمل عليه

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

ابدأ بشكل كائن خطأ ثابت واستمر في الثبات عبر CSV و JSON. يمكنك استخدام Claude Code لاقتراح مخطط وبعض الأمثلة الواقعية، ثم قفله كجزء من عقد الاستيراد.

كائن خطأ ثابت

عامل كل خطأ كسجل صغير بحقول لا تتغير. يمكن أن يتطور النص، لكن يجب أن تبقى الرموز والموقع ثابتين.

• code: معرف قصير وثابت مثل REQUIRED_MISSING أو INVALID_DATE
• message: جملة مقروءة للبشر لعرضها في الواجهة
• path: مكان المشكلة (مؤشر JSON مثل /customer/email، أو اسم عمود مثل email)
• row أو line: للـ CSV، أدرج رقم الصف 1-based (ومع خيار تضمين السطر الأصلي)
• severity: على الأقل error و warning

اجعل الأخطاء قابلة للتنفيذ. أدرج ما توقعت وما رأيت، وعند الإمكان اعرض مثالًا ينجح. مثال: المتوقع YYYY-MM-DD، الفعلي 03/12/24.

تجميع للواجهة وتصحيح الأخطاء

حتى لو أعطيت قائمة مسطحة، أدرج بيانات كافية لتجميع الأخطاء حسب الصف والحقل. كثير من واجهات المستخدم تريد "الصف 12 لديه 3 مشاكل" ثم تبرز كل عمود. فرق الدعم تحب التجميع لأن الأنماط تصبح واضحة (مثلاً كل الصفوف تفتقد country).

استجابة مضغوطة قد تبدو هكذا:

{
  "importId": "imp_123",
  "status": "failed",
  "errors": [
    {
      "code": "INVALID_DATE",
      "message": "Signup date must be in YYYY-MM-DD.",
      "path": "signup_date",
      "row": 12,
      "severity": "error",
      "expected": "YYYY-MM-DD",
      "actual": "03/12/24"
    },
    {
      "code": "UNKNOWN_FIELD",
      "message": "Column 'fav_colour' is not recognized.",
      "path": "fav_colour",
      "row": 1,
      "severity": "warning"
    }
  ]
}

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

ماذا يجب أن تُرجع واجهة الاستيراد عند النجاح أو الفشل

لتجنب "الاستيرادات الغامضة"، يجب أن تجيب استجابة الـ API على سؤالين: ماذا حدث، وماذا يجب أن يفعل المستخدم بعد ذلك؟

أعد ملخص استيراد واضح (في كل مرة)

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

تضمّن:

• أعداد created, updated, skipped, failed
• totalRows (أو totalRecords لـ JSON)
• mode (مثلاً: "createOnly", "upsert", أو "updateOnly")
• طوابع زمنية startedAt و finishedAt
• correlationId يمكن للدعم طلبه

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

أدرج أخطاء قابلة للتنفيذ، وطريقة لجلب التقرير الكامل

لا تُرمِ 10,000 خطأ صف في الاستجابة. أعد عينة صغيرة (مثلاً 20) تُظهر النمط، ووفّر وسيلة منفصلة لاسترجاع التقرير الكامل إذا لزم.

اجعل كل خطأ محددًا وثابتًا:

• الموقع: رقم الصف (CSV) أو مسار يشبه مؤشر JSON (JSON)
• اسم الحقل
• رمز الخطأ (قابل للقراءة آليًا)
• الرسالة (مقروءة للبشر)
• القيمة المرفوضة (كن حذرًا مع البيانات الحساسة)

شكل استجابة مثال (نجاح به بعض فشل الصفوف):

{
  "importId": "imp_01HZY...",
  "correlationId": "c_9f1f2c2a",
  "status": "completed_with_errors",
  "summary": {
    "totalRows": 1200,
    "created": 950,
    "updated": 200,
    "skipped": 10,
    "failed": 40
  },
  "errorsSample": [
    {
      "row": 17,
      "field": "email",
      "code": "invalid_format",
      "message": "Email must contain '@'.",
      "value": "maria.example.com"
    }
  ],
  "report": {
    "hasMore": true,
    "nextPageToken": "p_002"
  },
  "next": {
    "suggestedAction": "review_errors"
  }
}

لاحظ حقل next. حتى حمولة نجاح بسيطة يجب أن تساعد المنتج على التحرك: عرض شاشة مراجعة، عرض إعادة محاولة، أو فتح المجموعة المستوردة.

عرّف idempotency حتى لا تتكرر الإنشاءات

الناس يعيدون المحاولة. الشبكات تفشل. إذا استُورد نفس الملف مرتين، تريد نتائج متوقعة.

كن صريحًا بشأن idempotency: تقبل idempotencyKey (أو احسب هاش الملف)، وأعد importId الموجود إذا كان الطلب مكررًا. إذا كان وضعك upsert، حدد قاعدة التطابق (مثلاً "البريد الإلكتروني هو المفتاح الفريد"). إذا كان create-only، عدّ "skipped" للتكرارات، لا "created again".

استخدم الحالة المناسبة للفشل، لكن احتفظ بالشكل ثابتًا

إذا كان الطلب كله غير صالح (مصادقة سيئة، نوع محتوى خاطئ، ملف غير قابل للقراءة)، افشل بسرعة وأعد status: "rejected" مع قائمة أخطاء قصيرة. إذا كان الملف صالحًا لكن هناك مشاكل على مستوى الصفوف، عاملها كوظيفة مكتملة مع failed > 0 حتى يتمكن المستخدمون من الإصلاح وإعادة الرفع دون فقدان الملخص.

كيف تستخدم Claude Code لتوليد قواعد وأمثلة

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

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

You are helping design an importer for CSV and JSON.
Output a Markdown table with columns:
Field | Type | Required? | Normalization | Validation rules | Default | Pass examples | Fail examples
Rules must be testable (no vague wording).
Then output:
1) A list of edge cases to test (CSV + JSON).
2) Proposed test names with expected result (pass/fail + error code).
Finally, list any contradictions you notice (required vs default, min/max vs examples).

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

لسيناريو محدد: تخيل استيراد "العملاء" من CSV: email مطلوب، phone اختياري، و signup_date افتراضيًا اليوم إذا غاب. يجب أن يُشير النموذج إلى تناقض إذا قلت أيضًا "signup_date مطلوب". يجب أن يقترح اختبارات مثل import_customers_missing_email_returns_row_error ويحدد رمز الخطأ وشكل الرسالة التي ترجعها.

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

خطوة بخطوة: اختبارات fuzz لملفات CSV و JSON

اختبارات fuzz تمنع "الملفات الغريبة" من أن تصبح تذاكر دعم. ابدأ بمجموعة صغيرة من ملفات صحيحة معروفة، ثم ولد آلاف التباينات الطفيفة وتأكد أن المستورد يتعامل بأمان ووضوح.

ابنِ مجموعة بذور، ثم حرّضها

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

ثم أضف محوّلًا آليًا يغيّر شيئًا واحدًا في كل مرة. اجعل التغييرات قابلة لإعادة التشغيل بتسجيل البذرة العشوائية حتى يمكنك إعادة تشغيل الفشل.

أبعاد الفز التي تلتقط معظم المشاكل الواقعية:

• مشاكل الترميز: UTF-8 مع BOM، تسلسلات بايت غير صالحة، تطبيع Unicode مختلط
• مشاكل الهيكل: عناوين مفقودة، أعمدة/حقول إضافية، فاصل خاطئ، فواصل زائدة
• الاقتباس والأسطر الجديدة: اقتباسات غير مغلقة، أسطر جديدة مدمجة، CRLF مقابل LF، هروب غير متسق
• حواف النوع: أعداد صحيحة ضخمة، NaN/Infinity (JSON)، سلاسل فارغة مقابل null، حشو بمسافات
• الحجم والحدود: حقول طويلة جدًا، صفوف كثيرة، مفاتيح مكررة، مصفوفات عميقة

لا تتوقف عند الصياغة. أضف فز معنوي أيضًا: بدل الحقول المشابهة (email مقابل username)، تواريخ متطرفة، معرفات مكررة، كميات سالبة، أو قيم تنتهك enums.

عرّف ماذا يعني "نجاح" ثم اقفل المعايير

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

مجموعة قواعد نجاح عملية:

• لا انهيار، لا مهلات، ولا قفزات ذاكرة تتجاوز حدك
• أخطاء واضحة بمؤشرات صف/حقل (CSV) أو مسارات JSON
• رموز أخطاء مستقرة عبر التشغيل لنفس الفشل
• لا كتابة جزئية ما لم تدعم النجاح الجزئي صراحة
• الاستيرادات الناجحة تنتج نتائج متطابقة بغض النظر عن تنسيقات غير ضارة (مثل المسافات)

شغّل هذه الاختبارات في CI على كل تغيير. عندما تجد فشلًا، احفظ الملف بالضبط كـ fixture وأضف اختبار ارتداد حتى لا يعود.

إذا استخدمت Claude Code في العمل، اطلب منه توليد ملفات بذرة تتوافق مع عقدك، خطة تحوير، والمخرجات المتوقعة للأخطاء. أنت تختار القواعد، لكنه يعطيك سطح اختبار واسع بسرعة، خاصة لحالات اقتباس CSV وحواف JSON.

المصائد الشائعة التي تسبب تذاكر دعم متكررة

معظم تذاكر الاستيراد تنشأ من قواعد غير واضحة وردود فعل غير مفيدة.

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

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

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

مشاكل ترميز النصوص تسبب تذاكر عنيدة. UTF-8 هو الافتراضي الصحيح، لكن CSV الحقيقية غالبًا ما تتضمن BOM، علامات اقتباس معقوفة، أو مسافات غير قابلة للكسر منسوخة من جداول بيانات. عامل هذه الحالات باستمرار وبلغ عما اكتشفته حتى يتمكن المستخدمون من تعديل إعدادات التصدير لديهم.

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

مصائد جديرة بالحماية مسبقًا:

• تحليل "أفضل محاولة" غير موثق يتغير مع الزمن
• أخطاء بدون مؤشرات صف/حقل ورمز خطأ ثابت
• استيرادات كل شيء أو لا شيء بدون خيار صارم مقابل جزئي
• UTF-8، BOM، والأحرف غير المرئية غير مُعالَجة باستمرار
• تغييرات رموز الأخطاء التي تكسر التعامل على جانب العميل

مثال: زبون يصدر CSV من Excel، الذي يضيف BOM ويعالج التواريخ كـ 03/04/2026. يخمن مستوردك MM/DD، لكن العميل كان يتوقع DD/MM. إذا تضمن تقرير الخطأ الصيغة المكتشفة، الحقل المحدد، واقتراحًا للإصلاح، يمكن للمستخدم تصحيحها دون تبادل رسائل.

قائمة فحص سريعة قبل إطلاق مستورد

معظم مشاكل الاستيراد اختلافات صغيرة بين ما يعتقد المستخدم أن الملف يعنيه وما يقبله نظامك. اعتبر هذا بوابة إصدار.

• العناوين وأسماء الحقول: تأكد من وجود الأعمدة المطلوبة، الأسماء تطابق القواعد، والازدواجيات مرفوضة. قرر ماذا تفعل بالأعمدة الزائدة (تجاهل، تحذير، فشل) وابقَ على هذا السلوك.
• أنواع البيانات والتنسيقات: قفل طريقة التحليل للأعداد الصحيحة مقابل العشرية، البوليانات (true/false, 0/1, yes/no)، التواريخ والطوابع الزمنية (قواعد المنطقة الزمنية). فضّل تنسيقًا واحدًا مقبولًا لكل حقل.
• القيم الفارغة والمفقودة: حدد ماذا يعني السلسلة الفارغة لكل حقل. فصل الحقل المفقود، null الصريح، والنص الفارغ.
• حجم وحدود الأمان: حدد حدود حجم الملف، الحد الأقصى للصفوف، وأقصى طول للحقل. افشل مبكرًا مع رسالة واضحة.
• أخطاء حتمية: نفس المدخل السيئ يجب أن يُنتج نفس رمز الخطأ وشكل الرسالة في كل مرة.

اختبار عملي: استخدم ملف متعمد الفوضى. مثال: CSV به العنوان مكرر (عمودين "email"), حقل بولياني يستخدم "Y"، وتاريخ كـ "03/04/05". لا يجب أن يخمن المستورد. إما يطبق قاعدة مطابقة موثقة أو يرفض مع خطأ محدد.

فحصان غالبًا ما يتجاهلهما الفرق:

أولًا، تحقق أن المستورد يبلغ عن الأخطاء بتفاصيل كافية لتصحيح الملف المصدر. "تاريخ غير صالح" غير قابل للتنفيذ. "الصف 42، العمود start_date: المتوقع YYYY-MM-DD، الفعلي 03/04/05" قابل للتنفيذ.

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

سيناريو واقعي وخطوات لاحقة

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

تخيل ملفًا اسمه orders.csv بالأعمدة: order_id,customer_email,order_date,currency,total_amount.

هنا ثلاثة صفوف سيئة واقعية (كما سيرها المستخدم):

order_id,customer_email,order_date,currency,total_amount
A-1001,[email protected],2026-01-05,USD,129.99
A-1002,not-an-email,01/06/2026,USD,49.00
,[email protected],2026-01-07,US, -10

الصف 2 يحتوي على بريد إلكتروني غير صالح وتاريخ غامض الصيغة. الصف 3 مفقود order_id، يحتوي رمز عملة غير مدعوم (US بدلًا من USD)، ومبلغ سلبي.

إذا أعادت API أخطاء، اجعل الشكل ثابتًا ومحددًا. مثال استجابة تدعم النجاح الجزئي:

{
  "correlation_id": "imp_20260109_7f3a9d",
  "import_id": "ord_01HZZ...",
  "status": "partial_success",
  "summary": {
    "total_rows": 3,
    "imported_rows": 1,
    "failed_rows": 2
  },
  "errors": [
    {
      "row_number": 2,
      "field": "customer_email",
      "code": "invalid_email",
      "message": "Email must contain a valid domain.",
      "value": "not-an-email"
    },
    {
      "row_number": 2,
      "field": "order_date",
      "code": "invalid_date_format",
      "message": "Use ISO-8601 (YYYY-MM-DD).",
      "value": "01/06/2026"
    },
    {
      "row_number": 3,
      "field": "order_id",
      "code": "required",
      "message": "order_id is required.",
      "value": ""
    },
    {
      "row_number": 3,
      "field": "currency",
      "code": "unsupported_currency",
      "message": "Allowed values: USD, EUR, GBP.",
      "value": "US"
    },
    {
      "row_number": 3,
      "field": "total_amount",
      "code": "must_be_positive",
      "message": "total_amount must be greater than 0.",
      "value": " -10"
    }
  ],
  "retry": {
    "mode": "upload_failed_only",
    "failed_row_numbers": [2, 3]
  }
}

النجاح الجزئي مهم لأن المستخدمين لا ينبغي أن يعيدوا رفع الملف كله. تدفق إعادة محاولة بسيط: أصلح الصفوف الفاشلة فقط، صدّر CSV صغير يحتوي الصفوف 2 و3، وأعد الرفع. يجب أن يعامل المستورد هذه الحالة كـ idempotent عندما يكون order_id موجودًا، لذا فإن "إعادة المحاولة" تقوم بتحديث نفس السجلات بدلًا من إنشاء نسخ.

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

خطوات لاحقة تجعل هذا قابلاً للتكرار:

• استخدم Claude Code لتوليد قواعد التحقق، صفوف خاطئة نموذجية، والرموز/الرسائل التي تريد توحيدها.
• حوّل هذه الأمثلة إلى اختبارات آلية (بما في ذلك اختبارات الفز) بحيث تصبح الحواف الجديدة اختبارات فاشلة لا تذاكر جديدة.
• إذا بنيت مع Koder.ai، استخدم وضع التخطيط لصياغة عقد الاستيراد، توليد المحقق والاختبارات، ثم كرر حتى يبقى شكل الخطأ ثابتًا عبر CSV و JSON.