Claude Code ile veri içe/dışa aktarma doğruluğu: pratik adımlar

CSV ve JSON içe aktarmalarında neler yanlış gidiyor

İçe aktarmalar nadiren "kod yanlış olduğu için" başarısız olur. Gerçek veri dağınık, tutarsız ve sizin varsayımlarınızı görmemiş insanlar tarafından üretilmiş olduğu için başarısız olurlar.

CSV sorunları genellikle şekil ve formatla ilgilidir. JSON sorunları ise genellikle anlam ve tiplerle ilgilidir. Her ikisi de küçük görünen ama kafa karıştıran sonuçlar üretebilir.

Bu problemler destek taleplerinde sıkça tekrar eder:

• Gereken alanların eksik olması (email, id, country) veya birilerinin dosyayı “temizlerken” sütunların adını değiştirmesi
• Garip tarihler (01/02/03, 2024-13-01, Excel seri numaraları, karışık zaman dilimleri)
• Başka bir araç tarafından eklenen ekstra sütunlar veya beklenmeyen iç içe JSON nesneleri
• Tip sürüklenmesi ("00123" → 123, true/false → "yes"/"no")
• Çoğaltmalar ve neredeyse çoğaltmalar (aynı id iki kez, aynı kişi farklı büyük/küçük harf kullanımıyla)

Doğruluk sadece "içe aktarıldı mı" değil. Hangi çıktıların kabul edilebilir olduğuna karar vermeniz gerekir, çünkü kullanıcılar sessiz hataları yüksek sesli hatalardan daha çok fark ederler.

Çoğu ekip üç sonuçta anlaşabilir:

• Kabul edildi: tüm satırlar veya kayıtlar geçerli ve içe aktarıldı
• Reddedildi: dosya güvenilir değil diye hiçbir şey içe aktarılmadı (yanlış başlıklar, kötü kodlama, okunamayan JSON)
• Kısmi kabul: geçerli kayıtlar içe aktarılır, geçersiz olanlar net sebeplerle atılır

Köşe durumları, insanlar neyin yanlış gittiğini veya nasıl düzelteceklerini hızlıca söyleyemedikçe tekrar işe dönüşür. Yaygın bir senaryo: müşteri 5.000 satırlık bir CSV yükler, importer "Invalid format" der ve onlar rasgele düzenlemelerle üç kez yeniden dener. Bu birden fazla talebe ve sizin tarafınızda dosyayı yerel olarak yeniden üretmeye çalışan birine dönüşür.

Siklusun kısalmasını sağlayacak hedefler koyun: daha az tekrar, daha hızlı düzeltmeler, öngörülebilir sonuçlar. Kurallar yazmadan önce kısmi kabulün ne anlama geldiğine (ve izin verip vermediğinize), satır düzeyinde sorunları nasıl raporlayacağınıza ve kullanıcıların sonraki adımının ne olması gerektiğine karar verin (dosyayı düzenle, alanları eşleştir veya düzeltilmiş bir sürümü dışa aktar). Eğer validator ve testleri hızlıca üretmek için Koder.ai (koder.ai) gibi bir platform kullanıyorsanız, import kontratı yine de ürün evrildikçe davranışı tutarlı kılacaktır.

Kuralları yazmadan önce import kontratına karar verin

Tek bir doğrulama kuralı yazmadan önce ürününüz için "geçerli girdi"nin ne anlama geldiğine karar verin. Çoğu import hatası, kullanıcıların yüklediği ile sisteminizin sessizce varsaydığı şeyler arasındaki beklenti uyuşmazlığıdır.

Formatlarla başlayın ve açık olun. “CSV” virgül veya noktalı virgül anlamına gelebilir, başlık satırı olabilir veya olmayabilir, UTF-8 olabilir veya “Excel'in ürettiği her şey.” JSON için tek bir nesne kabul edip etmeyeceğinize, kayıtlar dizisi mi yoksa JSON Lines mı kabul ettiğinize karar verin. İç içe JSON kabul ediyorsanız hangi yolları okuyacağınızı ve hangilerini yok sayacağınızı tanımlayın.

Sonra alan kontratını kilitleyin. Her alan için zorunlu, isteğe bağlı veya varsayılanla isteğe bağlı olup olmadığına karar verin. Varsayılanlar kontratın parçasıdır, uygulama detayları değil. country eksikse boş mu, belirli bir ülke mi seçersiniz yoksa satırı mı reddedersiniz?

Parselama davranışı, “toleranslı” importer'ların uzun vadeli ağrı yarattığı yerdir. Baştan ne kadar katı olacağınız konusunda karar verin: boşluk kesme, harf durumunu normalleştirme ve "yes"/"true"/"1" gibi varyantları kabul etme konularında. Toleranslı olmak sorun değil, yeter ki öngörülebilir ve belgelenmiş olsun.

Çoğaltmalar da doğruluk ve güveni etkileyen bir kontrat kararıdır. Bir çoğaltmanın ne sayılacağını (aynı email, aynı external_id veya alan kombinasyonu), nerede tespit edileceğini (dosya içinde, mevcut verilerle karşılaştırma veya her ikisi) ve bu durumda ne yapacağınızı (ilkini tut, sonuncuyu tut, birleştir veya reddet) tanımlayın.

Yapıştırılabilecek bir kontrat kontrol listesi:

• Kabul edilen formatlar ve kodlama (CSV ayırıcı, JSON vs JSON Lines, iç içe destek)
• Alan kuralları (zorunlu/isteğe bağlı/varsayılanlar, izin verilen değerler)
• Normalizasyon kuralları (trim, harf durumu, tarih/sayı formatları)
• Çoğaltma tanımı ve işleme (tespit kapsamı, seçilen davranış)
• Doğrulama yeri (istemci, sunucu veya her ikisi)

Örnek: “customers” içe aktarımı. Email benzersiz anahtarsa, " [email protected] " ile "[email protected]" eşit mi sayılacak, external_id varsa eksik email kabul edilecek mi ve dosya içindeki çoğaltmalar veritabanında eşleşme olmasa bile reddedilecek mi? Bu kontrat sabitlendiğinde UI ve API arasında tutarlı davranış sağlamak çok daha kolaydır, ister Koder.ai ile ister başka yerde uygulayın.

Okunabilir ve test edilebilir kalan doğrulama kuralları

Dağınık içe aktarmalar genellikle tek bir devasa validate() fonksiyonuyla başlar. Daha temiz bir yaklaşım, net isimleri olan küçük fonksiyonlarla katmanlı kurallar kullanmaktır. Bu değişiklikleri gözden geçirmeyi ve test yazmayı kolaylaştırır.

Alan düzeyi kurallarla başlayın: tek bir değerin kendi başına geçip geçemeyeceğine bakar (tip, aralık, uzunluk, izin verilen değerler, regex). Bunları sıkıcı ve öngörülebilir tutun. Örnekler: email basit bir email deseniyle eşleşir, age 0 ile 120 arasında bir tamsayıdır, status active|paused|deleted değerlerinden biridir.

İhtiyaç duyulduğunda alanlar arası kurallar ekleyin. Bu kontroller birden fazla alana bağlıdır ve hatalar burada gizlenir. Klasik örnekler: startDate endDate'den önce olmalı veya total subtotal + tax - discount eşit olmalı. Bu kuralları sadece "kayıt geçersiz" demek yerine belirli alanları işaret edecek şekilde yazın.

Kayıt düzeyi kuralları ile dosya düzeyi kurallarını ayırın. Kayıt düzeyi satır (CSV) veya nesne (JSON) başına kontrol yapar. Dosya düzeyi kural tüm yüklemeyi kontrol eder: gerekli başlıklar var mı, benzersiz anahtar satırlar arasında tekrarlanıyor mu, kolon sayısı beklentiyle eşleşiyor mu veya dosya desteklenen bir versiyon bildiriyor mu.

Normalizasyon açık olmalı, “sihirli” olmamalı. Doğrulamadan önce neyi normalleştirdiğinizi kararlaştırın ve belgelendirin. Yaygın örnekler: boşlukları kesmek, Unicode normalizasyonu (görsel olarak aynı karakterlerin aynı şekilde karşılaştırılması), telefon numaralarını tek bir saklama formatına dönüştürme.

Okunabilir kalan bir yapı:

• Normalize: ham girdiyi kanonik bir şekle dönüştürün.
• Alanları doğrulayın: alan başına küçük, yeniden kullanılabilir kontroller.
• İlişkileri doğrulayın: alanlar arası kontroller, net hedeflerle.
• Dosya kurallarını doğrulayın: başlıklar, çoğaltmalar ve versiyon desteği.
• Her katmanı test edin: her kural için birim testleri ve birkaç uçtan uca örnek.

Kurallarınızı versiyonlayın. Dosyaya veya API isteğine schemaVersion (veya import "profile") koyun. "Geçerli"nin ne anlama geldiğini değiştirdiğinizde, eski export'ları eski versiyonla yeniden içe aktarabilirsiniz. Bu tek tercih birçok “dün çalışıyordu” biletini önler.

İnsanların işlem yapabileceği bir hata raporlama formatı tasarlayın

İyi bir importer yardımcı şekilde başarısız olur. Muğlak hatalar rastgele tekrar denemelere ve önlenebilir destek işine yol açar. Açık bir hata formatı kullanıcıların dosyayı hızlıca düzeltmesine yardımcı olur ve doğrulamayı bozmadan iyileştirmenizi sağlar.

CSV ve JSON arasında tutarlı bir hata nesne şekliyle başlayın. Claude Code kullanarak bir şema ve birkaç gerçekçi örnek önerebilir, sonra bunu import kontratının parçası olarak kilitleyebilirsiniz.

Sabit bir hata nesnesi

Her hatayı değişmeyen alanları olan küçük bir kayıt gibi ele alın. Mesaj gelişebilir, ama kod ve konum sabit kalmalı.

• code: REQUIRED_MISSING veya INVALID_DATE gibi kısa, sabit bir tanımlayıcı
• message: UI için insan-dostu bir cümle
• path: sorunun olduğu yer (JSON pointer gibi /customer/email veya email gibi bir sütun adı)
• row veya line: CSV için 1 tabanlı satır numarası (ve isteğe bağlı olarak orijinal satır)
• severity: en az error ve warning

Hataları eyleme geçirilebilir yapın. Beklediğiniz ile gerçekte gördüğünüzü, mümkünse kabul edecek bir örnekle birlikte verin. Örneğin: beklenen YYYY-MM-DD, alınan 03/12/24.

UI ve hata ayıklama için gruplayama

Düz bir liste döndürseniz bile, hataları satır ve alan bazında gruplayacak kadar veri ekleyin. Birçok UI "12. satırda 3 sorun var" göstermek ister ve her sütunu vurgular. Destek ekipleri ise desenleri görmek ister (örneğin her satır country eksik).

Kompakt bir yanıt şöyle olabilir:

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

Hata kodlarını lokalize etmeden destekleyecek şekilde planlayın. code dil-bağımsız ve dayanıklı olsun; message değiştirilebilir metin olarak ele alınsın. Daha sonra messageKey veya çevrilmiş mesajlar ekleseniz bile, eski istemciler aynı kodlara güvenerek filtreleme, gruplama ve analiz yapabilir.

Başarı ve hata durumunda import API hangi bilgileri dönmeli

“Gizemli import”ları önlemek için API yanıtınız iki soruyu yanıtlamalı: ne oldu ve kullanıcı bir sonraki adımda ne yapmalı.

Her zaman açık bir import özeti dönün

Hatalar olsa bile tutarlı bir özet döndürün ki UI ve destek araçları her importu aynı şekilde işleyebilsin.

İçermesi gerekenler:

• created, updated, skipped, failed sayıları
• totalRows (veya JSON için totalRecords)
• mode (örneğin: "createOnly", "upsert" veya "updateOnly")
• startedAt ve finishedAt zaman damgaları
• destek için bir correlationId

Bu correlationId çok işe yarar. "İçe aktarılmadı" diyen bir kullanıcı geldiğinde, tam çalıştırmayı ve hata raporunu tahmin etmeden bulabilirsiniz.

Eyleme geçirilebilir hatalar ve tam raporu getirme yolu

10.000 satırlık hata listelemesini yanıt olarak dökmeyin. Küçük bir örnek döndürün (örneğin 20) ve tam raporu almak için ayrı bir yol sağlayın.

Her hatayı spesifik ve sabit yapın:

• konum: satır numarası (CSV) veya JSON pointer-benzeri yol (JSON)
• alan adı
• hata kodu (makine tarafından okunabilir)
• mesaj (insan tarafından okunabilir)
• reddedilen değer (gizli verilerle dikkatli olun)

Örnek yanıt (bazı satır hatalarıyla tamamlanmış başarı):

{
  "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 alanına dikkat edin. Minimal bir başarı payload'u bile ürünü bir sonraki adıma taşımalı: inceleme ekranı göster, yeniden deneme sun veya içe aktarılan koleksiyonu aç.

Tekrarlayan yüklemeler iki kez oluşturmasın diye idempotency tanımlayın

İnsanlar yeniden dener. Ağlar kopar. Aynı dosya iki kez yüklendiğinde öngörülebilir sonuçlar isteyeceksiniz.

Idempotency hakkında açık olun: bir idempotencyKey kabul edin (veya dosya hash'i hesaplayın) ve istek tekrar ise mevcut importId'yi döndürün. Modunuz upsert ise eşleme kuralını tanımlayın (örneğin email benzersiz anahtar). Create-only ise duplicate'lar için "created" yerine "skipped" döndürün.

Hatalar için doğru statüleri kullanın, ama şekli sabit tutun

Tüm istek geçersizse (kötü auth, yanlış content type, okunamayan dosya) hızlıca reddedin ve status: "rejected" ile kısa bir hata listesi döndürün. Dosya geçerliyse ama satır düzeyinde sorun varsa, bunu failed > 0 ile tamamlanmış bir iş olarak işleyin ki kullanıcılar özet kaybolmadan hataları düzeltsin ve yeniden yüklesin.

Claude Code'u kurallar ve örnekler üretmek için nasıl kullanmalısınız

Yapıcı bir alışkanlık: modeli sözlü açıklama yerine yapısal formatta kontratı yazması için kullanın. "Yardımcı paragraflar" genellikle trim kuralları, varsayılan değerler ve boş hücrenin "eksik" mi yoksa "boş" mu olduğu gibi detayları atlar.

İncelemesi hızlı ve geliştirici tarafından koda dönüştürülebilir bir tablo istemek için bir prompt kullanın. Her alanın kuralını, geçme/başarısız örneklerini ve belirsiz olan her şey için açık notu isteyin.

Örnek prompt:

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).

İlk taslaktan sonra her kural için bir pozitif ve bir negatif örnek isteyin. Bu, boş stringler, sadece boşluktan oluşan değerler, eksik sütunlar, null vs "null", çok büyük tam sayılar, bilimsel gösterim, duplicate ID'ler ve ekstra JSON alanları gibi köşe durumlarının kapsanmasını zorlar.

Somut bir senaryo için "customers" importunu düşünün: email zorunlu, phone isteğe bağlı ve signup_date eksikse bugünün tarihi varsayılan olarak atanıyor. Model, şu anda "signup_date zorunlu" derseniz çelişki olduğunu işaretlemeli. import_customers_missing_email_returns_row_error gibi test isimleri önermeli ve döndürülecek hata kodu ile mesaj şeklini belirtmelidir.

Uygulamaya geçmeden önce bir tur daha isteyin: modelden kuralları bir kontrol listesi olarak tekrar etmesini ve varsayılanlar, zorunlu alanlar ve normalizasyon arasında çakışma olabileceği yerleri belirtmesini isteyin. Bu inceleme adımı birçok bilet değeri davranışı yakalar.

Adım adım: CSV ve JSON importları için fuzz testleri

Fuzz testleri "tuhaf dosyaların" destek biletine dönüşmesini engeller. Küçük bir set gerçekçi iyi dosyadan başlayın, sonra binlerce hafif bozuk varyasyon üretin ve importer'ın güvenli ve net şekilde tepki verdiğinden emin olun.

Seed set oluşturun, sonra mutasyon yapın

Gerçek kullanımı temsil eden birkaç geçerli örnekle başlayın: en küçük geçerli dosya, tipik bir dosya ve büyük bir dosya. JSON için bir nesne, çoklu nesneler ve iç içe yapılardan örnekler ekleyin.

Sonra tek bir şeyi değiştiren otomatik bir mutatör ekleyin. Rastgele tohumu (seed) loglayarak üretilen hataları yeniden oynatılabilir kılın.

Fuzz boyutları (dimensions) çoğu gerçek dünya problemini yakalar:

• Kodlama sorunları: BOM'lu UTF-8, geçersiz byte dizileri, karışık normalizasyon
• Yapı sorunları: eksik başlıklar, ekstra sütunlar/alanlar, yanlış ayırıcı, sondaki virgüller
• Tırnaklama ve yeni satırlar: kapanmamış tırnaklar, gömülü yeni satırlar, CRLF vs LF, tutarsız kaçış
• Tip sınırları: çok büyük tamsayılar, JSON'da NaN/Infinity, boş string vs null, boşluk dolgu
• Boyut ve sınırlar: çok uzun alanlar, çok fazla satır, tekrar eden anahtarlar, derin iç içe diziler

Sadece sözdizimine takılmayın. Anlamsal fuzz da ekleyin: benzer alanları yer değiştirin (email vs username), uç tarihleri, duplicate ID'ler, negatif adetler veya enum ihlali değerler.

"Geçmek" ne anlama geliyor belirtin ve kilitleyin

Fuzz testleri yalnızca geçme kriterleri sıkıysa işe yarar. Importer hiçbir zaman çökme veya asla donma yapmamalı ve hatalar tutarlı ve eyleme geçirilebilir olmalı.

Pratik geçiş kuralları:

• Çökme, zaman aşımı veya sınır dışı bellek kullanımı yok
• Satır/alan işaretçileri ile açık hatalar (CSV için) veya JSON path'leri
• Aynı hata için tekrar çalıştırıldığında stabil hata kodları
• Kısmi yazma yalnızca açıkça destekleniyorsa olmalı
• Başarılı importlar biçimsel farklılıklardan (boşluk gibi) etkilenmemeli

Bu testleri CI'da her değişiklikte çalıştırın. Hata bulduğunuzda, tam dosyayı fixture olarak kaydedin ve regresyon testi ekleyin ki geri dönmesin.

Claude Code kullanıyorsanız modelden seed fixture'lar, mutasyon planı ve beklenen hata çıktıları üretmesini isteyin. Kuralları siz seçersiniz, ama geniş bir test yüzeyi hızlıca elde edersiniz, özellikle CSV tırnaklama ve JSON köşe durumları için.

Tekrarlanan destek biletlerine neden olan yaygın tuzaklar

Çoğu import bileti belirsiz kurallar ve işe yaramayan geri bildirimten gelir.

Yaygın tuzaklardan biri dokümante edilmemiş “elinden gelenin en iyisi” parse etmektir. Importer boşlukları sessizce kesiyorsa, hem virgül hem noktalı virgül kabul ediyorsa veya tarih formatını tahmin ediyorsa, kullanıcılar bu tahminlere göre iş akışları kurar. Küçük bir değişiklik veya farklı dosya üreteci her şeyi bozabilir. Davranışı seçin, belgeleyin ve test edin.

Bir diğer tekrar eden sorun genel hata mesajıdır. "Invalid CSV" veya "Bad request" kullanıcıyı tahmin etmeye zorlar. Aynı dosyayı beş kere yüklerler ve destek yine dosyayı ister. Hatalar bir satırı, alanı, net sebebi ve sabit bir kodu işaret etmeli.

Tek bir kötü satır için tüm dosyayı reddetmek de sıkıntı yaratır. Bazen bu doğrudur (örneğin finansal importlarda kısmi veri tehlikelidir). Birçok iş importu devam edebilir ve bir özet rapor edebilir; yeter ki sıkı mod vs kısmi import gibi açık bir seçenek sunun.

Metin kodlama problemleri inatçı biletler yaratır. Varsayılan olarak UTF-8 doğru tercihtir, ancak gerçek CSV'ler genellikle BOM, kıvırcık tırnaklar veya elektronik tablodan kopyalanmış görünmez boşluklar içerir. Bunları tutarlı şekilde ele alın ve ne tespit ettiğinizi rapor edin ki kullanıcı dışa aktarma ayarlarını düzeltebilsin.

Son olarak, sürümler arasında hata kodlarını değiştirmek istemeyin. İfadeyi geliştirmek istiyorsanız bunu yapın ama kodları ve anlamları sabit tutun. Gerçekten gerektiğinde versiyonlayın.

Korunmaya değer tuzaklar:

• Zaman içinde değişen ve belgelenmemiş "elinden gelenin en iyisi" parse davranışları
• Satır/alan işaretçisi ve sabit hata kodu olmadan verilen genel hatalar
• Sıkı vs kısmi seçenek olmadan tümüyle reddetme
• UTF-8, BOM ve görünmez karakterlerin tutarsız işlenmesi
• Sürüm değişikliklerinde hata kodlarının değiştirilmesi

Örnek: bir müşteri Excel'den CSV dışa aktarır; Excel BOM ekler ve tarihleri 03/04/2026 olarak formatlar. Importer MM/DD tahmini yaparsa ama müşteri DD/MM bekliyorsa sorun yaşanır. Hata raporunuz algılanan formatı, tam alanı ve önerilen düzeltmeyi içeriyorsa kullanıcı geri dönüş-s-e gerek kalmadan düzeltebilir.

Bir importer göndermeden önce hızlı kontrol listesi

Çoğu import problemi, kullanıcıların dosyanın ne anlama geldiğini düşündüğü ile sisteminizin ne kabul ettiği arasındaki küçük uyumsuzluklardır. Bunu bir sürüm kapısı gibi ele alın.

• Başlıklar ve alan adları: gerekli kolonların varlığını doğrulayın, adların kurallara uyduğunu kontrol edin ve çoğaltmaları reddedin. Fazla kolonlarla ne yapılacağına karar verin (yoksay, uyar, hata) ve tutarlı tutun.
• Veri tipleri ve formatlar: tamsayı vs ondalık, boolean'lar (true/false, 0/1, yes/no), tarihler ve zaman damgaları (zaman dilimi kuralları) nasıl parse edileceğini kilitleyin. Her alan için tercihen tek bir kabul edilen format belirleyin.
• Null ve eksik değerler: her alan için boş string'in ne anlama geldiğini tanımlayın. Eksik alan, explicit null ve boş metini ayırın.
• Boyut ve güvenlik sınırları: dosya boyutu, maksimum satır sayısı ve maksimum alan uzunluğu için sınırlar koyun. Erken başarısız olup net mesaj verin.
• Deterministik hatalar: aynı kötü girdi aynı hata kodu ve mesaj şeklini üretmeli.

Pratik test: kasıtlı olarak dağınık bir dosya kullanın. Örnek: başlık iki kez görünür (iki "email" kolonu), bir boolean alan "Y" kullanıyor ve tarih "03/04/05" olarak var. Importer tahmin yapmamalı; ya belgelenmiş eşleme kuralını uygulamalı ya da spesifik bir hata ile reddetmelidir.

Takımların sıklıkla atladığı iki kontrol:

Birincisi, importerin hataları düzeltmek için yeterli konum bilgisini rapor edip etmediğini doğrulayın. "Invalid date" eyleme geçirilebilir değildir. "42. satır, start_date sütunu: beklenen YYYY-MM-DD, alınan 03/04/05" eyleme geçirilebilirdir.

İkincisi, aynı geçersiz dosyayı iki kez çalıştırın ve sonuçları karşılaştırın. Hata sırası değişiyorsa, kodlar değişiyorsa veya satır numaraları kayıyorsa kullanıcı güveni azalır. Deterministik davranış sıkıcıdır ve amaç da budur.

Gerçekçi bir örnek senaryo ve sonraki adımlar

Gerçek dünyada sık rastlanan bir import, eski bir sistemden dışa aktarılan ve kullanıcı tarafından Excel'de düzenlenen sipariş dosyasıdır. Çoğu bilet, importer'ın veriyi sessizce "düzeltmesi" veya hata mesajının neyi değiştirmeleri gerektiğini söylememesinden kaynaklanır.

Bir dosya düşünün: orders.csv kolonları: order_id,customer_email,order_date,currency,total_amount.

Kullanıcının göreceği üç kötü satır örneği:

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. satırda geçersiz email ve belirsiz tarih formatı var. 3. satırda order_id eksik, desteklenmeyen para kodu (US yerine USD) ve negatif tutar var.

API'niz hataları döndürüyor ise, şekli tutarlı ve spesifik tutun. Aşağıda kısmi başarıyı destekleyen bir örnek yanıt:

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

Kısmi başarı önemlidir: kullanıcı tüm dosyayı yeniden yüklemek zorunda kalmamalı. Basit bir yeniden deneme akışı: yalnızca başarısız satırları düzeltin, 2 ve 3 numaralı satırları içeren küçük bir CSV dışa aktarın ve yeniden yükleyin. Importer order_id mevcutsa bunu idempotent olarak ele almalı, böylece yeniden deneme aynı kayıtları günceller, tekrar yaratmaz.

Destek için correlation_id teşhis yolunun en hızlı yoludur. Destek görevlisi sadece bu değeri isteyerek çalıştırmayı günlüklerde bulabilir ve parser'ın ekstra kolonlar, yanlış ayırıcı veya beklenmeyen kodlama görüp görmediğini doğrulayabilir.

Tekrarlanabilir kılmak için sonraki adımlar:

• Claude Code'u kullanarak doğrulama kuralları, kötü satır örnekleri ve standartlaştırmak istediğiniz hata kodları/mesajlarını üretin.
• Bu örnekleri otomatik testlere dönüştürün (fuzz testleri dahil) ki yeni köşe durumları başarısız testler olsun, yeni biletler değil.
• Koder.ai ile inşa ediyorsanız planning modunu kullanarak import kontratını taslaklayın, doğrulayıcı ve testleri üretin ve hata çıktısı CSV ile JSON arasında tutarlı kalana dek yineleyin.