Gümrük Motoru

Gümrük Motoru Nedir?

server/engines/CustomsEngine.ts, Gümrük & Küresel Ticaret Operasyonları add-on'undaki her AI çağıran ve yargı bölgesi farkında ekranı destekleyen tek sunucu taraflı dosyadır. Aynı dosyada yaşayan iki ayrı işi vardır:

Bir yargı bölgesi Strategy Pattern'i (en eski kısmı, Patent Ajanı'nun ve Uyumluluk Motoru'nun şeklini yansıtır) — bir ülke kodu ve bir şema kategorisi verildiğinde, eşleşen CustomsSchemaStrategy'yi seçer (Türkiye/GTİP, Amerika Birleşik Devletleri/HTS veya genel bir varsayılan) ve render edilmeye hazır bir gümrük müşavirliği yetkilendirme, Incoterms kural veya tarife sınıflandırma formu döner.
On bir bağımsız AI akıl yürütme uç noktası, add-on'daki her ekran için bir tane, hepsi aynı şekli izler: istekten bir prompt oluştur, apiMode'a göre Cohere / Anthropic API / Claude CLI'ye yönlendir, modelin JSON yanıtını ayrıştır ve sonucu Olay & Analitik Motoru aracılığıyla kaydet.

Tek cümlede

Gümrük Motoru, Gümrük & Küresel Ticaret Operasyonları'ndaki her "2. Aşama" AI çağrısının fiilen çalıştığı yerdir — frontend'in tek işi önce yerel embedding'ler aracılığıyla doğru bağlamı bulmak (1. Aşama) ve bunu bu motorun on bir uç noktasından birine vermektir.

Bu Motorun Tamamladığı İki Aşamalı Hibrit Desen

Gümrük & Küresel Ticaret Operasyonları'ndaki her AI çağıran ekran aynı iki aşamalı akışı çalıştırır ve Gümrük Motoru her zaman 2. Aşamadır:

1. Aşama — Embedding Engine (istemci, yalnızca yerel Ollama) → 2. Aşama — Gümrük Motoru (bu dosya, writerEngine ile yönlendirilir)

Aşama	Nerede çalışır	Ne yapar
1. Aşama	Tamamen istemci tarafında, `src/services/customsEmbeddingService.ts` içinde, Bilgi Motoru'nu sarmalar	Ekranın sorgu metnini, kiracının kendi canlı defterine (yaptırım kuralları, beyannameler, gümrükleme kayıtları, navlun kıyaslamaları vb.) karşı, kullanıcının kendi yerel Ollama örneği aracılığıyla vektörleştirir (`ollamaEngine.embed` + kosinüs benzerliği), asla sunucuya dokunmadan.
2. Aşama	Kullanıcının Ayarlar → Agentic seçimine bağlı olarak istemci tarafında (`callClaude()`) veya sunucu tarafında (bu motor)	1. Aşamanın en iyi eşleşmelerini alır ve üzerinde akıl yürütür — risk puanlama, fazla ücretlendirme/fazla ödeme tespiti, uyuşmazlık teşhisi vb. Sunucuya yalnızca `writerEngine` `'api'` veya `'local-cli'` olduğunda ulaşır.

1. Aşama neden asla sunucuya ulaşmaz?

ollama/local-llm/web-llm hepsi kullanıcının kendi tarayıcısında veya kendi makinesinde çalışır — Render sunucusunun bir kullanıcının 127.0.0.1:11434 Ollama örneğine ağ erişimi yoktur. Bir istemci fonksiyonu bu kontrolü atlayıp her zaman sunucuyu çağırsaydı, Ayarlar'da Ollama'yı seçmek yerel yönlendirme yerine sessizce kafa karıştırıcı 500 hatalarına yol açardı. Bu, proje genelinde "Full Writer Engine Support Rule" olarak belgelenmiştir ve Gümrük Motoru'nun on bir istemci taraflı karşılığının her biri bunu uygular.

Aday havuzu her zaman kiracının kendi defteridir

TotalApp'teki küçük statik örnek külliyata karşı sıralama yapan bazı diğer motorların aksine, her Gümrük ekranının 1. Aşama araması kiracının kendi canlı kayıtlarını sıralar — henüz bağlı bir harici regülasyon külliyatı (gerçek bir OFAC/EU/UN yaptırım arşivi, gerçek bir devlet tarife cetveli, gerçek bir taşıyıcı SLA veritabanı) yoktur. Örneğin Trade Compliance ekranındaki "Search Similar Rules", gerçek bir devlet listesine değil, zaten dosyada bulunan yaptırım kurallarını semantik olarak sıralar.

Bölüm 1 — Yargı Bölgesi Şema Stratejisi

resolveCustomsStrategy(countryCode), gelen kodu büyük harfe çevirir ve üç somut CustomsSchemaStrategy sınıfı arasında geçiş yapar, her biri tek bir metot uygular: getSchema(category).

Strateji	Yargı Bölgesi	Referans Alınan Kanun
TRCustomsStrategy	Türkiye (GTİP — 12 haneli tarife kodu)	6769 Sınai Mülkiyet Kanunu, TSE/CE/Tareks belge alanları
USCustomsStrategy	Amerika Birleşik Devletleri (HTS — 10 haneli tarife kodu)	FDA/EPA/FCC belge alanları
DefaultCustomsStrategy	Eşlenmemiş herhangi bir ülke	Genel yedek alanlar, asla hata fırlatmaz

Her strateji category'ye göre tekrar dallanır ve üç farklı alan setinden birini döner:

`broker_agency`

Gümrük sicil numarası, Vekaletname referansı ve bitiş tarihi, dijital imza sertifika numarası ve yetkili gümrük müdürlükleri — Gümrük Müşavirleri & Acenteleri ekranının yetkilendirme modalını besler.

`incoterms_rules`

Incoterm kodu, risk devir noktası, alıcı navlun maliyet payı (%), alıcı risk payı (%) ve (yalnızca TR) bir KDV istisna kodu — Incoterms & Teslimat Kuralları ekranını besler.

Varsayılan (tarife sınıflandırması)

HS/GTİP veya HTS kodu, ürün tanımı, gümrük vergisi oranı (%), ÖTV oranı (%, yalnızca TR) ve gerekli belgeler/sertifikalar — GTİP Kataloğu ekranını besler.

Ortaya çıkan UiComponent Form ağacı, TotalApp'teki her diğer sunucu güdümlü arayüz şemasının kullandığı aynı <DynamicScreenRenderer> bileşeni tarafından render edilir — POST /api/customs-engine/generate-schema'da handleCustomsEngineGenerateSchema tarafından sunulur.

Bölüm 2 — On Bir AI Akıl Yürütme Uç Noktası

Gümrük & Küresel Ticaret Operasyonları'ndaki her AI çağıran ekranın bu dosyada kendi özel işleyici fonksiyonu vardır. On birinin tümü aynı şekli paylaşır — prompt oluştur, apiMode'a göre yönlendir (Cohere command-r7b-12-2024 / Anthropic claude-sonnet-4-6 / Claude CLI), modelin JSON'ını ayrıştır, Olay & Analitik Motoru aracılığıyla kaydet — ve yalnızca prompt içerikleri ve çıktı şemaları bakımından farklılık gösterirler:

İşleyici	Uç Nokta	Beslediği Ekran	Ne Hesaplar
`handleCustomsEngineTradeComplianceAudit`	`/customs-engine/trade-compliance-audit`	Ticaret Uyumluluğu & Yaptırımlar	Önerilen bir ihracat/sevkiyat için yasaklı taraf eşleşmesi, çift kullanımlı lisans gerekliliği, askeri kullanım risk vektörü ve gerekli belgeler.
`handleCustomsEngineExportDeclarationAudit`	`/customs-engine/export-declaration-audit`	İhracat Beyannameleri	Bir giden (ETGB) beyannamesi için eksik fatura detayları, çift kullanımlı ihracat bayrağı ve döviz değerleme farkı notu.
`handleCustomsEngineImportDeclarationAudit`	`/customs-engine/import-declaration-audit`	İthalat Beyannameleri	Düşük değerleme risk uyarısı, referans fiyat farkı (%) ve bir TAREKS güvenlik incelemesi tutma önerisi.
`handleCustomsEngineClearanceRiskAudit`	`/customs-engine/clearance-risk-audit`	Gümrükleme Durumu	Yönlendirme gerekçesi, tahmini ek gecikme (saat) ve fiziki (Kırmızı Hat) muayenenin olası olup olmadığı.
`handleCustomsEngineOriginDocValidationAudit`	`/customs-engine/origin-doc-validation-audit`	Sertifikalar & Menşe Belgeleri	Tercihli bir menşe belgesi için Yerli Katkı Oranı eşiği kontrolü, menşesiz malzeme riski ve oda onayı doğrulaması.
`handleCustomsEngineCarrierRateAudit`	`/customs-engine/carrier-rate-audit`	Navlun Oranı Kıyaslaması	Bir ticaret hattı için taşıyıcı fazla ücretlendirme tespiti, spot oran arbitraj fırsatı ve tahmini bir fiyat kaçağı tutarı.
`handleCustomsEngineDemurrageRiskAudit`	`/customs-engine/demurrage-risk-audit`	Küresel Sevkiyat Takibi	Tahmini varış farkı, serbest süre dolma aciliyeti ve önerilen bir konteyner çıkış önceliği.
`handleCustomsEngineFreightBookingAudit`	`/customs-engine/freight-booking-audit`	Taşıyıcı & Nakliyeci Merkezi	Bir lojistik tedarikçisi için SLA sözleşme ihlali tespiti, rezervasyon tahsis düşüşü tespiti ve tahmini bir tehlikeli kargo elleçleme doğruluğu.
`handleCustomsEngineLandedCostAudit`	`/customs-engine/landed-cost-audit`	Teslim Maliyeti Hesaplayıcı	Vergi sıçraması tespiti, yanlış tahsis edilen terminal ücreti bayrağı ve sağlık-kontrolü amaçlı yeniden hesaplanmış birim teslim maliyeti.
`handleCustomsEngineDutyLedgerAudit`	`/customs-engine/duty-ledger-audit`	Gümrük Vergisi & Tarife Defteri	Fazla ödeme tespiti, iade (drawback) uygunluğu, yanlış hesaplanan tarife dilimi bayrağı ve tahmini bir iade tutarı.
`handleCustomsEngineDocMatcherLinterAudit`	`/customs-engine/doc-matcher-linter-audit`	Belge Eşleştirici & Denetleyici	Net ağırlık farkı, GTİP uyumsuzluğu ve döviz uyuşmazlığı bayrakları — tek bir çağrıya katlanmış iki geçişli bir Linter (aday topla) → Critic (onayla/ele) prompt yapısı aracılığıyla.

Neden tek bir genel işleyici yerine on bir neredeyse özdeş işleyici?

Her işleyicinin promptu alan-özeldir — bir yaptırım-tarama promptu ve bir vergi-iadesi promptu, model'den tamamen farklı şeyler hakkında akıl yürütmesini ister ve farklı bir JSON şekli döndürür. Bunları (tek bir parametreli mega-işleyici yerine) ayrı, bağımsız test edilebilir fonksiyonlar olarak tutmak, bir ekranın akıl yürütme mantığındaki bir değişikliğin başka bir ekranı asla sessizce etkileyememesi anlamına gelir; bunun bedeli, kasıtlı olan, kazara olmayan bir miktar tekrarlanan yönlendirme kodudur.

Sunucu Taraflı Yönlendirme Nasıl Çalışır — `apiMode`

On bir işleyicinin her biri, bir istek fiilen sunucuya ulaştığında (yani istemcide writerEngine 'api' veya 'local-cli' idi — Ollama/local-llm/web-llm buraya asla istek göndermez) tam olarak aynı yönlendirme mantığını uygular:

`apiMode`	Rota	Model
`'cohere'`	Cohere Chat API	`command-r7b-12-2024`
başka herhangi bir şey, `ANTHROPIC_API_KEY` tanımlı	Anthropic Messages API	`claude-sonnet-4-6`
başka herhangi bir şey, API anahtarı yapılandırılmamış	Yerel Claude CLI (Windows'ta `spawn('cmd', ['/c','claude','--print'])`)	CLI oturumunun çözdüğü herhangi bir şey

Üç yoldan hangisi hizmet verirse versin, tamamlanan veya başarısız olan her çağrı, engineName: 'CustomsEngine', işleyici başına bir workflowId (örn. 'customs-engine-duty-ledger-audit') ve bir süre ölçümüyle birlikte logEvent() aracılığıyla Olay & Analitik Motoru'na kaydedilir, böylece her ekranın AI kullanımı, TotalApp'teki her diğer motorla aynı kiracı genelindeki analitik geçmişinde görünür.

Gümrük Motoru Nereye Oturur

Bu motorun kendi kalıcılık katmanı yoktur — her ekranın defter verisi (yaptırım kuralları, beyannameler, gümrükleme kayıtları, navlun kıyaslamaları, vergi girişleri vb.), bu motor tarafından değil, src/services/customsTradeService.ts tarafından yönetilen, customs-trade/ altında kendi kiracıya özel JSON deposunda yaşar. Gümrük Motoru'nun işi kesinlikle akıl yürütme adımıdır: bir ekranın zaten topladığı bağlamı (kendi 1. Aşama embedding aramasıyla) alıp yapılandırılmış bir yargı üretmek ve geri vermek.

İstemcide, customsTradeService.ts'deki on bir karşılık gelen fonksiyonun her biri (runTradeComplianceAudit, runExportDeclarationAudit, runImportDeclarationAudit, runClearanceRiskAudit, runOriginDocValidationAudit, runCarrierRateAudit, runDemurrageRiskAudit, runFreightBookingAudit, runLandedCostAudit, runDutyLedgerAudit, runDocMatcherLinterAudit) önce useUIStore'dan writerEngine'i okur, üç yerel motor için doğrudan callClaude()'u çağırır ve yalnızca 'api'/'local-cli' için bu sunucu motorunun eşleşen uç noktasını çağırır.

Yeni bir veri katmanı değil, bir akıl yürütme katmanı

Gümrük Motoru bir kiracının saklanan kayıtlarını asla doğrudan okumaz veya yazmaz — çağıran ekranın istek gövdesinde topladığı bağlamı tam olarak alır, üzerinde akıl yürütür ve bir sonuç döner. Bu sonucu ekranın kendi defterine geri kalıcı hale getirmek, customsTradeService.ts aracılığıyla çağıran ekranın kendi sorumluluğundadır. Pratikte, ekranlar arasında satır aksiyonlarının (AI teşhisinin kendisinden farklı olarak) herhangi bir şeyi kalıcı hale getirip getirmediği değişir — aşağıdaki SSS'ye bakın.

Sıkça Sorulan Sorular

Bu tek dosya neden hem bir yargı bölgesi strateji deseni hem de on bir ilgisiz AI uç noktası içeriyor?

Yargı bölgesi strateji deseni (müşavirlik/Incoterms/tarife sınıflandırma formları), Patent Ajanı'nun ve Uyumluluk Motoru'nun şeklini yansıtarak önce yazıldı. Gümrük & Küresel Ticaret Operasyonları add-on'undaki her yeni ekran kendi 2. Aşama AI akıl yürütme uç noktasına ihtiyaç duydukça, işleyicisi ekran başına yeni bir tek seferlik motor dosyası oluşturmak yerine bu aynı dosyaya eklendi — add-on'un her sunucu taraflı parçasını tek bir yerde tutarak.

Bu motor Gümrük & Küresel Ticaret Operasyonları add-on'una özgü mü?

Bugün, evet — on bir AI uç noktasının ve her üç şema kategorisinin tümü, özellikle o add-on'un ekranlarına hizmet etmek için var. Ancak Strategy Pattern'de veya apiMode yönlendirme şeklinde add-on'a özel hiçbir şey yoktur; her iki desen de Patent Ajanı'nun, Uyumluluk Motoru'nun ve Matris Ajanı'in TotalApp'in başka yerlerinde zaten kullandığı aynı desenlerdir. Bir işleyici başka bir add-on tarafından doğrudan import edilerek kullanılamaz, çünkü her birinin istek/yanıt şekli ve promptu kendi ekranının veri modeli için elle yazılmıştır.

"Submit Drawback Refund Claim" veya "Lock Landed Cost Allocation" gibi satır aksiyonları her zaman ilgili kaydı günceller mi?

Hayır — ve bu, add-on'un ekranları arasında tutarlı değildir. Bazı yardımcı fonksiyonlar (örn. submitDutyRefundClaim, transmitExportDeclaration, updateProviderSLATier) bir makbuz referansı üretir ve kayıt üzerinde gerçek bir durum değişikliğini kalıcı hale getirir. Diğerleri (örn. lockLandedCostAllocation, applyDocLinterFix, enforceTradeSanctionHold) yalnızca bir makbuz referanslı toast bildirimi üretir — altta yatan kayıt dokunulmamış kalır ve sayfa yenilemesi herhangi bir görsel "kilitli/düzeltildi" durumunu geri alır. Hiçbir sınıf henüz gerçek bir harici sisteme (bir devlet başvuru geçidi, bir banka, bir ticaret odası) bağlı değildir; ikisi de gelecekteki bir entegrasyonu bekleyen yer tutuculardır.

Belge Eşleştirici & Denetleyici uç noktasındaki "Linter/Critic" iki geçişli yapısı nedir?

Bu, model'den yanıt vermeden önce iki dahili geçişte çalışmasını isteyen tek bir promptdur: önce bulabildiği her aday çapraz-belge uyuşmazlığını topla ("Linter" geçişi), sonra kendi adaylarını gözden geçir ve gerçek bir uyumsuzluk olmayanları — yuvarlama gürültüsü, birim dönüşümü artefaktları — nihai bir karara varmadan önce ele ("Critic" geçişi). Terminolojisini Matris Ajanı'in kendi Gatekeeper/Puanlama boru hattından ödünç alır, ama onunla hiçbir kod paylaşmaz — iki motorun veri şekilleri (ağırlıklı bir sayısal skora karşı bir dizi boolean uyuşmazlık bayrağı) yeterince farklıdır ki yalnızca iki-aşamalı prompt yapısı ödünç alınmıştır, herhangi bir fonksiyon değil.

Bölüm 1'e varsayımsal bir AB/EORI stratejisi gibi yeni bir yargı bölgesi nasıl eklenir?

CustomsSchemaStrategy'yi uygulayan yeni bir sınıf ekleyerek (örn. EUCustomsStrategy) ve resolveCustomsStrategy()'nin koşullu zincirine bir yeni dal ekleyerek. Şema uç noktasını çağıran hiçbir ekranın değişmesi gerekmez — zaten kullanıcının yargı bölgesi seçicisinin çözdüğü hangi countryCode'u iletiyorlarsa onu iletmeye devam ederler. Bu motorun şu anda Patent Ajanı'nun beşinden (TR/US/WO/EP/Default) daha az yargı bölgesini (TR/US/Default) desteklediğini not edin — AB ve WIPO gümrük formları bugün genel Varsayılan stratejiye düşer.