Kayıt defteri ayrıştırma ve otomasyon

TL; DR

Güvenilir "doğrulama" otomasyonu üç sütuna dayanır: deterministik yutma (güvenli teslimat, idempotans, bütünlük kontrolü), normalleştirilmiş veri katmanı (tek şema, eşleşen anahtarlar, standart zaman birimleri/para birimleri/işaretler) ve sıkı kalite disiplini (validasyonlar, toleranslar, DLQ, uyarılar, otomatik düzeltmeler). Amaç, rengarenk dosyaları/web kitaplarını, kullanılabilirlik konusunda SLA'larla uzlaşma, raporlama ve BI için kararlı tablolara dönüştürmektir.

1) Kaynak ve format manzarası

1. 1 Kaynaklar

PSP/alıcılar/toplayıcılar: işlemler, setler, komisyonlar, anlaşmazlıklar.
Bankalar: ekstreler MT940, ISO 20022 CAMT. 052/053/054, PAIN ödemeleri. 001/002.
AWS/cüzdanlar/ödemeler (OCT/RTP/SEPA): ödeme kayıtları, iadeler.
Kripto-özel/borsalar: zincir içi işlemler, dönüşüm/komisyon raporları.
Vergiler/Devlet portalları: CSV/XLSX/PDF, bazen komut dosyası tarayıcı aracılığıyla.

1. 2 Formatlar

CSV/TSV (değişken ayırıcılar, lokaller, kodlamalar).
XLSX (çok sayfalı, birleştirilmiş hücreler).
XML (ISO 20022 CAMT/PAIN, XSD özel şemaları).
SWIFT MT940/942 (konum alanları).
JSON-API/NDJSON (artımlı yüklemeler, imleçler).
PDF (tablo - ayrıştırıcı; Tarama - OCR).
ZIP/TAR. GZ (çoklu dosya yığınları).

2) Yutma boru hattı mimarisi

1. Açılış: güvenli dosya kabulü (SFTP/FTPS/WebDAV/API/webhooks) - hemen sağlama toplamı düşünün, hammaddeleri her zaman saklayın.

2. Ham: tarihlere/sağlayıcılara/kasaplara göre düzen, versiyonlarla depolama.

3. Normalleştir: ayrıştırma - birleştirici türler/birimler - normalleştirilmiş tablolar.

4. Doğrulanmış: doğrulama sonrası (kalite kuralları) - bayraklar, DLQ.

5. Eşleştirilmiş: Dahili olaylara/bankaya eşleme.

6. Hizmet/BI: uzlaşma/finansal/işlemler için vitrinler.

• Yutma idempotency: '(sağlayıcı, file_name, file_size, checksum, statement_date)' - benzersiz bir anahtar.
• Reruns/Retrays: Dosyanın yeniden çalıştırılması kopyalar oluşturmaz.
• DLQ (ölü harf kuyruğu): tüm tanınmayan/ihlal eden kurallar - izole edilmiş bir kuyruğa.
• Sürüm oluşturma: aynı gün için yeni bir dosya - bir öncekine bağlantı içeren yeni bir sürüm.

3) Teslimat ve sırların güvenliği

Kanallar: Sınırlı anahtarlı SFTP; FTPS - sadece sıkı TLS ile; API - OAuth2/short TTL belirteçleri.
İçerik şifreleme: Dosyaları indirirken PGP/GPG; E-posta gelen kutuları için S/MIME (kullanılıyorsa).
Bütünlük kontrolü: SHA-256/512 sağlama toplamı, hash in manifest ile karşılaştırma.
Sırlar: Vault/KMS'de saklama, döndürme, yapılandırma dosyalarında/günlüklerinde yasaklanmıştır.
Erişimler: RBAC +'en az ayrıcalık "ilkesi, ayrı hizmet hesapları.

4) Normalleştirme ve veri şeması

4. 1 Evrensel kurallar

Zaman: ISO-8601 her zaman UTC; Yerleşim tarihleri için, TZ olmadan 'DATE'.
Miktarlar: 'DECIMAL (p, s)' küçük birimler + bireysel 'ölçek'; İşaret: makbuz/masraf kesinlikle sözlüğe göre.
Para birimleri: ISO-4217, 'fx _ src'ile sabit oranlı tablo.
Locali: autodetect yasağı - ayırıcıların/ondalık noktanın/binlerin açık bir şekilde ayarlanması.
Kodlamalar: UTF-8 girişi; diğerleri - bir günlük ile dönüşüm.

4. 2 Normalleştirilmiş "düz" katman (örnek)

json
{
"provider": "Acquirer_A",
"source_kind": "PSP_TX    PSP_SETTLEMENT    BANK    WALLET    CRYPTO",
"kind": "AUTH    CAPTURE    REFUND    PAYOUT    FEE    SETTLEMENT    CHARGEBACK",
"payment_id": "pay_123",        // ваше
"provider_txid": "psp_abc_789",    // внешнее
"merchant_ref": "mr_456",
"sequence": 0,             // partial/refund line index
"amount_minor": 100000,        // 1000.00
"currency": "EUR",
"fee_minor": 120,           // 1.20
"fx_rate": 1.0000,
"fx_src": "PSP    ECB    BANK",
"event_ts": "2025-11-03T12:00:00Z",
"value_date": "2025-11-05",
"account": "PSP_MERCHANT_CARD_A",
"bin": "425000",
"last4": "1234",
"status": "APPROVED    CAPTURED    SUCCESS    FAILED    SETTLED",
"file_id": "ing_20251103_001",
"row_hash": "sha256(raw_row)"
}

5) Formata göre Ayrıştırıcılar: Hileler ve Tırmık

5. 1 CSV/TSV

Açıkça 'sınırlayıcı', 'quotechar', 'escapechar', 'kodlama'yı belirtin.

5. 2 XLSX

Sayfa beyaz listesine göre okuma; Otomatik Birleştirme Engelleme - Birleştirilmiş hücreleri düzleştirir.
Formüllerin değerlere dönüştürülmesi; Excel - UTC tarihleri açık TZ ile.

5. 3 XML (ISO 20022 CAMT/PAIN)

XSD tarafından doğrulama; XPath kimlik eşlemesi ('<Ntry>', '<TxDtls>', '<Amt>', '<CdtDbtInd>').
Kredi/borç normalizasyonu - işareti; Çoklu '<Chrgs>', '<RmtInf>' desteği.

5. 4 MT940

Ayrıştırma etiketleri ': 61:', ': 86:'; Ulusal uzantılara destek; Konum alanları - dilimleme kuralları.
Birkaç ': 61:'nin tek bir grupta birleştirilmesi.

5. 5 JSON/NDJSON/API

5. 6 PDF/OCR

İlk olarak, tablo ayrıştırma denemesi (tablo dedektörü), ancak daha sonra beyaz liste karakterleriyle OCR (Tesseract).
Doğrulama sonrası: miktarlar, kontrol toplamları, satır sayısının uzlaştırılması.

5. 7 Arşivler/Partiler

Yapı koruma ile ambalajın açılması; Her dosya - ayrı bir 'file _ id'; Tezahür, tüm parçaların kontrolü.

6) Veri kalitesi doğrulamaları ve kuralları

• Şema - Gerekli tüm alanlar mevcuttur.
• Türler: miktarlar - sayısal, tarihler - ayrıştırma.
• Checksums/Totals - Satırların toplamı = Dosyadaki toplam (varsa).
• Aralıklar: makul bir pencerede tarih; sum> 0 (veya izin verilen negatif sözlüğüne göre).
• Benzersizlik: '(provider, provider_txid, sequence)' normalize edilmiş olarak çoğaltılmaz.
• Toleranslara 'miktar/fx/zaman' tutarsızlıklarına izin verilir.

Sonuç: 'VALID', 'VALID _ WITH _ WARNINGS', 'INVALID _ DLQ (reason_code)'.

7) Kimlik ve veri tekilleştirme

Yutma anahtarı: '(provider, file_name, filesize, checksum, statement_date)' - tek bir 'file _ id'.
Satır düzeyi idem: 'row _ hash = sha256 (normalized_row_compact)'; Yeniden yükleme yeni kayıtlar oluşturmaz.
Webhooks/API: 'idempotency _ key' sağlayıcı + etiketleriniz ('exec _ id'), mağaza TTL.
Sağlayıcının kopyaları: 'provider _ txid' + 'sequence'ile dedup, tutarsızlık durumunda - DLQ_DUPLICATE.

8) Orkestrasyon ve programlar

Оркестратор: AirFlow/Dagster (DAG: 'Getir - şifreyi çöz - ayrıştırın - normalleştirin - doğrula - doğrula - yayınla - eşleştir').
SLA/SLO: 'Time-to-Availability (TtA)' dosya oluşumundan 'normalized = READY' değerine.
Retrai: üstel geri dönüş + jitter; teşebbüs sınırları; açık statüler.
Eşzamanlılık ve izolasyon: Ağır OCR/ayrıştırma XLSX - CPU/RAM sınırı olan ayrı bir havuzda/işçide.
DLQ-replay: kuralları/eşlemeleri güncellerken periyodik yeniden işleme.

9) Gözlemlenebilirlik ve uyarılar

• Yutma Başarısı %, Ayrıştırma Başarısı % kaynağa göre.
• TtA p50/p95, Verim (çizgi/dak).
• DLQ Oranı и Yaşlanma DLQ p50/p95.
• Şema Sürüklenme Olayları.
• Duplicate Rate по 'provider _ txid'.

• 'TtA p95> SLA' - P1.
• Sağlayıcı P1 için saat başına 'DLQ Oranı> %2'.
• 'Schema Drift algılandı' - P0 (kaynağa göre otomatik eşleştirmeyi durdurun).
• 'Duplicate spike' - P2 (sağlayıcı/webhooks kontrol edin).

Dashbord: Bir huni 'dosyaları rows_raw - rows_norm - rows_valid - rows_matched', nedenlerle DLQ kartı, TtA-quantiles.

10) Otomatik düzeltmeler ve eşlemeler

Üstbilgi takma adları: sürümleri olan sözlük (örneğin, 'Tutar', 'amt', 'TUTAR', 'amt').

11) "PSP Ödemeleri ve Raporlarının Mutabakatı" Bağlantısı

Hazır normalleştirilmiş katman - eşleştirme için girdi (provider_txid/merchant_ref/fuzzy), diff-taksonomiyi hesaplama, otomatik günlükler ve settlement↔bank -titleme. Anahtar alanlar: 'provider _ txid', 'sequence', 'kind', 'amount _ minor', 'value _ date', 'account'.

12) Depolama modeli ve tablolar

sql
CREATE TABLE landed_files (
file_id TEXT PRIMARY KEY,
provider TEXT,
source_kind TEXT,
file_name TEXT,
file_size BIGINT,
checksum TEXT,
statement_date DATE,
received_at TIMESTAMP WITH TIME ZONE,
version INT,
status TEXT, -- RECEIVED    PARSED    FAILED error TEXT
);

sql
CREATE TABLE psp_norm (
row_id BIGSERIAL PRIMARY KEY,
file_id TEXT REFERENCES landed_files(file_id),
provider TEXT,
source_kind TEXT,
kind TEXT,
payment_id TEXT,
provider_txid TEXT,
merchant_ref TEXT,
sequence INT,
amount_minor BIGINT,
currency CHAR(3),
fee_minor BIGINT,
fx_rate NUMERIC(18,8),
fx_src TEXT,
event_ts TIMESTAMPTZ,
value_date DATE,
account TEXT,
status TEXT,
row_hash TEXT UNIQUE,
repair_flags TEXT[]
);
CREATE INDEX idx_psp_norm_txid ON psp_norm(provider, provider_txid, sequence);

13) Ayrıştırıcı pseudocode

python def parse_table(file, spec):
df = load_csv_or_xlsx(file, delimiter=spec.delim, encoding=spec.enc, sheet=spec.sheet)
df = rename_headers(df, spec.header_aliases)
df = clean_amounts(df, thousand=spec.thousand, decimal=spec.decimal, sign_policy=spec.sign)
rows = []
for r in df.itertuples():
rows.append(normalize_row(r, spec))
return rows

python def parse_camt(xml):
root = parse_xml(xml, xsd="camt053.xsd")
for ntry in root.findall('.//Ntry'):
sign = 1 if ntry.findtext('CdtDbtInd') == 'CRDT' else -1 amt = Decimal(ntry.findtext('Amt')) sign
... map to normalized fields

python def parse_pdf_ocr(pdf):
text = tesseract(pdf, lang="eng", psm=6, whitelist="0123456789.,-;:/A-Za-z")
table = detect_table(text)
return normalize_table(table)

14) GDPR/PII ve günlük düzenleme

Maskeleme/hashing: PAN/e-posta/telefon - 'sha256 + tuz', günlükler - birincil değerler olmadan.
Saklama politikası: Kaynak türüne göre 'tutma' (AML/muhasebe).
PII erişimleri - sadece role göre; Okuma/dışa aktarma denetimi.

15) KPI'lar ve hedefler (ayrıştırma/yutma için)

Yutma Başarısı %99 ≥. Kaynak başına %5/gün.
Ayrıştırma Başarısı % ≥ 99 %, DLQ ≤ %1.
TtA p95 (fayl - normalize edilmiş) ≤ 15 dakika (CSV/XML), ≤ 60 dakika (PDF/OCR).
Şema Sürüklenme Olayları: Uyarı/düzeltme olmadan 0/ay.
Duplicate Rate по 'provider _ txid' ≤ 0. 05%.

16) Olay oyun kitapları

Şema kayması: otomatik eşleştirmeyi durdurun, hoparlörlerin ML algılamasıyla "yumuşak" ayrıştırıcıyı açın, bir takma ad yaması hazırlayın, DLQ-replay çalıştırın.
DLQ dalgalanması: En son dosyalarda hata ayıklama, kodlama/yerel/işareti kontrol etme, toleransların şiddetini geçici olarak azaltma (bayrakla).
SFTP gecikmeleri: API yoklama/webhook'lara geçiş, geri çekilmeleri artırma, sağlayıcı ile iletişim.
Spikes kopyaları: ek doğrulamayı etkinleştirin 'row _ hash', açıklığa kavuşana kadar tekrarlama bloğu.

17) Test Kasa Paketi (UAT/Prod-Ready)

1. Idempotency: 1 'file _ id', 0 yeni satır ile aynı yükü tekrarlayın.
2. Locales: ','/' olan dosyalar. '/spaces - doğru toplamlar.
3. Kısmi/geri ödeme: bir 'sağlayıcı _ txid' için çoklu 'dizi'.
4. XML XSD: geçersiz CAMT - 'INVALID' + DLQ.
5. MT940 varyasyonlar: ulusal uzantılar - doğru analiz.
6. PDF - OCR: gürültüyle tarama - temel kuralları çıkarma ve geçirme.
7. Şema sürüklenme: yeni bir başlık - takma adı yama ve tarihsel dosyaların yeniden işlenmesi.
8. Throughput: N dosya/saat yük testi - TtA SLA ile uyumluluk.
9. PII sürümü: PAN/e-posta içermeyen günlükler, yalnızca karma.

18) Uygulama kontrol listesi

• Kaynak Kayıt Defteri: Protokol, Zamanlama, SLA, Biçim, İletişim.
• Güvenli kanallar (SFTP/PGP/API), Sırlar için Vault.
• Idempotent yutma + sağlama toplamı + sürümleri.
• Biçim, takma ad sözlüğü, işaret/yerel ilkelere göre ayrıştırıcılar.
• Normalleştirilmiş katman ve anahtar indeksleri.
• Doğrulama kuralları, toleranslar, DLQ ve tekrar oynatma.
• Orkestra (DAG), Retrai/Backoff, Kaynak Havuzları.
• Gözlemlenebilirlik: metrikler, gösterge panoları, uyarılar.
• GDPR/PII maskeleme, erişim denetimleri.
• Test durumları ve düzenli şema-sürüklenme tatbikatları.

Özgeçmiş Özeti

Ayrıştırma otomasyonu'bir ayrıştırıcı yazmak'değil, endüstriyel bir devre oluşturmaktır: güvenilir teslimat ve şifreleme, idempotent boru hatları, sıkı normalleşme, kalite kuralları ve şeffaf uyarılar. Böyle bir taslak, herhangi bir kaydı, veri kullanılabilirliği konusunda garantili bir SLA ile öngörülebilir tablolara dönüştürür - uzlaşma, hazine ve yönetim raporlaması için temel oluşturur.