Claude Code ব্যবহার করে ডেটা ইম্পোর্ট/এক্সপোর্ট সঠিকতা বাড়ান: ভ্যালিডেশন রুল, ধারাবাহিক এরর ফরম্যাট, এবং CSV/JSON ইম্পোর্টের জন্য ফাজ টেস্টিং সেট করে এজ-কেস সাপোর্ট টিকিট কমান।
ইম্পোর্টগুলো বেশিরভাগই “কোড ভুল” হওয়ার কারণে ব্যর্থ হয় না। সেগুলো ব্যর্থ হয় কারণ বাস্তব-জগতের ডেটা বিশৃঙ্খল, অনিয়মিত, এবং এমনভাবে তৈরি হয়েছে যা আপনার অনুমানগুলো দেখেনি।
CSV সমস্যাগুলো সাধারণত শেইপ এবং ফরম্যাটিং নিয়ে। JSON সমস্যাগুলো সাধারণত অর্থ ও টাইপ নিয়ে। দুইটোই এমনভাবে ভেঙে পড়তে পারে যা ছোট মনে হলেও বিভ্রান্তিকর ফলাফল তৈরি করে।
এই সমস্যাগুলো সাপোর্ট টিকিটে বারবার দেখা যায়:
সঠিকতা কেবল "ইম্পোর্ট হয়েছে কি না" নয়। আপনাকে সিদ্ধান্ত নিতে হবে কোন আউটকামগুলো মঞ্জুরযোগ্য, কারণ ব্যবহারকারীরা চুপচাপ ভুলগুলোকে বেশ্যিকল্পে প্রথমেই নোট করে, স্পষ্ট ব্যর্থতার চেয়ে বেশি।
বেশিরভাগ টিম তিন ধরনের আউটকামে একমত হতে পারে:
এজ-কেসগুলো পুনরায় কাজের কারণ হয় যখন মানুষেরা দ্রুত বুঝতে পারেন না কীভাবে সমস্যা সমাধান করবেন। একটি সাধারণ দৃশ্য: কাস্টমার 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, বা ফিল্ডের একটি সম্মিলিত কম্বিনেশন), কোথায় তা শনাক্ত করবেন (ফাইলের মধ্যে, বিদ্যমান ডাটার বিরুদ্ধে, বা উভয়), এবং আপনি কী করবেন (প্রথমটি রাখুন, শেষটি রাখুন, মার্জ করুন, না রিজেক্ট করুন)।
একটি কন্ট্রাক্ট চেকলিস্ট যা স্পেসে পেস্ট করা যায়:
উদাহরণ: "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-এর আগে আপনি কী নর্মালাইজ করবেন এবং তা ডকুমেন্ট করুন। সাধারণ উদাহরণ: স্পেস ট্রিম করা, ইউনিকোড নর্মালাইজেশন (দৃশ্যত সমান অক্ষরগুলো একইভাবে তুলনা করার জন্য), এবং ফোন নম্বরগুলোকে একটি নির্দিষ্ট স্টোরেজ ফরম্যাটে ফরম্যাট করা।
একটি পড়তে সুবিধাজনক কাঠামো:
আপনার রুলগুলো 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 চায় “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 রেসপন্স দুটি প্রশ্নের উত্তর দেয়া উচিত: কী হলো, এবং ব্যবহারকারী পরবর্তী কী করবে।
এরর থাকলেও ধারাবাহিক সামারি রিটার্ন করুন যাতে UI ও সাপোর্ট টুলিং প্রতিটি ইম্পোর্ট একইভাবে হ্যান্ডল করতে পারে।
শামিল করুন:
created, updated, skipped, failed কাউন্টtotalRows (অথবা JSON-এর জন্য totalRecords)mode (উদাহরণ: "createOnly", "upsert", বা "updateOnly")startedAt ও finishedAt টাইমস্ট্যাম্পcorrelationId যাতে সাপোর্ট অনুরোধ করতে পারেcorrelationId অনেক মূল্যবান — কেউ বললে "ইম্পোর্ট হয়নি", আপনি সঠিক রান ও এরর রিপোর্ট দ্রুত খুঁজে পাবেন।
10,000 সারির এরর রেসপন্সে ঢেলে দেবেন না। একটি ছোট স্যাম্পল (উদাহরণ: 20) দিন যা প্যাটার্ন দেখায়, এবং পুরো রিপোর্ট আলাদা একটি এন্ডপয়েন্ট থেকে আনবার ব্যবস্থা রাখুন।
প্রতিটি এরর স্পেসিফিক ও স্থিতিশীল রাখুন:
উদাহরণ রেসপন্স (কিছু সারি ব্যর্থ হলেও সফল):
{
"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 সম্পর্কে স্পষ্ট হন: একটি idempotencyKey গ্রহণ করুন (অথবা ফাইল হ্যাশ গণনা করুন), এবং অনুরোধটি পুনরাবৃত্ত হলে বিদ্যমান importId রিটার্ন করুন। আপনার মোড যদি upsert হয়, মিলন নিয়ম নির্ধারণ করুন (উদাহরণ: email অনন্য কী)। create-only হলে ডুপ্লিকেটগুলিকে "skipped" রিটার্ন করুন, "created again" নয়।
যদি পুরো রিকোয়েস্টই অনুপযুক্ত (খারাপ অথ, ভুল কনটেন্ট-টাইপ, অনুপাঠ্য ফাইল), দ্রুত ব্যর্থ করুন এবং status: "rejected" রিটার্ন করুন একটি সংক্ষিপ্ত এরর লিস্ট সহ। যদি ফাইল বৈধ কিন্তু সারি-স্তরের সমস্যা থাকে, এটি একটি সম্পন্ন কাজ হিসাবে বিবেচনা করুন failed > 0 দিয়ে যাতে ব্যবহারকারী ফাইল ঠিক করে পুনরায় আপলোড করতে পারে summary হারায় না।
ভালো অভ্যাস: মডেলকে কন্ট্রাক্টটি স্ট্রাকচার্ড ফরম্যাটে লিখতে বলুন, প্রোজেক্টিভ প্রোজেক্ট হিসেবে নয়। "সহায়ক অনুচ্ছেদ" প্রায়ই ট্রিমিং নিয়ম, ডিফল্ট ভ্যালু, এবং খালি সেল মানছে কি না—এর মতো ডিটেইল বাদ দেয়।
একটি প্রম্পট ব্যবহার করুন যা একটি টেবিল আউটপুট করতে বাধ্য করে যাতে মানব রিভিউ করতে পারে এবং ডেভেলপার কোডে রূপান্তর করতে পারে। প্রতিটি ফিল্ড-মেয়ের জন্য পাস ও ফেল উদাহরণ এবং অস্পষ্ট কোনো বিষয়ের নোট চাওয়া উচিত (উদাহরণ: খালি স্ট্রিং 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, এবং নর্মালাইজেশন সংঘাত করতে পারে তা দেখাতে বলুন। সেই রিভিউ ধাপ অনেক টিকিট-যোগ্য আচরণ ধরবে।
ফাজ টেস্টিং "অদ্ভুত ফাইলগুলো" সাপোর্ট টিকিটে পরিণত হওয়া থেকে রোধ করে। একটি ছোট সেট সত্যিকারের ভাল ফাইল দিয়ে শুরু করুন, তারপর হাজার হাজার সামান্য ভাঙা ভ্যারিয়েন্ট জেনারেট করে নিশ্চিত করুন আপনার ইম্পোর্টার সেফলি ও স্পষ্টভাবে প্রতিক্রিয়া করে।
সামান্য ভিন্ন ধরণের সিড কোরপাস রাখুন: সবচেয়ে ছোট বৈধ ফাইল, একটি টিপিক্যাল ফাইল, এবং একটি বড় ফাইল। JSON-এর ক্ষেত্রে, একটি অবজেক্ট, বহু অবজেক্ট, এবং নেস্টেড স্ট্রাকচার অন্তর্ভুক্ত করুন যদি আপনি সেগুলো সাপোর্ট করেন।
এরপর একটি অটোমেটেড মিউটেটর যোগ করুন যা এক সময়ে একটি জিনিস পরিবর্তন করে। র্যান্ডম সিড লগ করে মিউটেশনের পুনরাবৃত্তি নিশ্চিত করুন যাতে আপনি ব্যর্থতা রেপ্লে করতে পারেন।
ফাজ ডাইমেনশন যা বাস্তব-জগতের বেশিরভাগ সমস্যা ধরবে:
সিনট্যাক্সে থেমে যাবেন না — সেমান্টিক ফাজও যোগ করুন: অনুরূপ ফিল্ডগুলোর আদল বদলান (email বনাম username), চরম তারিখ, ডুপ্লিকেট আইডি, নেগেটিভ পরিমাণ, বা enum ভ্যালু লঙ্ঘন করুন।
ফাজ টেস্টগুলো তখনই কাজ করে যখন পাসের শর্ত কঠোর। আপনার ইম্পোর্টার কখনো ক্র্যাশ বা হ্যাং করবে না, এবং এররগুলো ধারাবাহিক ও কার্যকর হবে।
প্রায়োগিক পাস নিয়মের সেট:
CI-তে প্রতিটি পরিবর্তনের উপর এই টেস্ট চালান। যখন কোনো ব্যর্থতা পেলে, সঠিক ফাইলটি ফিক্সচারে সংরক্ষণ করুন এবং একটি রিগ্রেশন টেস্ট যোগ করুন যাতে এটি আর ফিরে না আসে।
আপনি Claude Code ব্যবহার করলে, এটি আপনার কন্ট্রাক্ট অনুযায়ী সিড ফিক্সচার, মিউটেশন প্ল্যান এবং প্রত্যাশিত এরর আউটপুট জেনারেট করতে পারবে—আপনি এখনও নিয়ম নির্ধারণ করবেন, কিন্তু ফেইস কভারেজ দ্রুত বাড়বে, বিশেষত CSV কোটিং এবং JSON কর্নার কেসগুলোর জন্য।
বেশিরভাগ ইম্পোর্ট টিকিট আসে অনিশ্চিত নিয়ম ও অপ্রচলিত ফিডব্যাক থেকে।
একটি সাধারণ ট্র্যাপ হলো “বেস্ট-এফোর্ট” পার্সিং যা লিখে রাখা হয় না। যদি আপনার ইম্পোর্টার নিঃশব্দে স্পেস ট্রিম করে, কমা ও সেমিকোলন দুটোই গ্রহণ করে, বা তারিখ ফরম্যাট অনুমান করে, ব্যবহারকারীরা এই অনুমানগুলোর ওপরওয়ার্কফ্লো তৈরি করে। তারপর সামান্য পরিবর্তন বা ভিন্ন ফাইল জেনারেটর সব বিনষ্ট করে দেয়। আচরণ বেছে নিন, ডকুমেন্ট করুন, এবং টেস্ট করুন।
আর এক বার্তার-প্রেরক সমস্যা হলো generic এরর মেসেজ। "Invalid CSV" বা "Bad request" ব্যবহারকারীকে অনুমান করতে বাধ্য করে। তারা একই ফাইল পাঁচবার আপলোড করে, এবং সাপোর্ট শেষে ফাইল চাইবে। এররগুলো একটি সারি, একটি ফিল্ড, একটি স্পষ্ট কারণ এবং একটি স্থিতিশীল কোড নির্দেশ করা উচিত।
এক খারাপ নীতি হলো সবাই-অথবা-আছে ইম্পোর্ট যেখানে একটি খারাপ সারি পুরো ফাইল ব্যর্থ করে দেয়। কখনো কখনো সেটা প্রয়োজনীয় (উদাহরণ: ফাইন্যান্সিয়াল ইম্পোর্ট যেখানে আংশিক ডেটা বিপজ্জনক), কিন্তু অনেক ব্যবসায়িক ইম্পোর্ট চালিয়ে যেতে পারে এবং একটি সামারি রিপোর্ট করতে পারে, যতক্ষণ আপনি স্পষ্ট অপশন দেন যেমন strict mode বনাম partial import।
টেক্সট এনকোডিং ইস্যুগুলোও জেদি টিকিট তৈরি করে। UTF-8 সঠিক ডিফল্ট, কিন্তু বাস্তব CSV-গুলোতে BOM, কর্লি কোট, বা স্প্রেডশীট থেকে কপি করা non-breaking স্পেস থাকে। এগুলো কনসিস্টেন্টভাবে হ্যান্ডল করুন এবং যে detected এনকোডিংটা দেখেছেন তা রিপোর্ট করুন যাতে ব্যবহারকারী তাদের এক্সপোর্ট সেটিংস ঠিক করতে পারে।
শেষে, রিলিজগুলোর মধ্যে এরর কোড বদলে ফেলা ক্লায়েন্ট ও অটোমেশন ভেঙে দেয়। শব্দ প্রকাশ ভালো করলে মেসেজ বদলান, কিন্তু কোড ও মানে স্থিতিশীল রাখুন। সত্যিই প্রয়োজন হলে ভার্সন করুন।
রক্ষার যোগ্য ট্র্যাপগুলো:
উদাহরণ: একজন কাস্টমার Excel থেকে CSV এক্সপোর্ট করে, যা BOM যোগ করে এবং তারিখগুলো 03/04/2026 ফরম্যাটে ফরম্যাট করে। আপনার ইম্পোর্টার MM/DD অনুমান করে, কিন্তু কাস্টমার DD/MM আশা করেছিল। যদি আপনার এরর রিপোর্ট ডিটেক্ট করা ফরম্যাট, স্পষ্ট ফিল্ড, এবং প্রস্তাবিত সমাধান দেখায়, ব্যবহারকারী ফাইল ঠিক করে দ্রুত পুনরায় আপলোড করতে পারবেন।
বেশিরভাগ ইম্পোর্ট সমস্যাই ব্যবহারকারীর ফাইলের ব্যাখ্যা ও আপনার সিস্টেমের স্বীকৃতির মধ্যে সামান্য মিসম্যাচ। এটিকে একটি রিলিজ গেট হিসেবে বিবেচনা করুন।
একটি ব্যবহারিক টেস্ট: একটি ইচ্ছাকৃতভাবে বিশৃঙ্খল ফাইল নিন। উদাহরণ: হেডার দুইবার আছে (দুইটি "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 দ্রুত নির্ণয়ের পথ। একটি সাপোর্ট এজেন্ট সেই এক ভ্যালু চাইলে, লগে নির্দিষ্ট ইম্পোর্ট রান খুঁজে পাবে এবং নিশ্চিত করবে পার্সার অতিরিক্ত কলাম, ভুল ডিলিমিটার, বা অপ্রত্যাশিত এনকোডিং দেখেছে কি না।
পরবর্তী ধাপ যা এটি পুনরাবৃত্তিযোগ্য করে তোলে:
বেশিরভাগ ব্যর্থতা “খারাপ কোড” থেকে আসে না, বরং বাস্তব-জগতের বিশৃঙ্খলা থেকে আসে। CSV সমস্যা সাধারণত গঠনের (হেডার, ডিলিমিটার, কোটিং, এনকোডিং) সঙ্গে সম্পর্কিত, আর JSON সমস্যা সাধারণত অর্থ (টাইপ, null বনাম খালি, অনাকাঙ্ক্ষিত নেস্টিং) নিয়ে। উভয় ক্ষেত্রেই ইনপুটকে অবিশ্বাস্য মনে করে একটি স্পষ্ট চুক্তি অনুসারে ভ্যালিডেট করুন।
আগে থেকেই তিনটি আউটকাম নির্ধারণ করুন:\n\n- Accepted: সবকিছু ইম্পোর্ট হয়েছে।\n- Rejected: ফাইল বিশ্বাসযোগ্য নয় বলে কিছুই ইম্পোর্ট করা হল না (ভুল হেডার, পাঠ্য না-উঠে এমন JSON, খারাপ এনকোডিং)।\n- Partially accepted: বৈধ রেকর্ডগুলো ইম্পোর্ট হবে; অবৈধগুলো স্পষ্ট কারণে বাদ হবে।\n\nএকটি ডিফল্ট নীতি বেছে নিন (অনেক প্রোডাক্ট partial বেছে নেয়) এবং UI ও API জুড়ে এটিকে সঙ্গত রাখুন।
একটি ইম্পোর্ট কন্ট্রাক্ট লেখা উচিত ইম্পোর্ট করার আগে:\n\n- গৃহীত ফরম্যাট (CSV ডিলিমিটার, হেডার বাধ্যতামূলক কি না, UTF-8/BOM হ্যান্ডলিং; JSON অ্যারে বনাম অবজেক্ট বনাম JSON Lines)\n- ফিল্ড নিয়ম (required/optional/defaults)\n- নর্মালাইজেশন (ট্রিম, কেস নিয়ম, তারিখ ফরম্যাট)\n- ডুপ্লিকেট নির্ধারণ ও হ্যান্ডলিং\n- ভ্যালিডেশন কোথায় হয় (ক্লায়েন্ট, সার্ভার, বা উভয়)\n\nএটি আচরণ পরিবর্তনের ফলে "গতকাল কাজ করেছিল" ধরণের সারপ্রাইজ রোধ করে।
প্রতি ফিল্ডে একটি অস্পষ্টতা থেকে রক্ষার জন্য এক ফরম্যাট নির্বাচন করুন (উদাহরণ: তারিখগুলোর জন্য YYYY-MM-DD)। যদি আপনি ভ্যারিয়েন্ট গ্রহণ করেন, তাহলে সেটা নির্দিষ্ট ও পূর্বাভাসযোগ্য করুন (উদাহরণ: true/false/1/0 গ্রহণ করা হলেও প্রতিটি স্প্রেডশীট অনুমান গ্রহণ করবেন না)। দ্ব্যর্থকারী তারিখ যেমন 01/02/03 অনুমান করবেন না; ISO ফরম্যাট দাবি করুন বা স্পষ্ট ত্রুটি দেখান।
নির্ধারণ করুন:\n\n- কীকে ডুপ্লিকেট গোনা হবে (email, external_id, বা একটি কম্পোজিট)\n- কোথায় ডিটেকশন হবে (ফাইলের মধ্যে, বিদ্যমান ডাটার বিরুদ্ধে, বা উভয়)\n- কী কার্য করণ (first রাখুন, last রাখুন, merge করুন, বা reject করুন)\n\nরিলায়বেল রিট্রাই সাপোর্ট করার জন্য idempotency-র সঙ্গে এটিকে মিলিয়ে নিন যাতে একই আপলোড ডুপ্লিকেট তৈরি না করে।
একটি স্তরভিত্তিক কাঠামো ব্যবহার করুন, একজায়গায় বড় validate() না লিখে:\n\n- Normalize ইনপুটকে canonical আকারে রূপান্তর করুন\n- Field-level rules (টাইপ, রেঞ্জ, enum)\n- Cross-field rules (start < end, totals মিলেছে কিনা)\n- File-level rules (আবশ্যক হেডার, duplicate keys, supported version)\n\nছোট, নামকৃত রুলগুলো টেস্ট করা সহজ ও পরিবর্তন-প্রতিরোধী।
স্থিতিশীল এরর অবজেক্ট শেপ রাখুন:\n\n- code (স্থিতিশীল আইডেন্টিফায়ার)\n- message (ইউআই-র জন্য মানুষের ভাষা)\n- path/field (কলামের নাম বা JSON পয়েন্টার)\n- / (CSV-এর জন্য)\n- ( বনাম )\n\nসম্ভব হলে প্রত্যাশিত ও প্রকৃত মান দেখান যাতে ব্যবহারকারীরা সময় বাঁচিয়ে সমস্যার সমাধান করতে পারে।
প্রতিবার একটি ধারাবাহিক সামারি রিটার্ন করুন, এমনকি এরর থাকলেও:\n\n- গণনা: created, , , এবং \n- (success, rejected, completed_with_errors)\n- টাইমস্ট্যাম্প (, )\n- একটি ডিবাগিং/সাপোর্টের জন্য\n\nবড় ফাইল হলে একটি ছোট দিন এবং পুরো রিপোর্ট আনতে একটি উপায় রাখুন।
রিট্রাই সমর্থন করুন:\n\n- একটি idempotencyKey গ্রহণ করুন (বা ফাইল হ্যাশ ব্যবহার করুন)\n- একই অনুরোধ পুনরাবৃত্ত হলে বিদ্যমান importId রিটার্ন করুন\n- upsert matching rule নির্ধারণ করুন (উদাহরণ: email হলো অনন্য কী)\n\nএটিই পুনরাবৃত্তি করার সময় ডুপ্লিকেট সৃষ্টি রোধ করে।
কিছু পরিচিত-ভিত্তিক সিড ফাইল নিয়ে শুরু করুন, তারপর ছোট মিউটেশনগুলো জেনারেট করুন (এক সময়ে এক পরিবর্তন):\n\n- এনকোডিং (UTF-8 BOM, অবৈধ বাইট)\n- স্ট্রাকচার (হেডার অনুপস্থিত, এক্সট্রা কলাম, ভুল ডিলিমিটার)\n- কোটিং/নিউলাইন (অনাবৃত কোট, এমবেডেড নিউলাইন)\n- টাইপ এজ (বড় সংখ্যা, খালি বনাম null, JSON-এ NaN/Infinity)\n- সাইজ লিমিট (অনেক বড় ফিল্ড, গভীর নেস্টিং)\n\nএকটি ফাজ টেস্ট পাস বলে যদি ইম্পোর্টার ক্র্যাশ না করে, নির্দিষ্ট, কার্যকর এরর দেয়, এবং র্যান্ডম ফলাফল না দেখায়।
rowlineseverityerrorwarningupdatedskippedfailedtotalRows/totalRecordsstatusstartedAtfinishedAtcorrelationIderrorsSample