ਡੇਟਾ ਆਯਾਤ/ਨਿਰਯਾਤ ਦੀ ਸਹੀਤਾ ਲਈ Claude Code: ਪ੍ਰਯੋਗਿਕ ਕਦਮ

CSV ਅਤੇ JSON ਆਯਾਤਾਂ ਨਾਲ ਕੀ ਗਲਤ ਹੁੰਦਾ ਹੈ

ਆਮ ਤੌਰ 'ਤੇ imports ਇਸ ਲਈ fail ਨਹੀਂ ਹੁੰਦੀਆਂ ਕਿ ਕੋਡ "ਗਲਤ" ਹੈ। ਉਹ fail ਹੁੰਦੀਆਂ ਹਨ ਕਿਉਂਕਿ ਅਸਲ ਡੇਟਾ ਗੰਦਗੀ, ਏਕਸਰਸੀ ਅਤੇ ਅਸਮਰਥਤ ਹੁੰਦੀ ਹੈ — ਲੋਕ ਜੋ ਫਾਇਲ ਬਣਾਉਂਦੇ ਹਨ ਉਹ ਤੁਹਾਡੇ ਅਨੁਮਾਨ ਨਹੀਂ ਦੇਖਦੇ।

CSV ਮੁੱਦੇ ਆਮ ਤੌਰ 'ਤੇ shape ਅਤੇ formatting ਸਮੇਤ ਹੁੰਦੇ ਹਨ। JSON ਮੁੱਦੇ ਅਰਥ ਅਤੇ types ਦੇ ਚक्कर ਵਿਚ ਹੁੰਦੇ ਹਨ। ਦੋਹਾਂ ਤਰ੍ਹਾਂ ਦੀਆਂ ਸਮੱਸਿਆਵਾਂ ਅਜੇਹੀਆਂ ਤਰੀਕਿਆਂ ਨਾਲ ਟੁੱਟ ਸਕਦੀਆਂ ਹਨ ਜੋ ਹਲਕੇ ਦਿਸਦੀਆਂ ਹਨ ਪਰ ਉਪਭੋਗਤਾ ਲਈ ਗੁੰਝਲਦਾਰ ਨਤੀਜੇ ਬਣਾਉਂਦੀਆਂ ਹਨ।

ਇਹ ਮੁੱਦੇ support tickets ਵਿੱਚ ਵਾਰ-ਵਾਰ ਨਜ਼ਰ ਆਉਂਦੇ ਹਨ:

• ਲੋੜੀਂਦੇ ਫੀਲਡ (email, id, country) ਗੈਰ ਮੌਜੂਦ ਹੋਣਾ ਜਾਂ ਕਿਸੇ ਨੇ column rename ਕਰ ਦਿੱਤਾ ਹੋਵੇ
• ਅਜੀਬ ਤਰਿੱਖਾਂ (01/02/03, 2024-13-01, Excel serial numbers, ਮਿਲੀ-ਹੋਈ time zones)
• ਵਾਧੂ ਕਾਲਮ ਜਾਂ ਦੁਸਰੇ ਟੂਲ ਵੱਲੋਂ nested JSON objects
• ਟਾਈਪ drift ("00123" ਦੇ 123 ਹੋਣਾ, true/false ਦੇ "yes"/"no" ਹੋ ਜਾਣਾ)
• duplicates ਅਤੇ near-duplicates (ਉਹੀ id ਦੋ ਵਾਰੀ, ਜਾਂ ਉਸੇ ਵਿਅਕਤੀ ਦਾ भਿੰਨ-casing)

Correctness ਸਿਰਫ ਇਹ ਨਹੀਂ ਕਿ "ਇਹ ਆਯਾਤ ਹੋਇਆ"। ਤੁਹਾਨੂੰ ਫੈਸਲਾ ਕਰਨਾ ਪੈਂਦਾ ਹੈ ਕਿ ਕਿਹੜੇ ਨਤੀਜੇ ਬਰਦਾਸ਼ਤ ਹਨ, ਕਿਉਂਕਿ ਉਪਭੋਗਤਾ ਖਾਮੋਸ਼ ਗਲਤੀਆਂ ਨੂੰ ਉੱਚ-ਅਵਾਜ਼ failures ਨਾਲੋਂ ਜ਼ਿਆਦਾ ਨੋਟਿਸ ਕਰਦੇ ਹਨ।

ਜ਼ਿਆਦਾਤਰ ਟੀਮਾਂ ਤਿੰਨ ਨਤੀਜਿਆਂ 'ਤੇ ਸਹਿਮਤ ਹੋ ਸਕਦੀਆਂ ਹਨ:

• Accepted: ਸਾਰੀਆਂ rows ਜਾਂ records ਵੈਧ ਹਨ ਅਤੇ ਆਯਾਤ ਹੋ ਗਈਆਂ
• Rejected: ਕੁਝ ਵੀ ਆਯਾਤ ਨਹੀਂ ਕੀਤਾ ਗਿਆ ਕਿਉਂਕਿ ਫਾਇਲ ਭਰੋਸੇਯੋਗ ਨਹੀਂ (ਗਲਤ headers, ਬੁਰਾ encoding, unreadable JSON)
• Partially accepted: ਵੈਧ ਰਿਕਾਰਡ ਆਯਾਤ ਹੋ ਜਾਂਦੇ ਹਨ, ਗੈਰ-ਵੈਧ ਬਾਈ-passed ਕੀਤੇ ਜਾਂਦੇ ਹਨ ਜਿਨ੍ਹਾਂ ਲਈ ਸਪਸ਼ਟ ਕਾਰਨ ਦਿੱਤਾ ਜਾਵੇ

Edge cases ਮੁੜ-ਮਰammat ਬਣ ਜਾਂਦੀਆਂ ਹਨ ਜਦੋਂ ਲੋਕ ਨਹੀਂ ਸਮਝਦੇ ਕਿ ਕੀ ਗਲਤ ਹੋਇਆ ਜਾਂ ਕਿਵੇਂ ਤੇਜ਼ੀ ਨਾਲ ਠੀਕ ਕਰਨਾ ਹੈ। ਆਮ ਦ੍ਰਿਸ਼: ਇੱਕ ਗ੍ਰਾਹਕ 5,000 row ਵਾਲੀ CSV upload ਕਰਦਾ ਹੈ, importer ਕਹਿੰਦਾ "Invalid format", ਅਤੇ ਉਹ ਤਿੰਨ ਵਾਰੀ random edits ਕਰਕੇ retry ਕਰਦਾ ਹੈ। ਇਸ ਨਾਲ ਕਈ tickets ਬਣਦੇ ਹਨ ਅਤੇ ਕਿਸੇ ਲੋਕ ਨੂੰ ਤੁਹਾਡੇ ਪਾਸੋਂ ਫਾਇਲ local ਤੇ reproduce ਕਰਨੀ ਪੈਂਦੀ ਹੈ।

ਚੀਜ਼ਾਂ ਘਟਾਉਣ ਲਈ goals ਰੱਖੋ: ਘੱਟ retries, ਤੇਜ਼ fixes, predictable ਨਤੀਜੇ। ਜੋ ਨਿਯਮ ਲਿਖਣ ਤੋਂ ਪਹਿਲਾਂ ਫੈਸਲਾ ਕਰੋ ਕਿ "partial" ਦਾ ਕੀ ਮਤਲਬ ਹੈ (ਅਤੇ ਕੀ ਤੁਸੀਂ ਇਸਨੂੰ allow ਕਰਦੇ ਹੋ), ਤੁਸੀਂ row-level issues ਕਿਵੇਂ report ਕਰੋਗੇ, ਅਤੇ ਉਪਭੋਗਤਾ ਅਗਲੇ ਕੀ ਕਰਣ (ਫਾਇਲ edit ਕਰਨੀ, fields map ਕਰਨਾ, ਜਾਂ corrected version export ਕਰਨਾ)। ਜੇ ਤੁਸੀਂ vibe-coding platform ਵਰਗਾ Koder.ai (koder.ai) ਵਰਤ ਰਹੇ ਹੋ validators ਅਤੇ tests ਤੇਜ਼ੀ ਨਾਲ ਬਣਾਉਣ ਲਈ, ਫਿਰ ਵੀ import contract ਹੀ ਹੈ ਜੋ ਉਤਪਾਦ ਦੇ ਵਿਕਾਸ ਦੇ ਨਾਲ ਵਰਤਾਰਾ consistent ਰੱਖਦਾ ਹੈ।

ਨਿਯਮ ਲਿਖਣ ਤੋਂ ਪਹਿਲਾਂ import contract ਤੈਅ ਕਰੋ

ਇੱਕ ਵੀ validation rule ਲਿਖਣ ਤੋਂ ਪਹਿਲਾਂ ਤੈਅ ਕਰੋ ਕਿ ਤੁਹਾਡੇ ਉਤਪਾਦ ਲਈ "valid input" ਦਾ ਕੀ ਅਰਥ ਹੈ। ਜ਼ਿਆਦਾਤਰ import bugs ਉਮੀਦਾਂ ਦੇ ਅਣਮੈਚ ਤੋਂ ਹੋਂਦੀਆਂ ਹਨ — ਯੂਜ਼ਰ ਜੋ upload ਕਰਦੇ ਹਨ ਅਤੇ ਤੁਹਾਡੀ ਸਿਸਟਮ ਜੋ ਗੁਪਤ ਧਾਰਣਾਂ ਰੱਖਦੀ ਹੈ।

ਸ਼ੁਰੂਆਤ formats ਨਾਲ ਕਰੋ, ਅਤੇ ਸਪੱਸ਼ਟ ਹੋਵੋ। "CSV" ਦੇ ਅਰਥ comma ਜਾਂ semicolon, header row ਹੋਣ ਜਾਂ ਨਾ ਹੋਣ, UTF-8 ਜਾਂ "Excel produced" ਹੋ ਸਕਦਾ ਹੈ। JSON ਲਈ ਫੈਸਲਾ ਕਰੋ ਕਿ ਤੁਸੀਂ single object, array of records, ਜਾਂ JSON Lines (ਇੱਕ line ਵਿੱਚ ਇੱਕ JSON object) accept ਕਰਦੇ ਹੋ। ਜੇ nested JSON ਮਨਜ਼ੂਰ ਹੈ, ਤਾਂ ਕਿਹੜੀਆਂ paths ਤੁਸੀਂ ਪੜ੍ਹੋਗੇ ਅਤੇ ਕਿਹੜੀਆਂ ignore ਕਰੋਂਗੇ, ਇਹ ਵੀ ਦੱਸੋ।

ਫਿਰ field contract lock ਕਰੋ। ਹਰ field ਲਈ ਫੈਸਲਾ ਕਰੋ ਕਿ ਉਹ required, optional, ਜਾਂ optional with default ਹੈ। Defaults contract ਦਾ ਹਿੱਸਾ ਹਨ, implementation detail ਨਹੀਂ। ਜੇ country ਗੈਰ-ਮੌਜੂਦ ਹੈ, ਤਾਂ ਤੁਸੀਂ empty ਰੱਖੋਗੇ, ਕਿਸੇ ਖਾਸ ਦੇਸ਼ ਨੂੰ default ਕਰਦੇ ਹੋ, ਜਾਂ row reject ਕਰਦੇ ਹੋ?

Parsing behavior ਉਹ ਥਾਂ ਹੈ ਜਿੱਥੇ "tolerant" imports ਲੰਬੇ ਸਮੇਂ ਦੀ ਪੀੜਾ ਬਣਾਉਂਦੇ ਹਨ। ਪਹਿਲਾਂ ਤੈਅ ਕਰੋ ਕਿ ਤੁਸੀਂ trimming spaces, normalizing case, ਅਤੇ "yes"/"true"/"1" ਵਰਗੇ variants ਕਿੰਨੇ strict/ਲੰਬੇ ਸਮੇਂ ਲਈ ਮਨਜ਼ੂਰ ਕਰੋਗੇ। tolerance ਠੀਕ ਹੈ ਜੇ ਇਹ predictable ਅਤੇ documented ਹੈ।

Duplicates ਇੱਕ ਹੋਰ contract ਫੈਸਲਾ ਹੈ ਜੋ correctness ਅਤੇ trust ਨੂੰ ਪ੍ਰਭਾਵਿਤ ਕਰਦਾ ਹੈ। ਪਰਿਭਾਸ਼ਾ ਕਰੋ ਕਿ duplicate ਕੀ ਹੈ (same email, same external_id, ਜਾਂ fields ਦਾ combo), ਕਿੱਥੇ detect ਕਰੋਗੇ (file ਦੇ ਅੰਦਰ, existing data ਦੇ ਖਿਲਾਫ, ਜਾਂ ਦੋਹਾਂ), ਅਤੇ duplicate ਹੋਣ 'ਤੇ ਕੀ ਕਰਾਂਗੇ (first ਰੱਖੋ, last ਰੱਖੋ, merge, ਜਾਂ reject)।

ਇੱਕ contract checklist ਜੋ ਤੁਸੀਂ spec ਵਿੱਚ paste ਕਰ ਸਕਦੇ ਹੋ:

• Accepted formats ਅਤੇ encoding (CSV delimiter, JSON vs JSON Lines, nested support)
• Field rules (required/optional/defaults, allowed values)
• Normalization rules (trim, case, date/number formats)
• Duplicate definition ਅਤੇ handling (detection scope, chosen behavior)
• Validation placement (client, server, or both)

ਉਦਾਹਰਨ: "customers" import ਕਰਦੇ ਸਮੇਂ। ਜੇ email unique key ਹੈ, ਤਾਂ ਫੈਸਲਾ ਕਰੋ ਕਿ \" [email protected] \" ਅਤੇ \"[email protected]\" ਦੀ ਬਰਾਬਰੀ ਹੈ ਜਾਂ ਨਹੀਂ, ਜੇ external_id ਮੌਜੂਦ ਹੈ ਤਾਂ missing email allowed ਹੈ ਜਾਂ ਨਹੀਂ, ਅਤੇ ਫਾਇਲ ਦੇ ਅੰਦਰ duplicates ਨੂੰ reject ਕਰਨਾ ਹੈ ਭਾਵੇਂ DB ਵਿੱਚ ਕੋਈ match ਨਾ ਹੋਵੇ। ਜਦੋਂ contract fix ਹੋ ਜਾਵੇ, ਤਾਂ UI ਅਤੇ API ਵਿੱਚ consistent behavior ਆਸਾਨ ਬਣ ਸਕਦੀ ਹੈ, ਚਾਹੇ ਤੁਸੀਂ Koder.ai ਵਿੱਚ implement ਕਰੋ ਜਾਂ ਹੋਰਥਾਂ।

ਪੜ੍ਹਨਯੋਗ ਅਤੇ ਟੈਸਟਯੋਗ validation rules

ਗੰਦੇ imports ਆਮ ਤੌਰ 'ਤੇ ਇੱਕ ਵੱਡੇ validate() function ਤੋਂ ਸ਼ੁਰੂ ਹੁੰਦੇ ਹਨ। ਇੱਕ ਸਾਫ ਸਲੂਕ layered rules ਨਾਲ ਕਰੋ ਜਿੱਥੇ ਹਰ rule ਦਾ ਨਾਮ ਅਤੇ ਛੋਟੀ function ਹੋਵੇ। ਇਸ ਨਾਲ changes review ਕਰਨਾ ਆਸਾਨ ਹੁੰਦਾ ਹੈ ਅਤੇ tests ਲਿਖਣਾ ਵੀ।

ਸ਼ੁਰੂ ਕਰੋ field-level rules ਨਾਲ: ਇੱਕ single value ਦੀ ਜਾਂਚ ਜੋ ਖੁਦ ਵਿੱਚ pass ਜਾਂ fail ਹੋ ਸਕਦੀ ਹੈ (type, range, length, allowed values, regex)। ਉਨ੍ਹਾਂ ਨੂੰ ਸਧਾਰਨ ਅਤੇ predictable ਰੱਖੋ। ਉਦਾਹਰਨ: email ਇੱਕ basic email pattern ਨਾਲ match ਹੋਵੇ, age integer ਹੋਵੇ 0 ਤੋਂ 120 ਦੇ ਵਿਚਕਾਰ, status ਇੱਕ active|paused|deleted ਵਿੱਚੋਂ ਹੋਵੇ।

ਜਿੱਥੇ ਜ਼ਰੂਰੀ ਹੋਵੇ ਉਥੇ cross-field rules add ਕਰੋ। ਇਹ checks multiple fields 'ਤੇ ਨਿਰਭਰ ਕਰਦੇ ਹਨ ਅਤੇ ਬੱਗ ਇੱਥੇ ਛੁਪਦੇ ਹਨ। ਕਲਾਸਿਕ ਉਦਾਹਰਨ: startDate should be before endDate, ਜਾਂ total equals subtotal + tax - discount। ਇਹ rules ਐਸੇ ਲਿਖੋ ਕਿ ਉਹ specific fields ਨੂੰ point ਕਰ ਸਕਣ, ਨਾ ਕਿ ਸਿਰਫ "record invalid" ਕਹਿਣ।

Record-level rules ਨੂੰ file-level rules ਤੋਂ ਵੱਖਰਾ ਰੱਖੋ। Record-level rule ਇੱਕ row (CSV) ਜਾਂ ਇੱਕ object (JSON) ਜਾਂਚਦਾ ਹੈ। File-level rule ਪੂਰੇ upload ਨੂੰ ਜਾਂਚਦਾ ਹੈ: required headers ਮੌਜੂਦ ਹਨ, unique key ਫਾਇਲ ਵਿੱਚ ਨੀ ਦੋਹਰਾਈ, column count expectations ਨਾਲ match ਕਰਦਾ ਹੈ, ਜਾਂ ਫਾਇਲ supported version declare ਕਰਦੀ ਹੈ।

Normalization explicit ਹੋਣੀ ਚਾਹੀਦੀ ਹੈ, ਨਾ ਕਿ "magic"। ਫੈਸਲਾ ਕਰੋ ਕਿ ਕੀ ਤੁਸੀਂ validate ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ normalize ਕਰੋਗੇ ਅਤੇ ਇਸਨੂੰ document ਕਰੋ। ਆਮ ਉਦਾਹਰਨਾਂ: spaces trim ਕਰਨਾ, Unicode normalization (ਤਾਕਿ ਵਿਜ਼ੂਅਲ ਦੇਖਣ ਵਾਲੇ identical characters same ਤਰੀਕੇ ਨਾਲ compare ਹੋਣ), ਅਤੇ phone numbers ਨੂੰ ਇੱਕ consistent storage format ਵਿੱਚ ਫਾਰਮੈਟ ਕਰਨਾ।

ਇਕ ਵਿਆਕਤ ਰਚਨਾ ਜੋ ਪੜ੍ਹਨਯੋਗ ਰਹਿੰਦੀ ਹੈ:

• Normalize: raw input ਨੂੰ canonical shape ਵਿੱਚ ਤਬਦੀਲ ਕਰੋ।
• Validate fields: small, reusable checks per field.
• Validate relationships: cross-field checks with clear targets.
• Validate file rules: headers, duplicates, ਅਤੇ version support.
• Test each layer: unit tests for each rule, ਤੇ ਕੁਝ end-to-end fixtures।

ਆਪਣੀਆਂ rules ਨੂੰ version ਕਰੋ। ਇੱਕ schemaVersion (ਜਾਂ import “profile”) ਫਾਇਲ ਜਾਂ API request ਵਿੱਚ ਪਾਓ। ਜਦੋਂ ਤੁਸੀਂ "valid" ਦਾ ਮਤਲਬ ਬਦਲਦੇ ਹੋ, ਤੁਸੀਂ ਪੁਰਾਣੀ exports ਨੂੰ ਵੀ ਪੁਰਾਣੇ version ਨਾਲ re-import ਕਰ ਸਕਦੇ ਹੋ। ਇਹ ਇਕ ਚੋਣ ਬਹੁਤ ਸਾਰੀਆਂ "ਅੱਜ ਤੱਕ ਚੱਲਦਾ ਸੀ" tickets ਰੋਕਦੀ ਹੈ।

ਐਸਾ error reporting format ਡਿਜ਼ਾਈਨ ਕਰੋ ਜੋ ਲੋਕ ਕਾਰਵਾਈ ਕਰ ਸਕਣ

ਇੱਕ ਚੰਗਾ importer ਮਦਦਗਾਰ ਤਰੀਕੇ ਨਾਲ fail ਹੁੰਦਾ ਹੈ। vague errors random retries ਅਤੇ avoidable support work ਨੂੰ ਜਨਮ ਦਿੰਦੇ ਹਨ। ਇੱਕ ਸਪੱਸ਼ਟ error format ਯੂਜ਼ਰਾਂ ਨੂੰ ਫਾਇਲ ਤੇਜ਼ੀ ਨਾਲ ਠੀਕ ਕਰਨ ਵਿੱਚ ਮਦਦ ਕਰਦਾ ਹੈ, ਅਤੇ validations ਨੂੰ ਬਦਲੇ ਬਿਨਾਂ clients ਨੂੰ ਟੁੱਟਣ ਤੋਂ ਬਚਾਉਂਦਾ ਹੈ।

ਸ਼ੁਰੂ ਕਰੋ ਇੱਕ stable error object shape ਨਾਲ ਅਤੇ CSV ਅਤੇ JSON ਦੁਨੀਆਂ ਵਿੱਚ consistency ਰੱਖੋ। ਤੁਸੀਂ Claude Code ਵਰਤ ਕੇ ਇੱਕ schema ਅਤੇ ਕੁਝ realistic examples propose ਕਰਵਾ ਸਕਦੇ ਹੋ, ਫਿਰ ਉਸਨੂੰ import contract ਦਾ ਹਿੱਸਾ ਬਣਾਓ।

ਇਕ ਸਥਿਰ error object

ਹਰ error ਨੂੰ ਇੱਕ ਛੋਟੇ record ਵਜੋਂ treat ਕਰੋ ਜਿਸ ਦੇ fields change ਨਾ ਹੋਣ। message ਵਿਕਸਿਤ ਹੋ ਸਕਦਾ ਹੈ, ਪਰ code ਅਤੇ location stable ਰਹਿਣੇ ਚਾਹੀਦੇ ਹਨ।

• code: ਇੱਕ ਛੋਟਾ, stable identifier ਜਿਵੇਂ REQUIRED_MISSING ਜਾਂ INVALID_DATE
• message: UI ਲਈ human-friendly sentence
• path: ਜਿੱਥੇ ਸਮੱਸਿਆ ਹੈ (JSON pointer ਜਿਵੇਂ /customer/email, ਜਾਂ column name ਜਿਵੇਂ email)
• row ਜਾਂ line: CSV ਲਈ 1-based row number (ਤੇ optionally original line)
• severity: ਘੱਟ-ਭਾਗ error ਅਤੇ warning

Errors actionable ਬਣਾਓ। ਉਮੀਦ ਕੀਤੀ ਗਈ ਚੀਜ਼ ਅਤੇ ਜੋ ਮਿਲੀ ਉਹ ਦਿਖਾਓ, ਅਤੇ ਜੇ ਸੰਭਵ ਹੋਵੇ ਤੋ ਇਕ example ਦਿਓ ਜੋ pass ਕਰੇ। ਉਦਾਹਰਨ: expected YYYY-MM-DD, got 03/12/24।

UI ਅਤੇ debugging ਲਈ grouping

ਜਿੱਥੇ ਤੱਕ ਤੁਸੀਂ flat list ਵਾਪਸ ਕਰਦੇ ਹੋ, ਕਾਫੀ data ਦਿਓ ਤਾਂ errors row ਅਤੇ field ਅਨੁਸਾਰ group ਕੀਤੇ ਜਾ ਸਕਣ। ਬਹੁਤ ਸਾਰੀਆਂ UIs ਨੂੰ ਚਾਹੀਦਾ ਹੈ “Row 12 has 3 issues” ਅਤੇ ਫਿਰ ਹਰ column ਨੂੰ highlight ਕਰਨ ਦੀ ਯੋਗਤਾ। Support teams patterns ਵੇਖਣ ਲਈ grouping ਚਾਹੁੰਦੇ ਹਨ (ਉਦਾਹਰਨ: ਹਰ row missing country)।

ਇੱਕ compact response ਇਸ ਤਰ੍ਹਾਂ ਹੋ ਸਕਦੀ ਹੈ:

{
  "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"
    }
  ]
}

Localization ਲਈ ਯੋਜਨਾ ਬਣਾਓ ਬਿਨਾਂ error codes ਬਦਲੇ। code language-neutral ਅਤੇ durable ਰੱਖੋ, message translateable ਟੈਕਸਟ ਹੋਵੇ। ਜੇ ਤੁਸੀਂ ਬਾਅਦ ਵਿੱਚ messageKey ਜਾਂ translated messages add ਕਰੋ, ਪੁਰਾਣੇ clients ਹਾਲੇ ਵੀ same codes 'ਤੇ rely ਕਰ ਸਕਦੇ ਹਨ।

ਸਫਲਤਾ ਅਤੇ ਅਸਫਲਤਾ 'ਤੇ import API ਕੀ ਵਾਪਸ ਕਰੇ

"ਮਿਸਟਰੀ imports" ਤੋਂ ਬਚਣ ਲਈ, API response ਦੋ ਸਵਾਲਾਂ ਦਾ ਜਵਾਬ ਦੇਵੇ: ਕੀ ਹੋਇਆ, ਅਤੇ ਯੂਜ਼ਰ ਅਗਲਾ ਕੀ ਕਰੇ।

ਹਰ ਵਾਰੀ ਇੱਕ ਸਪੱਸ਼ਟ import summary ਵਾਪਸ ਕਰੋ

ਭਾਵੇਂ errors ਹੋਣ ਜਾਂ ਨਾ, consistent summary ਦਿਓ ਤਾਂ UI ਅਤੇ support tooling ਹਰ import ਨੂੰ ਇੱਕੋ ਤਰੀਕੇ ਨਾਲ handle ਕਰ ਸਕਣ।

ਸ਼ਾਮਿਲ ਕਰੋ:

• created, updated, skipped, failed counts
• totalRows (ਜਾਂ JSON ਲਈ totalRecords)
• mode (ਉਦਾਹਰਨ: createOnly, upsert, ਜਾਂ updateOnly)
• startedAt ਅਤੇ finishedAt timestamps
• ਇੱਕ correlationId ਜੋ support ਪੁੱਛ ਸਕਦਾ ਹੈ

ਇਹ correlationId ਬਹੁਤ ਮੁੱਲ ਰੱਖਦਾ ਹੈ। ਜਦੋਂ ਕੋਈ ਰਿਪੋਰਟ ਕਰਦਾ ਹੈ "ਇਹ ਆਯਾਤ ਨਹੀਂ ਹੋਇਆ", ਤੁਸੀਂ ਅਸਾਨੀ ਨਾਲ ਉਸ exact run ਅਤੇ error report ਲੱਭ ਸਕਦੇ ਹੋ।

actionable errors ਅਤੇ full report ਤੱਕ ਪਹੁੰਚ

10,000 row errors response ਵਿੱਚ dump ਨਾ ਕਰੋ। ਇੱਕ ਛੋਟਾ sample (ਉਦਾਹਰਨ: 20) ਦਿਓ ਜੋ pattern ਦਿਖਾਏ, ਅਤੇ full report ਵੱਖਰਾ ਤਰੀਕਾ ਰੱਖੋ ਜੋ ਲੋੜ ਹੋਣ 'ਤੇ fetch ਕੀਤਾ ਜਾ ਸਕੇ।

ਹਰ error ਨੂੰ specific ਅਤੇ stable ਰੱਖੋ:

• location: row number (CSV) ਜਾਂ JSON pointer-like path (JSON)
• field name
• error code (machine-readable)
• message (human-readable)
• rejected value (ਸੰਵੇਦਨਸ਼ੀਲ ਡੇਟਾ ਦੇ ਨਾਲ ਸਾਵਧਾਨ)

ਉਦਾਹਰਨ response shape (success ਪਰ ਕੁਝ row failures ਨਾਲ):

{
  "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 ਫੀਲਡ ਦੀ ਨੋਟ ਕਰੋ। ਇੱਕ ਘੱਟੋ-ਘੱਟ success payload ਵੀ ਪ੍ਰੋਡਕਟ ਨੂੰ ਅਗੇ ਵਧਣ ਲਈ ਮਦਦ ਕਰੇ: review screen ਦਿਖਾਓ, retry ਦੀ ਪੇਸ਼ਕਸ਼ ਕਰੋ, ਜਾਂ imported collection ਖੋਲ੍ਹੋ।

idempotency define ਕਰੋ ਤਾਂ ਕਿ repeat uploads double-create ਨਾ ਕਰਨ

ਲੋਕ retry ਕਰਦੇ ਹਨ। ਨੈੱਟਵਰਕ fail ਕਰਦਾ ਹੈ। ਜੇ ਇਕੋ ਫਾਇਲ ਦੋ ਵਾਰੀ import ਕੀਤੀ ਜਾਂਦੀ ਹੈ ਤਾਂ ਤੁਹਾਨੂੰ predictable ਨਤੀਜੇ ਚਾਹੀਦੇ ਹਨ।

Idempotency ਬਾਰੇ ਸਪੱਸ਼ਟ ਹੋਵੋ: idempotencyKey قبول ਕਰੋ (ਜਾਂ file hash compute ਕਰੋ), ਅਤੇ ਜੇ request repeat ਹੋਵੇ ਤਾਂ existing importId ਵਾਪਸ ਕਰੋ। ਜੇ mode upsert ਹੈ ਤਾਂ matching rule define ਕਰੋ (ਉਦਾਹਰਨ: "email unique key")। ਜੇ create-only ਹੈ ਤਾਂ duplicates ਲਈ "skipped" return ਕਰੋ, "created again" ਨਹੀਂ।

failures ਲਈ ਠੀਕ status ਵਰਤੋ, ਪਰ shape stable ਰੱਖੋ

ਜੇ ਪੂਰਾ request invalid ਹੈ (bad auth, wrong content type, unreadable file), ਤੁਰੰਤ fail ਕਰੋ ਅਤੇ status: "rejected" ਛੋਟੀ error list ਨਾਲ ਵਾਪਸ ਕਰੋ। ਜੇ ਫਾਇਲ valid ਹੈ ਪਰ row-level problems ਹਨ, ਤਾਂ ਇਸਨੂੰ completed job treat ਕਰੋ failed > 0 ਨਾਲ ਤਾਂ ਕਿ ਯੂਜ਼ਰ ਫਾਇਲ fix ਕਰਕੇ re-upload ਕਰ ਸਕੇ ਬਿਨਾਂ summary ਗੁਆਉਂਦੇ।

Claude Code ਨੂੰ rules ਅਤੇ examples generate ਕਰਨ ਲਈ ਕਿਵੇਂ ਵਰਤਣਾ ਹੈ

ਇੱਕ ਉਪਯੋਗੀ ਆਦਤ: model ਨੂੰ contract structured format ਵਿੱਚ ਲਿਖਣ ਲਈ ਕਹੋ, prose ਵਿੱਚ ਨਹੀਂ। "ਹੈਲਪਫੁਲ ਪੈਰਾਗ੍ਰਾਫ" ਅਕਸਰ trimming rules, default values, ਅਤੇ ਇਹ ਕਿ blank cell "missing" ਹੈ ਜਾਂ "empty" ਵਰਗੀਆਂ details skip ਕਰ ਦਿੰਦੇ ਹਨ।

ਇੱਕ prompt ਵਰਤੋਂ ਜੋ ਇੱਕ table force ਕਰੇ ਜੋ ਮਨੁੱਖ ਤੇ developer ਦੋਹਾਂ ਤੇਜ਼ੀ ਨਾਲ review ਕਰ ਸਕਣ। ਹਰ field ਦੀ rule, pass ਅਤੇ fail examples, ਅਤੇ ambiguous ਚੀਜ਼ਾਂ ਲਈ explicit note ਮੰਗੋ (ਉਦਾਹਰਨ: empty string 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).

ਪਹਿਲੀ ਡਰਾਫਟ ਦੇ ਬਾਅਦ, ਇਸਨੂੰ ਤੀਖਾ ਕਰਨ ਲਈ ਮਾਡਲ ਨੂੰ ਹਰ rule ਲਈ ਇੱਕ positive ਅਤੇ ਇੱਕ negative example ਮੰਗੋ। ਇਹ tricky corners ਦਾ coverage ਵਧਾਉਂਦਾ ਹੈ ਜਿਵੇਂ empty strings, whitespace-only values, missing columns, null vs "null", ਬਹੁਤ ਵੱਡੇ integers, scientific notation, duplicate IDs, ਅਤੇ extra JSON fields।

ਇਕ concrete ਸਥਿਤੀ ਲਈ, "customers" CSV import ਸੋਚੋ: email required ਹੈ, phone optional ਹੈ, ਅਤੇ signup_date missing ਹੋਣ 'ਤੇ today ਨੂੰ default ਕਰਦਾ ਹੈ। ਮਾਡਲ ਨੂੰ contradiction flag ਕਰਨਾ ਚਾਹੀਦਾ ਹੈ ਜੇ ਤੁਸੀਂ ਇਕੱਠੇ ਕਹੋ "signup_date required"। ਇਹ import_customers_missing_email_returns_row_error ਜਿਹੇ tests propose ਕਰੇਗਾ ਅਤੇ error code/message shape specify ਕਰੇਗਾ।

Implementation ਤੋਂ ਪਹਿਲਾਂ ਇਕ ਹੋਰ pass ਕਰੋ: ਮਾਡਲ ਨੂੰ rules ਨੂੰ ਇੱਕ checklist ਵਜੋਂ restate ਕਰਨ ਲਈ ਕਹੋ ਅਤੇ ਦੱਸੋ ਕਿ defaults, required fields, ਅਤੇ normalization ਕਿੱਥੇ conflict ਕਰ ਸਕਦੇ ਹਨ। ਇਹ review ਕਦਮ ਬਹੁਤ ਸਾਰੀਆਂ ticket-worthy behavior ਫੜ ਲੈਦਾ ਹੈ।

CSV ਅਤੇ JSON imports ਲਈ fuzz tests: 단계-ਦਰ-ਕਦਮ

Fuzz testing "ਅਜੀਬ ਫਾਇਲਾਂ" ਨੂੰ support tickets ਬਣਨ ਤੋਂ ਰੋਕਦਾ ਹੈ। ਛੋਟੀ seed set ਤੋਂ ਸ਼ੁਰੂ ਕਰੋ, ਫਿਰ ہزارਾਂ ਥੋੜੀਆਂ-ਥੋੜੀਆਂ variation generate ਕਰੋ ਅਤੇ ਯਕੀਨੀ ਬਣਾਓ ਕਿ importer ਸੁਰੱਖਿਅਤ ਅਤੇ ਸਪੱਸ਼ਟ ਤਰੀਕੇ ਨਾਲ react ਕਰਦਾ ਹੈ।

seed ਬਣਾਓ, ਫਿਰ mutate ਕਰੋ

ਸਭ ਤੋਂ ਪਹਿਲਾਂ ਕੁਝ valid examples ਦਾ seed corpus ਬਣਾਓ ਜੋ ਅਸਲੀ ਵਰਤੋਂ ਦਰਸਾਉਂਦੇ ਹਨ: ਸਭ ਤੋਂ ਛੋਟੀ valid file, ਇੱਕ typical file, ਅਤੇ ਇਕ ਵੱਡੀ file। JSON ਲਈ, ਇਕ object, ਬਹੁਤ ਸਾਰੇ objects, ਅਤੇ nested structures ਸ਼ਾਮਿਲ ਕਰੋ ਜੇ ਤੁਸੀਂ ਉਹਨਾਂ ਨੂੰ support ਕਰੋ।

ਫਿਰ ਇਕ automated mutator ਜੋ ਇੱਕ-ਇੱਕ ਚੀਜ਼ ਨੂੰ tweak ਕਰੇ। mutations reproducible ਰੱਖੋ pamamagitan random seed ਨੂੰ log ਕਰਕੇ ਤਾਂ ਜੋ failures replay ਕੀਤੇ ਜਾ ਸਕਣ।

Fuzz dimensions ਜੋ ਅਕਸਰ ਅਸਲ-ਦੁਨੀਆਂ ਦੀਆਂ ਸਮੱਸਿਆਵਾਂ ਫੜਦੇ ਹਨ:

• Encoding issues: UTF-8 with BOM, invalid byte sequences, mixed normalization
• Structure issues: missing headers, extra columns/fields, wrong delimiter, trailing commas
• Quoting and newlines: unclosed quotes, embedded newlines, CRLF vs LF, inconsistent escaping
• Type edges: huge integers, NaN/Infinity (JSON), empty strings vs null, whitespace padding
• Size and limits: very long fields, many rows, repeated keys, deeply nested arrays

syntax 'ਤੇ ਹੀ ਰੁਕੋ ਨਾ। semantic fuzz ਵੀ add ਕਰੋ: similar fields swap ਕਰਨਾ (email vs username), extreme dates, duplicate IDs, negative quantities, ਜਾਂ values ਜੋ enums violate ਕਰਦੇ ਹਨ।

"ਪਾਸ" ਦਾ ਕੀ ਮਤਲਬ ਹੈ, ਫਿਰ ਉਸਨੂੰ lock ਕਰੋ

Fuzz tests ਤਦ ਹੀ ਮਦਦਗਾਰ ਹਨ ਜਦੋਂ pass criteria ਕੱਡੇ ਹੋਣ। ਤੁਹਾਡਾ importer crash ਜਾਂ hang ਨਾ ਕਰਨ ਚਾਹੀਦਾ, ਅਤੇ errors consistent ਅਤੇ actionable ਹੋਣੇ ਚਾਹੀਦੇ ਹਨ।

ਪ੍ਰਾਇਕਟਿਕ pass rules:

• Koi crash, timeout, ਜਾਂ memory spike ਨਾ ਹੋਵੇ
• Clear errors row/field pointers (CSV) ਜਾਂ JSON paths
• Stable error codes across runs for the same failure
• ਕੋਇ partial writes ਨਾ ਹੋਣ ਜੇ ਤੁਸੀਂ explicit partial success support ਨਹੀਂ ਕਰਦੇ
• Successful imports harmless formatting (ਜਿਵੇਂ whitespace) ਨਾਲ identical results ਦੇਣ

ਇਹ tests CI ਵਿੱਚ ਹਰ ਬਦਲਾਅ 'ਤੇ ਚਲਾਓ। ਜਦੋਂ failure ਮਿਲੇ, ਉਸ exact file ਨੂੰ fixture ਵਜੋਂ save ਕਰੋ ਅਤੇ regression test add ਕਰੋ ਤਾਂ ਕਿ ਇਹ ਮੁੜ ਨਾ ਆਵੇ।

ਜੇ ਤੁਸੀਂ Claude Code ਇਸ ਕੰਮ ਲਈ ਵਰਤਦੇ ਹੋ, ਤਾਂ ਉਹ seed fixtures ਜੋ ਤੁਹਾਡੇ contract ਨਾਲ match ਕਰਦੀਆਂ ਹਨ, ਇੱਕ mutation plan, ਅਤੇ expected error outputs generate ਕਰ ਸਕਦਾ ਹੈ। ਤੁਸੀਂ rules choose ਕਰਦੇ ਹੋ, ਪਰ ਤੁਸੀਂ ਤੇਜ਼ੀ ਨਾਲ ਵੱਡਾ test surface ਪਾਉਂਦੇ ਹੋ, ਖਾਸ ਕਰਕੇ CSV quoting ਅਤੇ JSON corner cases ਲਈ।

ਅਕਸਰ ਘੱਟੀਆਂ ਜਿਹੜੀਆਂ support tickets ਬਣਾਉਂਦੀਆਂ ਹਨ

ਜਿਆਦਾਤਰ import tickets unclear rules ਅਤੇ unhelpful feedback ਤੋਂ ਆਉਂਦੀਆਂ ਹਨ।

ਇੱਕ ਆਮ ਜਾਲ "best effort" parsing ਹੈ ਜੋ ਦਸਤਾਵੇਜ਼ ਵਿੱਚ ਨਹੀਂ ਲਿਖਿਆ ਹੁੰਦਾ। ਜੇ ਤੁਹਾਡਾ importer ਖਾਮੋਸ਼ੀ ਨਾਲ spaces trim ਕਰਦਾ ਹੈ, comma ਅਤੇ semicolon ਦੋਹਾਂ accept ਕਰਦਾ ਹੈ, ਜਾਂ date formats guess ਕਰਦਾ ਹੈ, ਤਾਂ ਯੂਜ਼ਰ ਉਹਨਾਂ guesses 'ਤੇ ਆਸਰਾ ਕਰ ਲੈਂਦੇ ਹਨ। ਫਿਰ ਕੋਈ ਛੋਟੀ change ਜਾਂ ਵੱਖਰੀ file generator ਸਾਰਾ ਕੁਝ ਤੋੜ ਸਕਦੀ ਹੈ। ਵਿਵਹਾਰ ਚੁਣੋ, document ਕਰੋ, ਅਤੇ test ਕਰੋ।

ਦੂਜਾ repeat offender generic error messages ਹਨ। "Invalid CSV" ਜਾਂ "Bad request" ਯੂਜ਼ਰ ਨੂੰ guess ਕਰਨ ਲਈ ਮਜਬੂਰ ਕਰਦਾ ਹੈ। ਉਹ same file ਪੰਜ ਵਾਰੀ upload ਕਰਦੇ ਹਨ ਅਤੇ support ਨੂੰ ਫਾਇਲ ਮੰਗਣੀ ਪੈਂਦੀ ਹੈ। Errors ਨੂੰ row, field, clear reason, ਅਤੇ stable code ਦਿਓ।

ਇੱਕ ਹੋਰ ਦਰਦ-ਕਾਰਣ ਵਾਲੀ ਗੱਲ ਸਾਰੀ ਫਾਇਲ ਨੂੰ ਇੱਕ ਖਰਾਬ row ਲਈ fail ਕਰ ਦੇਣਾ ਹੈ। ਕਈ ਵਾਰ ਇਹ ਸਹੀ ਹੁੰਦਾ ਹੈ (ਉਦਾਹਰਨ: financial imports ਜਿੱਥੇ partial data ਖਤਰਨਾਕ ਹੁੰਦੀ ਹੈ), ਪਰ ਬਹੁਤ ਸਾਰੇ business imports continue ਕਰ ਸਕਦੇ ਹਨ ਜੇ summary report ਦਿੱਤੀ ਜਾਵੇ ਅਤੇ strict mode vs partial import ਵਾਂਗ explicit ਚੋਣ ਹੋਵੇ।

Text encoding issues ਵੀ stubborn tickets ਬਣਾਉਂਦੇ ਹਨ। UTF-8 ਆਮ ਤੌਰ 'ਤੇ ਸਹੀ default ਹੈ, ਪਰ ਅਸਲ CSVs ਅਕਸਰ BOM, curly quotes, ਜਾਂ non-breaking spaces ਦੇ ਨਾਲ ਹੁੰਦੇ ਹਨ। ਇਨ੍ਹਾਂ ਨੂੰ consistent ਰੂਪ ਨਾਲ handle ਕਰੋ ਅਤੇ ਜੋ ਦਿਸਿਆ ਉਹ report ਕਰੋ ਤਾਂ ਯੂਜ਼ਰ export settings ਠੀਕ ਕਰ ਸਕੇ।

ਅਖੀਰ ਵਿੱਚ, error codes ਨੂੰ releases ਵਿਚ ਬਦਲਣਾ clients ਅਤੇ automations ਨੂੰ ਤੋੜ ਸਕਦਾ ਹੈ। wording ਨੂੰ ਸੁਧਾਰੋ ਪਰ codes ਅਤੇ meanings stable ਰੱਖੋ। ਜਦੋਂ ਵਾਸਤੇ ਲੋੜ ਹੋਵੇ ਤਦ ਹੀ ਉਹਨਾਂ ਨੂੰ version ਕਰੋ।

ਰਾਹਾਂ ਜੋ ਪਹਿਲਾਂ ਹੀ guard ਕਰਨਯੋਗ ਹਨ:

• undocumented “best effort” parsing ਜੋ ਸਮੇਂ ਦੇ ਨਾਲ ਬਦਲਦਾ ਰਹੇ
• Errors bina row/field pointers ਅਤੇ stable error code ਦੇ
• All-or-nothing imports ਬਿਨਾਂ strict vs partial option ਦੇ
• UTF-8, BOM, ਅਤੇ invisible characters inconsistent handling
• Error code changes ਜੋ client-side handling ਤੋੜਦੇ ਹਨ

ਉਦਾਹਰਨ: ਗ੍ਰਾਹਕ Excel ਤੋਂ CSV export ਕਰਦਾ ਹੈ ਜੋ BOM add ਕਰਦਾ ਹੈ ਅਤੇ dates 03/04/2026 ਦੇ ਰੂਪ ਵਿੱਚ ਰੱਖਦਾ ਹੈ। ਤੁਹਾਡਾ importer MM/DD guess ਕਰਦਾ ਹੈ ਪਰ ਗ੍ਰਾਹਕ DD/MM ਦੀ ਉਮੀਦ ਰੱਖਦਾ ਹੈ। ਜੇ ਤੁਹਾਡੀ error report detected format, exact field, ਅਤੇ suggested fix ਦਿਖਾਏ, ਤਾਂ ਯੂਜ਼ਰ ਬਿਨਾਂ ਬਹੁਤ-ਵਾਰ ਲਈ ਫਾਇਲ ਠੀਕ ਕਰ ਸਕਦਾ ਹੈ।

ਇੱਕ ਛੋਟਾ ਚੈੱਕਲਿਸਟ ਪਹਿਲਾਂ ship ਕਰਨ

ਅਕਸਰ import problems ਛੋਟੀ-ਛੋਟੀ mismatches ਹਨ ਜੋ ਯੂਜ਼ਰ ਦੀ ਸੋਚ ਅਤੇ ਤੁਹਾਡੀ ਸਿਸਟਮ ਦੀ ਸਵੀਕਾਰਤਾ ਦਰਮਿਆਨ ਹੁੰਦੀਆਂ ਹਨ। ਇਸਨੂੰ ਇੱਕ release gate ਵਜੋਂ treat ਕਰੋ।

• Headers ਅਤੇ field names: confirm required columns ਮੌਜੂਦ ਹਨ, names rules ਨਾਲ match ਕਰਦੇ ਹਨ, ਅਤੇ duplicates reject ਹੁੰਦੇ ਹਨ। extra columns ਨਾਲ ਕੀ ਕੀਤਾ ਜਾਏ (ignore, warn, fail) ਇਹ ਫੈਸਲਾ consistent ਰੱਖੋ।
• Data types ਅਤੇ formats: integers vs decimals, booleans (true/false, 0/1, yes/no), dates ਅਤੇ timestamps (timezone rules) ਦਾ ਤਰੀਕਾ lock ਕਰੋ। ਹਰੇਕ field ਲਈ ਇੱਕ accepted format prefer ਕਰੋ।
• Null ਅਤੇ missing values: per field empty string ਦਾ ਮਤਲਬ ਕੀ ਹੈ ਇਹ define ਕਰੋ। missing field, explicit null, ਅਤੇ blank text ਨੂੰ ਵੱਖਰਾ ਰੱਖੋ।
• Size ਅਤੇ safety limits: file size, maximum rows, ਅਤੇ maximum field length ਲਈ limits ਰੱਖੋ। Fail early with a clear message.
• Deterministic errors: same bad input ਹਮੇਸ਼ਾ same error code ਅਤੇ message shape ਦੇਵੇ।

ਇੱਕ عملي ਟੈਸਟ: ਇਕ ਇਰਾਦਾ-ਪੂਰਨ messy file ਵਰਤੋ। ਉਦਾਹਰਨ: header ਦੋ ਵਾਰੀ ਆ ਰਿਹਾ ਹੈ (두 "email" columns), boolean field "Y" ਵਰਤਦਾ ਹੈ, ਅਤੇ date "03/04/05" ਹੈ। ਤੁਹਾਡਾ importer guess ਨਾ ਕਰੇ। ਜਾਂ ਤਾਂ documented mapping rule apply ਕਰੋ ਜਾਂ specific error ਨਾਲ reject ਕਰੋ।

ਦੋ checks ਜੋ ਟੀਮਾਂ ਅਕਸਰ ਛੱਡ ਦਿੰਦੀਆਂ ਹਨ:

ਪਹਿਲਾ, importer errors ਵਿੱਚ ਕਾਫੀ location detail ਦਿਓ ਤਾਂ source file fix ਹੋ ਸਕੇ। "Invalid date" actionable ਨਹੀਂ ਹੈ। "Row 42, column start_date: expected YYYY-MM-DD, got 03/04/05" actionable ਹੈ।

ਦੂਜਾ, ਇਕੋ invalid file ਦੋ ਵਾਰੀ ਚਲਾਓ ਅਤੇ ਨਤੀਜਿਆਂ ਦੀ ਤੁਲਨਾ ਕਰੋ। ਜੇ error order change ਹੋਵੇ, codes change ਹੋਣ, ਜਾਂ row numbers drift ਕਰਨ, ਤਾਂ ਯੂਜ਼ਰ trust ਘਟਦਾ ਹੈ। Deterministic behavior boring ਹੈ — ਅਤੇ ਇਹੀ ਮਕਸਦ ਹੈ।

ਇੱਕ ਹਕੀਕਤੀ ਉਦਾਹਰਨ ਅਤੇ ਅਗਲੇ ਕਦਮ

ਇੱਕ ਆਮ real-world import spreadsheet export ਤੋਂ ਆ ਰਹੇ customer orders ਹੈ। ਕੋਈ ਜੀটি ਸਿਸਟਮ ਤੋਂ CSV export ਕਰਦਾ, Excel ਵਿੱਚ edit ਕਰਦਾ, ਫਿਰ upload ਕਰਦਾ। ਜ਼ਿਆਦਾਤਰ tickets ਉਸ ਵੇਲੇ ਹੁੰਦੀਆਂ ਹਨ ਜਦੋਂ importer ਨੇ data ਨੂੰ ਖਾਮੋਸ਼ੀ ਨਾਲ "fix" ਕੀਤਾ, ਜਾਂ error message ਨਹੀਂ ਦੱਸਦੀ ਕਿ ਕੀ change ਕਰਨਾ ਹੈ।

ਮੰਨੋ ਇਕ ਫਾਇਲ orders.csv ਹੈ ਜਿਸ ਵਿੱਚ columns: order_id,customer_email,order_date,currency,total_amount।

ਇੱਥੇ ਤਿੰਨ ਹਕੀਕਤੀ ਖਰਾਬ rows ਦੀ ਉਦਾਹਰਨ:

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

Row 2 ਵਿਚ invalid email ਅਤੇ ambiguous date format ਹੈ। Row 3 missing order_id, unsupported currency code (US ਬਜਾਏ USD), ਅਤੇ negative amount ਹੈ।

ਜੇ ਤੁਹਾਡੀ API errors ਵਾਪਸ ਕਰਦੀ ਹੈ, shape consistent ਅਤੇ specific ਰੱਖੋ। ਇੱਕ example response ਜੋ partial success support ਕਰਦਾ ਹੈ:

{
  "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]
  }
}

Partial success ਮਹੱਤਵਪੂਰਣ ਹੈ ਕਿਉਂਕਿ ਯੂਜ਼ਰਾਂ ਨੂੰ ਪੂਰੀ ਫਾਇਲ ਦੁਬਾਰਾ upload ਕਰਨ ਦੀ ਲੋੜ ਨਹੀਂ ਹੋਣੀ ਚਾਹੀਦੀ। ਇੱਕ ਸਾਦਾ retry flow ਇਹ ਹੈ: ਸਿਰਫ failed rows ਨੂੰ fix ਕਰੋ, ਇੱਕ ਛੋਟੀ CSV export ਕਰੋ ਜਿਸ ਵਿੱਚ rows 2 ਅਤੇ 3 ਹੋਣ, ਅਤੇ ਦੁਬਾਰਾ upload ਕਰੋ। ਜੇ order_id ਮੌਜੂਦ ਹੈ ਤਾਂ importer ਇਸ ਨੂੰ idempotent treat ਕਰੇ ਤਾਂ retry same records ਨੂੰ update ਕਰੇ ਨਾ ਕਿ duplicates ਬਣਾਏ।

Support ਲਈ, correlation_id ਸਭ ਤੋਂ ਤੇਜ਼ ਰਾਹ ਹੈ diagnosis ਦਾ। ਇਕ support agent ਉਸ single value ਨੂੰ ਪੁੱਛ ਕੇ import run logs ਵਿੱਚ ਸਹੀ run ਅਤੇ error report ਲੱਭ ਸਕਦਾ ਹੈ ਅਤੇ ਪੱਕਾ ਕਰ ਸਕਦਾ ਹੈ ਕਿ parser ਨੇ extra columns, wrong delimiter, ਜਾਂ unexpected encoding ਦੇਖਿਆ ਸੀ।

ਅਗਲੇ ਕਦਮ ਜੋ ਇਹ repeatable ਬਣਾਉਂਦੇ ਹਨ:

• Claude Code ਨੂੰ validation rules, example bad rows, ਅਤੇ error codes/messages generate ਕਰਨ ਲਈ ਵਰਤੋ।
• ਉਹ examples automated tests ਵਿੱਚ ਤਬਦੀਲ ਕਰੋ (fuzz tests ਸਮੇਤ) ਤਾਂ ਜੋ ਨਵੇਂ edge cases failing tests ਬਣਨ ਨਾ ਕਿ ਨਵੇਂ tickets।
• ਜੇ ਤੁਸੀਂ Koder.ai 'ਤੇ ਬਣਾਉਂਦੇ ਹੋ, planning mode ਵਿੱਚ import contract ਦਾ ਡਰਾਫਟ ਬਣਾਓ, validator ਅਤੇ tests generate ਕਰੋ, ਫਿਰ iteration ਕਰੋ ਜਦ ਤੱਕ error output CSV ਅਤੇ JSON ਦੋਹਾਂ ਲਈ consistent ਨਾ ਹੋ ਜਾਵੇ।