CSV İthalatlarını 10,000 Dağınık Satırı Bozmadan Nasıl Yeniden Oluşturdum

CSV importer geliştirdiyseniz, bunun basit göründüğünü bilirsiniz – ta ki gerçek kullanıcılar karmaşık verilerle geldiğinde. Belirsiz tarihler, tekrar eden satırlar, kısmi güncellemeler, “Acme Corp” isminin üç farklı şekilde yazılması gibi sorunlarla karşılaşırsınız. Temel parse-validate-insert süreci hızlıca çöker.

Relaticle, açık kaynaklı bir CRM oluşturuyorum ve V3 için import sistemini, katı bir iş akışı, aşamalı işleme ve açık hata yönetimi ile özel bir modül olarak tamamen yeniden inşa ettim. İşte arkasındaki mimari ve ticari anlaşmalar.

V3 için Neden İmportları Yeniden Yapılandırdım

Takımların genelde başladığı eski desen oldukça basit:

1. CSV’yi Parse Et
2. Hafızada Doğrula
3. Doğrudan Ekle/Güncelle

Bu, küçük ve temiz dosyalar için çalışır. Ancak birisi, “Acme Corp”un üç farklı şekilde geçtiği, tarihin MM/DD ve DD/MM karıştığı ve yarım satırların mevcut kayıtları güncellemesi gereken bir CSV yüklerse çöker.

Gerçekten ihtiyaç duyduğunuz şey:

• Mevcut kayıtlarla eşleşme, yanlış pozitif olmadan
• İlişkilerin güvenli bir şekilde işlenmesi (şirket, iletişim, atama bağlantıları)
• Veritabanına herhangi bir şey girmeden önce değer düzeyinde düzeltmeler
• Devam edilebilir durum ve güvenilir ilerleme takibi
• Kullanıcıların harekete geçebileceği net hata raporlaması

V3 için, importların bir iş akışı gibi davranmasını istedim; tek seferlik bir betik olmasın.

Ürün Akışı: 4 Adım, Bir Durum Makinesi

Yeni Import Wizard, dört belirgin adıma dayanıyor:

1. CSV’yi Yükle
2. Sütunları Eşle
3. Değerleri Gözden Geçir
4. Önizleme ve İçe Aktar

Her adım, bir import durumu (uploading, mapping, reviewing, previewing, ardından importing/completed/failed) ile eşleniyor, böylece UI ve arka uç senkronize kalıyor.

Bu, bir UI detayı gibi görünebilir, ancak bu bir güvenilirlik kararidir. Bağlamı geri yükleyebilir, geçersiz geçişleri engelleyebilir ve hatalar hakkında temiz bir şekilde mantık yürütebilirsiniz.

Temel Karar: Veriyi Ana Tablo Dışında Aşamalandır

V3’ün en önemli kararı, cada import için ayrılmış bir sahneleme depolaması içermektir.

Yükleme/gözden geçirme sırasında doğrudan CRM tablolarına yazmak yerine, her importun kendine ait bir SQLite destekli depolama alanı var (storage/app/imports//data.sqlite). Satırlar, şu gibi meta verilerle aşamalı olarak depolanır:

• raw_data
• validation
• corrections
• skipped
• match_action
• matched_id
• relationships
• processed

Bu ayrım size üç şey kazandırır:

1. Kullanıcılar, herhangi bir şey üretime girmeden önce verileri gözden geçirir ve düzeltir.
2. Çeşitleme ve doğrulama tekrarlı çalışır, veride kayma olmaz.
3. Temizlik zahmetsizdir: import depolama dizinini silebilirsiniz.

Birisi 10.000 Satır Yüklediğinde Ne Olur?

Yükleme, sert sınırlar getirir:

• Max dosya boyutu: 10MB
• Max satır sayısı: 10.000
• Parça ekleme boyutu: 500 satır
• Başlık temizliği ve tekrar eden başlık tespiti

Satırlar CSV’den akıtılır ve aşama deposuna parçalar halinde eklenir, tek bir büyük bellek yapısına yüklenmez.

Pratik etkisi: yüklemeler, büyük dosyalarda bile stabil ve hızlı kalır, hata durumları açıktır (boş dosya, tekrar eden başlıklar, çok fazla satır, kötü format).

Akıllı Eşleme: Bir Kaçış Yolu ile Otomasyon

Eşleme üç katmandan oluşur:

1. Başlığa dayalı tahminler (takma adlar gibi company_name, contact_email, vb.)
2. Varlık bağlantı eşlemesi (şirket, iletişim, atama, çok biçimli bağlantılar)
3. Veri türü çıkarımı eşlenmemiş sütunlar için

Tür çıkarımı, statik bir sabit harita yerine özel alan sistemi tarafından yönlendirilir. Bu, her ekip/varlık için gerçek alan yapılandırmasıyla uyumlu davranışı korur.

Kullanıcılar, herhangi bir eşleştirilebilir alanı (ID, e-posta veya alan gibi) atlarsa, sihirbaz, tekrar eden kayıtlar oluşturabileceklerini uyarır. Her şey yolundaymış gibi sessizce devam etmez.

Gözden Geçirme: Çoğu İmportrun Durdurulduğu Yer, V3 Devam Ediyor

Gözden Geçirme adımına girdiğinizde:

• Her eşlenmiş sütun için bir doğrulama işi gönderilir
• Ayrı bir eşleşme çözümleme işi gelir

Bu, kullanıcıların sonuçlarla etkileşime geçmeye başlamalarını sağlar; merkezde bir doğrulama duvarı beklemek yerine.

Kullanıcılar:

• Geçersiz değerleri düzeltip bu düzeltmeleri tüm eşleşen ham değerlere uygulayabilirler
• Problemli değerleri atlayabilirler
• Belirsizlik durumunda tarih/sayı formatlarını ayarlayabilirler

Her şey aşamalı JSON alanlarında saklanır, böylece her düzeltme belirleyici ve tekrar edilebilir.

Eşleme Modeli: Oluştur, Güncelle veya Atlama

Çözücü, her satırı üç eylemden biri ile işaretler:

Davranış, eşlenmiş eşleşme alanlarına ve stratejilerine bağlıdır:

• Eşleşme alanları, eşleşmeyen satırları atlayabilir
• Oluştur veya eşleştir alanları, eşleşmeyen satırları oluşturabilir
• İsim tabanlı eşleştirme, “yalnızca oluştur” niyetiyle, güvensiz varsayımlardan kaçınmak için kullanılabilir

Bu, eşleşme politikasını açık hale getirir; rastgele koşulların altında gömülmez.

Yürütme: Satırlar Hatalı Olursa Ne Olur?

İçe aktarma, tekrarlar ve geri dönüş ile birlikte, satırları parçalar halinde işleyen kuyruğa alınmış bir iş olarak çalışır.

Temel davranışlar:

• Yalnızca işlenmemiş satırlar işlenir
• Satır düzeyinde işleme, tüm import durdurulmadan başarı/başarısızlık işaretleri koyar
• Mevcut kayıtlar, güncelleme parçaları için önceden yüklenir
• Çoklu seçim alan değerleri güncelleme sırasında birleşir
• Başarısız satırlar hata mesajları ile yakalanır ve CSV olarak indirilebilir

Bu tasarımda beğendiğim bir detay: iç-dış deduplikasyon. Bir satır başlangıçta create olarak işaretlenmiş olsa bile, aynı dosyada daha önce o mantıksal kaydı oluşturan bir satır varsa, artık update olarak yükseltilebilir. Bu, tek bir import çalışmasında tekrar eden kayıtların oluşmasını engeller.

Operasyonel Güçlendirme

Mutlu yolun ötesinde, pratik operasyon desteği ekledim:

• İki kez aynı importu başlatmayı önlemek için geçiş kilidi
• Oluşturulan/güncellenen/atlanan/başarısız sayıları gösteren import geçmişi görünümü
• Başarısız satırların imzalı indirilmesi
• Abone olan ve sonlanan importlar için temizlik komutu

Temizlik stratejisi, özellikle üretimde kullanışlıdır: tamamlanmış/başarısız depolar kısa bir bekleme süresinden sonra kaldırılır ve bekleyen eski importlar temizlenir.

Relaticle V3 Hakkında Ne Söylüyor

Import Wizard, daha geniş V3 mimari ilkelerini yansıtır:

1. Tek seferlik betikler yerine iş akışı
2. Doğrudan değiştirme yerine aşamalı işleme
3. Maliyetli işler için asenkron görevler
4. Takım alanında güvenlik varsayılan olarak
5. İçe aktarıcı sözleşmeleri ve varlık bağlantı soyutlamaları aracılığıyla genişletilebilirlik

Modüler bir monolit olarak devam ediyor, ancak daha net sınırlar ve daha iyi operasyonel davranış ile.

Eğer Bir İmporter Geliştiriyorsanız: Pratik Kontrol Listem

• ✅ Nihai yazımlardan sahnelenmeyi ayırın
• ✅ Eşleşme politikasını açık yapın (ve kullanıcıya görünür)
• ✅ Taahhüt edilmeden önce değer düzeyinde düzeltmeleri destekleyin
• ✅ Satır eylemini create/update/skip olarak modelleyin
• ✅ İndirilebilir başarısız satır raporu tutun
• ✅ Başından itibaren temizlik ekleyin
• ✅ Her aşamayı test edin (UI + işler + doğrulayıcılar + eşleyiciler)

Importlar, güvenilirliğin güveni artırdığı bir ürün yüzeyidir. Kullanıcılar, bir kez “gizemli importlar” nedeniyle yanılırsa, sisteme güvenlerini kaybeder.

Relaticle V3 için hedef basitti: üretimde importları sıkıcı hale getirmek, veri karmaşık olsa bile.