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: বৈধ রেকর্ডগুলো ইম্পোর্ট হয়েছে, অবৈধগুলো স্পষ্ট কারণ প্রদর্শন করে বাদ দেয়া হয়েছে

এজ-কেসগুলো পুনরায় কাজের কারণ হয় যখন মানুষেরা দ্রুত বুঝতে পারেন না কীভাবে সমস্যা সমাধান করবেন। একটি সাধারণ দৃশ্য: কাস্টমার 5,000 সারির একটি CSV আপলোড করে, ইম্পোর্টার বলে "Invalid format", এবং তারা র্যান্ডম পরিবর্তন করে তিনবার রিট্রাই করে। এর ফলে একাধিক টিকিট এবং আপনার দিক থেকে কারও লোককে লোকালভাবে ফাইল পুনরায় তৈরি করে সমস্যা পুনরুত্থাপন করতে হয়।

চক্রটি কমাতে লক্ষ্য নির্ধারণ করুন: কম রিট্রাই, দ্রুত সমাধান, পূর্বানুমেয় ফলাফল। নিয়ম লেখার আগে সিদ্ধান্ত নিন "partial" মানে কী (এবং আপনি এটা অনুমোদন করেন কি না), সারি-স্তরের সমস্যাগুলো কীভাবে রিপোর্ট করবেন, এবং ব্যবহারকারী পরবর্তী কী করবে (ফাইল সম্পাদনা করবে, ফিল্ড ম্যাপ করবে, বা সংশোধিত একটি সংস্করণ এক্সপোর্ট করবে)। আপনি যদি Koder.ai-এর মতো প্ল্যাটফর্ম ব্যবহার করে দ্রুত ভ্যালিডেটর ও টেস্ট জেনারেট করেন, তবুও ইম্পোর্ট কন্ট্রাক্ট হচ্ছে যা সময়ের সাথে প্রোডাক্ট পরিবর্তনের পরও আচরণ ধারাবাহিক রাখে।

নিয়ম লেখার আগে ইম্পোর্ট চুক্তি নির্ধারণ করুন

একটা ভ্যালিডেশন রুল লেখার আগে সিদ্ধান্ত নিন আপনার প্রোডাক্টে "ভ্যালিড ইনপুট" মানে কী। বেশিরভাগ ইম্পোর্ট বাগই হলো ব্যবহারকারী যে ফাইল আপলোড করেছে এবং আপনার সিস্টেম যে নিঃশব্দভাবে অনুমান করেছে—এর মধ্যে প্রত্যাশার মিল না থাকা।

ফরম্যাট দিয়ে শুরু করুন, এবং স্পষ্ট হন। “CSV” বলতে কমা বা সেমিকোলন, হেডার আছে কি না, UTF-8 নাকি Excel-যে-ফরম্যাট-নির্গত—এসব হতে পারে। JSON-এর জন্য সিদ্ধান্ত নিন আপনি একটি একক অবজেক্ট গ্রহণ করবেন, রেকর্ডের অ্যারে নেবেন, না JSON Lines (লাইন প্রতি একটি JSON অবজেক্ট) টেক্সট গ্রহণ করবেন। যদি আপনি নেস্টেড JSON গ্রহণ করেন, নির্দিষ্ট করুন কোন পাথগুলো পড়বেন এবং কোনগুলো উপেক্ষা করবেন।

তারপর ফিল্ড কন্ট্রাক্ট লক করুন। প্রতিটি ফিল্ডের জন্য সিদ্ধান্ত নিন এটি কি required, optional, না default সহ optional। ডিফল্টগুলো কন্ট্রাক্টের অংশ — ইমপ্লিমেন্টেশন ডিটেইল নয়। যদি country অনুপস্থিত থাকে, খালি ডিফল্ট করবেন, একটি নির্দিষ্ট দেশ বেছে নেবেন, না সারি রিজেক্ট করবেন?

পার্সিং আচরণই সেই জায়গা যেখানে “সহনশীল” ইম্পোর্ট দীর্ঘমেয়াদী সমস্যা তৈরি করে। শুরুতে সিদ্ধান্ত নিন আপনি কতটা কড়া হবেন — স্পেস ট্রিম করা হবে কি না, কেস নর্মালাইজ করা হবে কি না, ও "yes"/"true"/"1" ধরনের ভ্যারিয়েন্ট গ্রহণ করা হবে কি না। সহনশীলতা ঠিক আছে যদি তা পূর্বানুমেয় এবং ডকুমেন্টেড থাকে।

ডুপ্লিকেটও আরেকটি কন্ট্রাক্ট সিদ্ধান্ত যা সঠিকতা ও বিশ্বাসকে প্রভাবিত করে। নির্ধারণ করুন কীকে ডুপ্লিকেট বলা হবে (একই ইমেইল, একই external_id, বা ফিল্ডের একটি সম্মিলিত কম্বিনেশন), কোথায় তা শনাক্ত করবেন (ফাইলের মধ্যে, বিদ্যমান ডাটার বিরুদ্ধে, বা উভয়), এবং আপনি কী করবেন (প্রথমটি রাখুন, শেষটি রাখুন, মার্জ করুন, না রিজেক্ট করুন)।

একটি কন্ট্রাক্ট চেকলিস্ট যা স্পেসে পেস্ট করা যায়:

• গৃহীত ফরম্যাট ও এনকোডিং (CSV ডিলিমিটার, JSON বনাম JSON Lines, নেস্টেড সমর্থন)
• ফিল্ড নিয়ম (required/optional/defaults, অনুমোদিত মান)
• নর্মালাইজেশন নিয়ম (ট্রিম, কেস, তারিখ/নাম্বার ফরম্যাট)
• ডুপ্লিকেট সংজ্ঞা ও হ্যান্ডলিং (ডিটেকশন স্কোপ, নির্ধারিত আচরণ)
• ভ্যালিডেশন অবস্থান (ক্লায়েন্ট, সার্ভার, বা উভয়)

উদাহরণ: "customers" ইম্পোর্ট। যদি ইমেইল অনন্য কী হয়, সিদ্ধান্ত নিন " [email protected] " কি "[email protected]"-এর সমান, external_id থাকলে missing email কি গ্রহণযোগ্য, এবং ফাইলের ভিতরের ডুপ্লিকেট কি রিজেক্ট করা হবে এমনকি যদি ডাটাবেসে মিলে না যায়। একবার এই চুক্তি স্থির হলে, UI ও API-তে ধারাবাহিক আচরণ করা অনেক সহজ হয়, Koder.ai-এ ইমপ্লিমেন্ট করুন বা অন্যত্র।

পাঠযোগ্য ও টেস্টযোগ্য ভ্যালিডেশন রুলস

বড়তর ইম্পোর্ট সমস্যা প্রায়ই একটি বড় validate() ফাংশন দিয়ে শুরু হয়। একটি পরিষ্কার পদ্ধতি হলো স্তরভিত্তিক রুলস ছোট ছোট ফাংশন দিয়ে, প্রত্যেকটির স্পষ্ট নাম থাকায় পরিবর্তন রিভিউ করা ও টেস্ট লেখা সহজ হয়।

ফিল্ড-লেভেল রুল দিয়ে শুরু করুন: একটি একক মান নিজে পাস বা ফেল করতে পারে (টাইপ, রেঞ্জ, দৈর্ঘ্য, অনুমোদিত মান, regex)। এগুলোকে সাধারণ ও পূর্বানুমেয় রাখুন। উদাহরণ: email একটি বেসিক প্যাটার্ন মেলে কি না, age 0 থেকে 120 এর মধ্যে পূর্ণসংখ্যা কি না, status একটি আলাউড ভ্যালু active|paused|deleted-এর মধ্যে আছে কি না।

মাত্র সেই জায়গায় ক্রস-ফিল্ড রুল যোগ করুন যেখানে তা জরুরি। এই চেকগুলো একাধিক ফিল্ডের উপর নির্ভর করে এবং বাগ এখানেই লুকায়। ক্লাসিক উদাহরণ: startDate অবশ্যই endDate-এর আগে থাকতে হবে, অথবা total = subtotal + tax - discount হওয়া উচিত। এই রুলগুলো এমনভাবে লিখুন যাতে সুনির্দিষ্ট ফিল্ডগুলোকে ইঙ্গিত করতে পারে, শুধু "record invalid" না।

রেকর্ড-লেভেল রুল আলাদা করা উচিত ফাইল-লেভেল রুল থেকে। রেকর্ড-লেভেল রুল একটি সারি (CSV) বা একটি অবজেক্ট (JSON) পরীক্ষা করে। ফাইল-লেভেল রুল পুরো আপলোড চেক করে: প্রয়োজনীয় হেডার আছে কি, একটি ইউনিক কী সারির মধ্যে পুনরাবৃত্ত হচ্ছে কি না, কলাম কাউন্ট প্রত্যাশার সাথে মিলে কি না, অথবা ফাইল কোন সমর্থিত ভার্সন ঘোষণা করেছে কি না।

নর্মালাইজেশনকে সাদামাটা রাখুন — জাদু বানানো হবে না। সিদ্ধান্ত নিন validation-এর আগে আপনি কী নর্মালাইজ করবেন এবং তা ডকুমেন্ট করুন। সাধারণ উদাহরণ: স্পেস ট্রিম করা, ইউনিকোড নর্মালাইজেশন (দৃশ্যত সমান অক্ষরগুলো একইভাবে তুলনা করার জন্য), এবং ফোন নম্বরগুলোকে একটি নির্দিষ্ট স্টোরেজ ফরম্যাটে ফরম্যাট করা।

একটি পড়তে সুবিধাজনক কাঠামো:

• Normalize: কাঁচা ইনপুটকে canonical আকারে রূপান্তর করুন।
• Validate fields: প্রতিটি ফিল্ডের জন্য ছোট, পুনব্যবহারযোগ্য চেক।
• Validate relationships: স্পষ্ট টার্গেট সহ ক্রস-ফিল্ড চেক।
• Validate file rules: হেডার, ডুপ্লিকেট, এবং ভার্সন সমর্থন।
• Test each layer: প্রতিটি রুলের ইউনিট টেস্ট এবং কয়েকটি end-to-end ফিক্সচার।

আপনার রুলগুলো version করুন। একটি schemaVersion (বা import “profile”) ফাইল বা API রিকোয়েস্টে রাখুন। যখন আপনি "ভ্যালিড"-এর সংজ্ঞা পরিবর্তন করবেন, তখনও আপনি পুরনো এক্সপোর্টগুলো পুরোনো ভার্সন ব্যবহার করে পুনঃইম্পোর্ট করতে পারবেন। এই এক চয়েস অনেক "গতকাল কাজ করেছিল" টিকিট রোধ করে।

মানুষেরা কাজ করতে পারার যোগ্য একটি এরর রিপোর্টিং ফরম্যাট ডিজাইন করুন

একটি ভাল ইম্পোর্টার সহায়কভাবে ব্যর্থ হয়। অস্পষ্ট এররগুলো র‍্যান্ডম রিট্রাই ও অনাবশ্যক সাপোর্ট কাজ বাড়ায়। একটি স্পষ্ট এরর ফরম্যাট ব্যবহারকারীদের দ্রুত ফাইল ঠিক করতে সাহায্য করে, এবং আপনাকে ভ্যালিডেশন উন্নত করতে দেয় ক্লায়েন্ট ব্রেক না করেই।

শুরু করুন একটি স্থিতিশীল এরর অবজেক্ট শেপ দিয়ে এবং CSV ও JSON জুড়ে এটিকে ধারাবাহিক রাখুন। Claude Code-কে একটি স্কিমা ও কয়েকটি বাস্তবসম্মত উদাহরণ প্রস্তাব করতে ব্যবহার করতে পারেন, এবং পরে এটাকে ইম্পোর্ট চুক্তির অংশ হিসেবে লক করে দিন।

একটি স্থিতিশীল এরর অবজেক্ট

প্রতিটি এররকে একটি ছোট রেকর্ড হিসেবে দেখুন যার ক্ষেত্রগুলো পরিবর্তন না করে। মেসেজ পরিবর্তনশীল হতে পারে, কিন্তু code এবং অবস্থান স্থির থাকা উচিত।

• code: সংক্ষিপ্ত, স্থিতিশীল আইডেন্টিফায়ার, যেমন REQUIRED_MISSING বা INVALID_DATE\n- message: UI-এর জন্য মানুষের ভাষায় বাক্য\n- path: সমস্যা কোথায় (JSON pointer যেমন /customer/email, বা কলামের নাম যেমন email)\n- row বা line: CSV-এর জন্য 1-ভিত্তিক সারি নম্বর (ঐচ্ছিকভাবে অরিজিনাল লাইনের সঙ্গে)\n- severity: অন্তত error ও warning

এররগুলো কার্যকর করা উচিত। আপনি কী আশা করেছিলেন ও কী দেখেছেন তা অন্তর্ভুক্ত করুন, এবং সম্ভব হলে একটি পাস উদাহরণ দেখান — উদাহরণ: প্রত্যাশিত YYYY-MM-DD, এসেছে 03/12/24।

UI ও ডিবাগিংয়ের জন্য গ্রুপিং

যদি আপনি একটি ফ্ল্যাট লিস্ট রিটার্ন করেন, তবুও পর্যাপ্ত ডেটা রাখুন যাতে UI সারি ও ফিল্ড ভেদে গ্রুপ করতে পারে। অনেক UI চায় “Row 12 has 3 issues” এবং তারপর প্রতিটি কলাম হাইলাইট করে। সাপোর্ট টিমগুলো প্যাটার্ন দেখে দ্রুত সিদ্ধান্ত নিতে পারে (উদাহরণ: প্রতিটি সারিতেই 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 কী রিটার্ন করা উচিত

"মিস্ট্রি ইম্পোর্ট" এড়াতে, আপনার API রেসপন্স দুটি প্রশ্নের উত্তর দেয়া উচিত: কী হলো, এবং ব্যবহারকারী পরবর্তী কী করবে।

প্রতিবার একটি স্পষ্ট ইম্পোর্ট সামারি রিটার্ন করুন

এরর থাকলেও ধারাবাহিক সামারি রিটার্ন করুন যাতে UI ও সাপোর্ট টুলিং প্রতিটি ইম্পোর্ট একইভাবে হ্যান্ডল করতে পারে।

শামিল করুন:

• created, updated, skipped, failed কাউন্ট
• totalRows (অথবা JSON-এর জন্য totalRecords)
• mode (উদাহরণ: "createOnly", "upsert", বা "updateOnly")
• startedAt ও finishedAt টাইমস্ট্যাম্প
• একটি correlationId যাতে সাপোর্ট অনুরোধ করতে পারে

correlationId অনেক মূল্যবান — কেউ বললে "ইম্পোর্ট হয়নি", আপনি সঠিক রান ও এরর রিপোর্ট দ্রুত খুঁজে পাবেন।

কার্যকর এররগুলো এবং ফুল রিপোর্ট আনবার উপায় দিন

10,000 সারির এরর রেসপন্সে ঢেলে দেবেন না। একটি ছোট স্যাম্পল (উদাহরণ: 20) দিন যা প্যাটার্ন দেখায়, এবং পুরো রিপোর্ট আলাদা একটি এন্ডপয়েন্ট থেকে আনবার ব্যবস্থা রাখুন।

প্রতিটি এরর স্পেসিফিক ও স্থিতিশীল রাখুন:

• অবস্থান: সারি নম্বর (CSV) বা JSON পাথ (JSON)\n- ফিল্ড নাম\n- এরর কোড (মেশিন-রিডেবল)\n- মেসেজ (মানব-পাঠযোগ্য)\n- প্রত্যাখ্যানকৃত মান (সুসংবেদনশীল ডেটা সাবধানে পরিচালনা করুন)

উদাহরণ রেসপন্স (কিছু সারি ব্যর্থ হলেও সফল):

{
  "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 হয়, মিলন নিয়ম নির্ধারণ করুন (উদাহরণ: email অনন্য কী)। create-only হলে ডুপ্লিকেটগুলিকে "skipped" রিটার্ন করুন, "created again" নয়।

ব্যর্থতায় সঠিক স্ট্যাটাস ব্যবহার করুন, কিন্তু শেপ স্থিতিশীল রাখুন

যদি পুরো রিকোয়েস্টই অনুপযুক্ত (খারাপ অথ, ভুল কনটেন্ট-টাইপ, অনুপাঠ্য ফাইল), দ্রুত ব্যর্থ করুন এবং status: "rejected" রিটার্ন করুন একটি সংক্ষিপ্ত এরর লিস্ট সহ। যদি ফাইল বৈধ কিন্তু সারি-স্তরের সমস্যা থাকে, এটি একটি সম্পন্ন কাজ হিসাবে বিবেচনা করুন failed > 0 দিয়ে যাতে ব্যবহারকারী ফাইল ঠিক করে পুনরায় আপলোড করতে পারে summary হারায় না।

Claude Code কিভাবে নিয়ম ও উদাহরণ জেনারেট করতে সাহায্য করে

ভালো অভ্যাস: মডেলকে কন্ট্রাক্টটি স্ট্রাকচার্ড ফরম্যাটে লিখতে বলুন, প্রোজেক্টিভ প্রোজেক্ট হিসেবে নয়। "সহায়ক অনুচ্ছেদ" প্রায়ই ট্রিমিং নিয়ম, ডিফল্ট ভ্যালু, এবং খালি সেল মানছে কি না—এর মতো ডিটেইল বাদ দেয়।

একটি প্রম্পট ব্যবহার করুন যা একটি টেবিল আউটপুট করতে বাধ্য করে যাতে মানব রিভিউ করতে পারে এবং ডেভেলপার কোডে রূপান্তর করতে পারে। প্রতিটি ফিল্ড-মেয়ের জন্য পাস ও ফেল উদাহরণ এবং অস্পষ্ট কোনো বিষয়ের নোট চাওয়া উচিত (উদাহরণ: খালি স্ট্রিং vs 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).

প্রথম খসড়ার পরে, এটিকে আরো কঠোর করুন: প্রতিটি রুলের জন্য পজিটিভ ও নেগেটিভ একটি করে উদাহরণ চাওয়া। এটি খালি স্ট্রিং, whitespace-only, কলাম অনুপস্থিতি, null বনাম "null", খুব বড় ইন্টিজার, সায়েন্টিফিক নোটেশন, ডুপ্লিকেট আইডি, এবং অতিরিক্ত JSON ফিল্ড — এইসব নাখোশ কনোরা কভার করার দিকে ঠেলবে।

কনক্রিট দৃশ্যের জন্য, "customers" CSV ইম্পোর্ট ভাবুন: email বাধ্যতামূলক, phone ঐচ্ছিক, এবং signup_date অনুপস্থিত হলে আজকের তারিখ ডিফল্ট। মডেল যদি আপনি একই সঙ্গে বলুন "signup_date required" সেটি বিরোধ উত্থাপন করবে। মডেলটিকে টেস্ট নাম যেমন import_customers_missing_email_returns_row_error প্রস্তাব করতে বলুন এবং রিটার্ন হওয়া এরর কোড ও মেসেজ শেপ নির্দিষ্ট করতে বলুন।

বাস্তবায়নের আগে এক ধাপ আর চালান: মডেলকে রুলগুলো চেকলিস্টের আকারে পুনরায় বলুন এবং কোথায় ডিফল্ট, required, এবং নর্মালাইজেশন সংঘাত করতে পারে তা দেখাতে বলুন। সেই রিভিউ ধাপ অনেক টিকিট-যোগ্য আচরণ ধরবে।

ধাপে ধাপে: CSV এবং JSON ইম্পোর্টের জন্য ফাজ টেস্ট

ফাজ টেস্টিং "অদ্ভুত ফাইলগুলো" সাপোর্ট টিকিটে পরিণত হওয়া থেকে রোধ করে। একটি ছোট সেট সত্যিকারের ভাল ফাইল দিয়ে শুরু করুন, তারপর হাজার হাজার সামান্য ভাঙা ভ্যারিয়েন্ট জেনারেট করে নিশ্চিত করুন আপনার ইম্পোর্টার সেফলি ও স্পষ্টভাবে প্রতিক্রিয়া করে।

সিড সেট তৈরি করুন, তারপর মিউটেট করুন

সামান্য ভিন্ন ধরণের সিড কোরপাস রাখুন: সবচেয়ে ছোট বৈধ ফাইল, একটি টিপিক্যাল ফাইল, এবং একটি বড় ফাইল। JSON-এর ক্ষেত্রে, একটি অবজেক্ট, বহু অবজেক্ট, এবং নেস্টেড স্ট্রাকচার অন্তর্ভুক্ত করুন যদি আপনি সেগুলো সাপোর্ট করেন।

এরপর একটি অটোমেটেড মিউটেটর যোগ করুন যা এক সময়ে একটি জিনিস পরিবর্তন করে। র‍্যান্ডম সিড লগ করে মিউটেশনের পুনরাবৃত্তি নিশ্চিত করুন যাতে আপনি ব্যর্থতা রেপ্লে করতে পারেন।

ফাজ ডাইমেনশন যা বাস্তব-জগতের বেশিরভাগ সমস্যা ধরবে:

• এনকোডিং ইস্যু: UTF-8 BOM, অবৈধ বাইট সিকোয়েন্স, মিক্সড নর্মালাইজেশন
• স্ট্রাকচার সমস্যা: হেডার অনুপস্থিত, অতিরিক্ত কলাম/ফিল্ড, ভুল ডিলিমিটার, ট্রেইলিং কমা
• কোটিং এবং নিউলাইন: অনাবৃত কোট, এমবেডেড নিউলাইন, CRLF বনাম LF, অসম কোটিং
• টাইপ এজ: বিশাল ইন্টিজার, NaN/Infinity (JSON), খালি স্ট্রিং বনাম null, whitespace প্যাডিং
• সাইজ ও লিমিট: অনেক বড় ফিল্ড, প্রচুর সারি, পুনরাবৃত্তি কী, গভীর নেস্টিং

সিনট্যাক্সে থেমে যাবেন না — সেমান্টিক ফাজও যোগ করুন: অনুরূপ ফিল্ডগুলোর আদল বদলান (email বনাম username), চরম তারিখ, ডুপ্লিকেট আইডি, নেগেটিভ পরিমাণ, বা enum ভ্যালু লঙ্ঘন করুন।

"পাস" কী মানে তা নির্ধারণ করুন এবং লক করে দিন

ফাজ টেস্টগুলো তখনই কাজ করে যখন পাসের শর্ত কঠোর। আপনার ইম্পোর্টার কখনো ক্র্যাশ বা হ্যাং করবে না, এবং এররগুলো ধারাবাহিক ও কার্যকর হবে।

প্রায়োগিক পাস নিয়মের সেট:

• ক্র্যাশ, টাইমআউট, বা মেমরি স্পাইক না ঘটবে আপনার সীমার বাইরে\n- সারি/ফিল্ড পয়েন্টারসহ পরিষ্কার এরর\n- একই ব্যর্থতার জন্য সব চালানোর সময় স্থিতিশীল এরর কোড\n- আংশিক লিখনন allowed না হলে কোন আংশিক লেখাও হবে না\n- স্টাইলগত পার্থক্য (যেমন whitespace) সাফল্যে ফলাফলকে প্রভাবিত করবে না

CI-তে প্রতিটি পরিবর্তনের উপর এই টেস্ট চালান। যখন কোনো ব্যর্থতা পেলে, সঠিক ফাইলটি ফিক্সচারে সংরক্ষণ করুন এবং একটি রিগ্রেশন টেস্ট যোগ করুন যাতে এটি আর ফিরে না আসে।

আপনি Claude Code ব্যবহার করলে, এটি আপনার কন্ট্রাক্ট অনুযায়ী সিড ফিক্সচার, মিউটেশন প্ল্যান এবং প্রত্যাশিত এরর আউটপুট জেনারেট করতে পারবে—আপনি এখনও নিয়ম নির্ধারণ করবেন, কিন্তু ফেইস কভারেজ দ্রুত বাড়বে, বিশেষত CSV কোটিং এবং JSON কর্নার কেসগুলোর জন্য।

প্রাথমিক ধরা পড়া ট্র্যাপগুলো যা বারবার সাপোর্ট টিকিট তৈরি করে

বেশিরভাগ ইম্পোর্ট টিকিট আসে অনিশ্চিত নিয়ম ও অপ্রচলিত ফিডব্যাক থেকে।

একটি সাধারণ ট্র্যাপ হলো “বেস্ট-এফোর্ট” পার্সিং যা লিখে রাখা হয় না। যদি আপনার ইম্পোর্টার নিঃশব্দে স্পেস ট্রিম করে, কমা ও সেমিকোলন দুটোই গ্রহণ করে, বা তারিখ ফরম্যাট অনুমান করে, ব্যবহারকারীরা এই অনুমানগুলোর ওপরওয়ার্কফ্লো তৈরি করে। তারপর সামান্য পরিবর্তন বা ভিন্ন ফাইল জেনারেটর সব বিনষ্ট করে দেয়। আচরণ বেছে নিন, ডকুমেন্ট করুন, এবং টেস্ট করুন।

আর এক বার্তার-প্রেরক সমস্যা হলো generic এরর মেসেজ। "Invalid CSV" বা "Bad request" ব্যবহারকারীকে অনুমান করতে বাধ্য করে। তারা একই ফাইল পাঁচবার আপলোড করে, এবং সাপোর্ট শেষে ফাইল চাইবে। এররগুলো একটি সারি, একটি ফিল্ড, একটি স্পষ্ট কারণ এবং একটি স্থিতিশীল কোড নির্দেশ করা উচিত।

এক খারাপ নীতি হলো সবাই-অথবা-আছে ইম্পোর্ট যেখানে একটি খারাপ সারি পুরো ফাইল ব্যর্থ করে দেয়। কখনো কখনো সেটা প্রয়োজনীয় (উদাহরণ: ফাইন্যান্সিয়াল ইম্পোর্ট যেখানে আংশিক ডেটা বিপজ্জনক), কিন্তু অনেক ব্যবসায়িক ইম্পোর্ট চালিয়ে যেতে পারে এবং একটি সামারি রিপোর্ট করতে পারে, যতক্ষণ আপনি স্পষ্ট অপশন দেন যেমন strict mode বনাম partial import।

টেক্সট এনকোডিং ইস্যুগুলোও জেদি টিকিট তৈরি করে। UTF-8 সঠিক ডিফল্ট, কিন্তু বাস্তব CSV-গুলোতে BOM, কর্লি কোট, বা স্প্রেডশীট থেকে কপি করা non-breaking স্পেস থাকে। এগুলো কনসিস্টেন্টভাবে হ্যান্ডল করুন এবং যে detected এনকোডিংটা দেখেছেন তা রিপোর্ট করুন যাতে ব্যবহারকারী তাদের এক্সপোর্ট সেটিংস ঠিক করতে পারে।

শেষে, রিলিজগুলোর মধ্যে এরর কোড বদলে ফেলা ক্লায়েন্ট ও অটোমেশন ভেঙে দেয়। শব্দ প্রকাশ ভালো করলে মেসেজ বদলান, কিন্তু কোড ও মানে স্থিতিশীল রাখুন। সত্যিই প্রয়োজন হলে ভার্সন করুন।

রক্ষার যোগ্য ট্র্যাপগুলো:

• সময়ের সাথে পরিবর্তিত undocumented “best effort” পার্সিং\n- সারি/ফিল্ড পয়েন্টার ও স্থিতিশীল এরর কোড ছাড়া এরর\n- strict বনাম partial অপশন ছাড়া সব-অথবা-কিছু নীতি\n- UTF-8, BOM, এবং অদৃশ্য অক্ষরগুলো অনিয়মিতভাবে না হ্যান্ডল করা\n- রিলিজে এরর কোড পরিবর্তন যা ক্লায়েন্ট সাইড হ্যান্ডলিং ভাঙে

উদাহরণ: একজন কাস্টমার Excel থেকে CSV এক্সপোর্ট করে, যা BOM যোগ করে এবং তারিখগুলো 03/04/2026 ফরম্যাটে ফরম্যাট করে। আপনার ইম্পোর্টার MM/DD অনুমান করে, কিন্তু কাস্টমার DD/MM আশা করেছিল। যদি আপনার এরর রিপোর্ট ডিটেক্ট করা ফরম্যাট, স্পষ্ট ফিল্ড, এবং প্রস্তাবিত সমাধান দেখায়, ব্যবহারকারী ফাইল ঠিক করে দ্রুত পুনরায় আপলোড করতে পারবেন।

ইম্পোর্টার শিপ করার আগে দ্রুত চেকলিস্ট

বেশিরভাগ ইম্পোর্ট সমস্যাই ব্যবহারকারীর ফাইলের ব্যাখ্যা ও আপনার সিস্টেমের স্বীকৃতির মধ্যে সামান্য মিসম্যাচ। এটিকে একটি রিলিজ গেট হিসেবে বিবেচনা করুন।

• হেডার এবং ফিল্ড নাম: প্রয়োজনীয় কলাম আছে কি না, নাম নিয়ম মেনে কিনা, এবং ডুপ্লিকেটগুলো রিজেক্ট করা হয়েছে কি না যাচাই করুন। অতিরিক্ত কলামগুলোর জন্য সিদ্ধান্ত নিন (ignore, warn, fail) এবং ধারাবাহিক রাখুন।
• ডেটা টাইপ ও ফরম্যাট: ইন্টিজার বনাম ডেসিমাল, বুলিয়ান (true/false, 0/1, yes/no), তারিখ ও টাইমস্ট্যাম্প (টাইমজোন নিয়ম) পার্সিং কীভাবে করবেন তা নির্ধারণ করুন। প্রতিটি ফিল্ডের জন্য একটি একটিমাত্র ফরম্যাট পছন্দ করুন।
• Null ও মিসিং ভ্যালু: প্রতিটি ফিল্ডের জন্য খালি স্ট্রিং কী বোঝায় তা নির্ধারণ করুন। মিসিং ফিল্ড, স্পষ্ট null, এবং খালি টেক্সট আলাদা করে বিবেচনা করুন।
• সাইজ ও সেফটি লিমিট: ফাইল সাইজ, সর্বোচ্চ সারি, এবং সর্বোচ্চ ফিল্ড দৈর্ঘ্যের লিমিট নির্ধারণ করুন। শুরুতেই স্পষ্টভাবে ব্যর্থ করুন এমনকি সারি প্রসেস করা শুরু করার আগে।
• ডিটারমিনিস্টিক এরর: একই খারাপ ইনপুট প্রতিবার একই এরর কোড এবং মেসেজ শেপ দেখাবে এটি নিশ্চিত করুন।

একটি ব্যবহারিক টেস্ট: একটি ইচ্ছাকৃতভাবে বিশৃঙ্খল ফাইল নিন। উদাহরণ: হেডার দুইবার আছে (দুইটি "email" কলাম), একটি বুলিয়ান ফিল্ডে "Y" ব্যবহার হয়েছে, এবং একটি তারিখ "03/04/05"। আপনার ইম্পোর্টার অনুমান করবে না। এটি অথবা ডকুমেন্টেড ম্যাপিং প্রয়োগ করা উচিত, অথবা একটি নির্দিষ্ট ত্রুটি দেখানো উচিত।

দুটি চেক টিম প্রায়ই বাদ দেয়:

প্রথমত, নিশ্চিত করুন আপনার ইম্পোর্টার পর্যাপ্ত লোকেশন ডিটেইল দেয় যাতে উৎস ফাইল ঠিক করা যায়। "Invalid date" কার্যকর নয়। "Row 42, column start_date: expected YYYY-MM-DD, got 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]
  }
}

আংশিক সাফল্য গুরুত্বপূর্ণ কারণ ব্যবহারকারীদের পুরো ফাইল আবার আপলোড করতে হবে না। একটি সহজ রিট্রাই ফ্লো: কেবল ব্যর্থ সারিগুলো ঠিক করুন, সারি 2 ও 3 রেখে একটি ছোট CSV এক্সপোর্ট করুন, এবং পুনরায় আপলোড করুন। যদি order_id উপস্থিত থাকে, আপনার ইম্পোর্টার এটিকে idempotent হিসেবে ট্রীট করা উচিত যাতে "রিট্রাই" একই রেকর্ডগুলো আপডেট করে, নতুন তৈরি না করে।

সাপোর্টের জন্য correlation_id দ্রুত নির্ণয়ের পথ। একটি সাপোর্ট এজেন্ট সেই এক ভ্যালু চাইলে, লগে নির্দিষ্ট ইম্পোর্ট রান খুঁজে পাবে এবং নিশ্চিত করবে পার্সার অতিরিক্ত কলাম, ভুল ডিলিমিটার, বা অপ্রত্যাশিত এনকোডিং দেখেছে কি না।

পরবর্তী ধাপ যা এটি পুনরাবৃত্তিযোগ্য করে তোলে:

• Claude Code ব্যবহার করে ভ্যালিডেশন রুল, খারাপ রো-এর উদাহরণ, এবং আপনি যে এরর কোড/মেসেজ স্ট্যান্ডার্ড করবেন তা জেনারেট করুন।\n- সেই উদাহরণগুলোকে অটোমেটেড টেস্টে পরিণত করুন (ফাজ টেস্টসহ) যাতে নতুন এজ-কেসগুলো নতুন টিকিট না হয়ে ফেইলিং টেস্ট হয়।\n- যদি আপনি Koder.ai-এ বিল্ড করেন, planning mode-এ ইম্পোর্ট চুক্তি খসড়া করুন, ভ্যালিডেটর এবং টেস্ট জেনারেট করুন, তারপর ততক্ষণ iterate করুন যতক্ষণ না CSV ও JSON জুড়ে এরর আউটপুট ধারাবাহিক থাকে।