Uyumluluk Motoru
Bir şantiyenin ülkesini doğru evraka çözen bir Strategy Pattern motoru — ardından ortaya çıkan formu, Arayüz Oluşturma Motoru'nun zaten ürettiği aynı sunucu güdümlü arayüz şeması biçimini kullanarak frontend'e geri verir, böylece onu görüntülemek için yeni bir render kodu gerekmez.
Uyumluluk Motoru Nedir?
İnşaat evrakları her yerde aynı değildir. Bir Türk şantiyesi Ada, Parsel ve Pafta kadastro referanslarını, "Müteahhit SGK Sicil No" müteahhit kayıt numarasını, bir şantiye şefinin belge numarasını ve TAKS/KAKS kat alanı katsayılarını sunar. Bir ABD şantiyesi ise bunun yerine bir Parsel Kimliği, bir Müteahhit Lisans Numarası, bir OSHA Sertifikasyon Numarası ve bir İmar Sınıflandırması sunar. Ruhsat evrakına ihtiyaç duyan her ekran içine ülke başına bir form kodlamak, aynı yargı bölgesi mantığını üç farklı yerde yeniden türetmek anlamına gelir — ve en az birinde yanlış yapmak.
Uyumluluk Motoru bu mantığı tek bir Strategy Pattern arkasında merkezileştirir: tek bir metotlu bir PermitStrategy arayüzü, getPermitFormSchema(permitType), ve yargı bölgesi başına bir somut sınıf — TRPermitStrategy, USPermitStrategy, ve henüz kimsenin strateji yazmadığı bir ülke için asla hata fırlatmayan bir DefaultPermitStrategy yedeği. resolveComplianceStrategy(countryCode), gelen kodu büyük harfe çevirir ve aralarında geçiş yapar. Yeni bir yargı bölgesi eklemek, bir yeni strateji sınıfı yazmaktır, bu motoru çağıran ekranlardan hiçbirine dokunmak değildir.
Motorun çıktısı ham HTML veya kodlanmış bir React formu değildir — Arayüz Oluşturma Motoru'nun tanımladığı ve diğer motorların zaten ürettiği aynı sunucu güdümlü arayüz biçiminde bir UiComponent ağacıdır. Uyumluluk Motoru, paralel bir şema biçimi icat etmek yerine UiComponent/UiComponentKind/UiVariant'ı doğrudan UiRenderingEngine.ts'den yeniden kullanır, bu yüzden Matrix Agent'in onay ekranlarını boyayan aynı <DynamicScreenRenderer> bileşeni bir Uyumluluk Motoru ruhsat formunu da boyar — bu motorun çıktısı için hiçbir yeni frontend render kodu mevcut değildir.
Tek cümlede
Bir ülke kodu ve bir ruhsat tipi verildiğinde, bu motor doğru yargı bölgesinin PermitStrategy'sini seçer ve render edilmeye hazır bir form şeması döner — yeni bir ülke eklemek yeni bir strateji sınıfıdır, yeni bir ekran değildir.
Nasıl Çalışır — Çöz, Oluştur, Render Et
Her şema isteği, "bu şantiye hangi ülkede" sorusundan "ekranda çalışan, yargı bölgesine doğru bir form" sonucuna aynı üç aşamalı yolu izler:
| Aşama | Ne olur |
|---|---|
| 1. Stratejiyi Çöz | resolveComplianceStrategy(countryCode) kodu büyük harfe çevirir ve üzerinde geçiş yapar — TR, TRPermitStrategy'yi döner, US, USPermitStrategy'yi döner, geri kalan her şey (tanınmayan veya eksik bir kod dahil) DefaultPermitStrategy'yi döner. Fonksiyon asla hata fırlatmaz. |
| 2. Şemayı Oluştur | Çözülen stratejinin getPermitFormSchema(permitType)'i bir Form bileşen ağacı döner — etiketli Input alanlarından oluşan bir set (bazıları bir regex doğrulama deseniyle, bazıları min/max ile sayısal) artı bir gönder Button'ı. |
| 3. DynamicScreenRenderer ile Render Et | Frontend'in fetchComplianceSchema()'si /api/compliance-engine/generate-schema'ya POST eder ve dönen UiComponent'i doğrudan <DynamicScreenRenderer>'a verir — Arayüz Oluşturma Motoru'nun kendi onay ekranlarının kullandığı aynı bileşen. |
Neden özel bir Uyumluluk şeması tipi yerine UiComponent yeniden kullanılıyor?
Arayüz Oluşturma Motoru'nun UiComponent/UiComponentKind/UiVariant tiplerini yeniden kullanmak, frontend'in asla ikinci bir render motoruna, ikinci bir stil kataloğuna veya ikinci bir bileşen-tipi işlemeye ihtiyaç duymaması demektir. Yargı bölgesine özel bir ruhsat formu ve bir Matrix Agent onay ekranı, yapısal olarak aynı türden bir şeydir — girdiler, rozetler ve düğmelerden oluşan küçük bir ağaç — bu yüzden uçtan uca tek bir render yolunu paylaşırlar.
Girdi — Bir Şema İsteği Ne Taşır
Bir ruhsat formu oluşturmak için, motorun yalnızca doğru yargı bölgesini seçmeye ve isteği etiketlemeye yetecek kadarına ihtiyacı vardır:
Ülke Kodu
Hangi PermitStrategy'nin isteği yanıtlayacağına karar veren iki harfli kod (TR, US veya başka herhangi biri). Her çağrıda zorunludur — işleyici bunu eksik bir isteği reddeder.
Ruhsat Tipi
Bunun ne tür bir ruhsat veya kayıt olduğunu tanımlayan serbest biçimli bir dize (örn. building_permit, zoning_land, legal_liens). Zorunludur, ancak bugün yalnızca formu etiketler — bir stratejinin döndürdüğü alanları değiştirmez.
Şantiye Kimliği (isteğe bağlı)
Denetim izi ve gelecekteki kullanım için kabul edilir. countryCode'u şantiyeden türetmek, bu motoru çağırmadan önce çağıranın sorumluluğundadır — bir jobsiteId geçirmek şemanın kendisini değiştirmez.
permitType alan setini değiştirmez — henüz
Üç strateji yalnızca countryCode'a göre dallanır. Bir Türk yapı ruhsatı ve bir Türk imar kaydı şu anda tamamen aynı Ada/Parsel/SGK/TAKS/KAKS alan setini döner — permitType bir etiket olarak iletilir ve oluşturulan formu adlandırmak için kullanılır (permit_form_tr_${permitType}), ancak şemayı kendisi dallandırmaz. Bu, motorun mevcut kapsamı hakkında dürüst bir mimari notudur, gizli bir hata değildir.
Çıktı — Yargı Bölgesine Özel Bir Form Şeması
Yanıt, alanları strateji başına farklılık gösteren bir UiComponent Form ağacıdır:
| Strateji | Dönen alanlar |
|---|---|
| TRPermitStrategy | Ada, Parsel, Pafta (isteğe bağlı), Müteahhit SGK Sicil No (regex doğrulamalı), Şantiye Şefi Belge No (regex doğrulamalı), TAKS (sayısal, 0–1), KAKS / Emsal (sayısal, 0–10), ardından bir gönder düğmesi. |
| USPermitStrategy | Parsel Kimliği, Müteahhit Lisans Numarası (regex doğrulamalı), OSHA Sertifikasyon Numarası (regex doğrulamalı), İmar Sınıflandırması, ardından bir gönder düğmesi. |
| DefaultPermitStrategy | İsteğin permitType'ı ile önceden doldurulmuş devre dışı bir Ruhsat Tipi alanı, zorunlu bir Saha Adresi alanı, isteğe bağlı bir Notlar alanı, ardından bir gönder düğmesi — özel bir stratejisi olmayan herhangi bir ülke için güvenli genel yedek. |
Regex doğrulaması şemanın kendisi içinde taşınır
Müteahhit SGK Sicil No veya Müteahhit Lisans Numarası gibi alanlar, Input bileşeni üzerinde doğrudan bir regex özelliği taşır — UiRenderingEngine'in oluşturduğu aynı sunucu güdümlü arayüz kuralı, bu yüzden frontend'in paylaşılan girdi render motoru, hiçbir Uyumluluk'a özel doğrulama kodu olmadan bunu zaten nasıl uygulayacağını bilir.
Son Kullanıcılar Bunu Fiilen Nasıl Kullanır
Bir Ruhsat, İmar Kaydı veya Hukuki Sözleşme Dosyalama
Ruhsat Başvuruları, İmar ve Arazi Kullanım Kuralları veya Hukuki Sözleşmeler & Hacizler'in (üçü de İnşaat → Ruhsat ve İmar Uyumluluğu'nda) Ekle/Düzenle modalı içinde, "Form Oluştur" düğmesi bu motoru şantiyenin çözülmüş yargı bölgesiyle çağırır ve sonucu yerinde render eder. Bir Türk şantiyesinin kullanıcısı Ada/Parsel/SGK alanları görür; bir ABD şantiyesinin kullanıcısı Parsel Kimliği/OSHA alanları görür — her iki ekranda da tek bir satır ülkeye özel form kodu olmadan.
Kayıt Ortasında Yargı Bölgesi Değiştirme
Üç ekranın her biri kendi yargı bölgesi seçicisini taşır (Globe/ChevronDown stilinde bir SearchableCombobox), seçilen şantiyeden useJobsiteJurisdiction() aracılığıyla önceden doldurulmuş ancak kayıt başına geçersiz kılınabilir. Değiştirmek bu motoru yeniden çağırır ve render edilen alan setini buna uyacak şekilde değiştirir — bir holding şirketinin, şantiyenin kendisinin kayıtlı olduğu ülkeden farklı bir ülkede evrak dosyalaması için kullanışlıdır.
Uyumluluk Motoru Nereye Oturur
Bu motor kendisi hiçbir şey render etmez — bir şema oluşturur, ve Arayüz Oluşturma Motoru'nun render motoru bu şemayı bir ekrana dönüştüren şeydir:
| Tüketici Ekran | Ne talep eder |
|---|---|
| Ruhsat Başvuruları | Modalda seçilen kategoriye bağlı olarak {category}_permit şeklinde bir permitType — building_permit, environmental_permit veya scaffolding_permit. |
| İmar ve Arazi Kullanım Kuralları | Sabit bir permitType olan zoning_land. |
| Hukuki Sözleşmeler & Hacizler | Sabit bir permitType olan legal_liens. |
Üçü de src/services/complianceEngineService.ts içindeki fetchComplianceSchema()'yi çağırır, bu da uiEngineService.ts'den UiComponent tipini yeniden kullanır (çoğaltmaz) — frontend sunucu kodunu doğrudan içe aktaramadığı için sunucu taraflı tipleri çoğaltmak zorunda olan uiEngineService.ts'nin kendisinin aksine. Bu üç ekranın her birinin çıktısı, Arayüz Oluşturma Motoru'nun kendi onay ekranlarını render eden aynı <DynamicScreenRenderer> bileşeni (src/components/app-factory/DynamicScreenRenderer.tsx) tarafından boyanır — Uyumluluk Motoru'nun çıktısı için hiçbir yeni render kodu yazılmadı.
Arayüz Oluşturma Motoru'nun oluşturduğu her ekran gibi, her başarılı veya başarısız şema oluşturma, Olay & Analitik Motoru aracılığıyla izlenen bir olay olarak kaydedilir (engineName: 'ComplianceEngine', başarıda eventType: 'compliance-engine.schema.generated', hatada '.failed') — böylece başarısız olmaya başlayan bir yargı bölgesi, TotalApp'teki her diğer motor çağrısıyla aynı kullanım ve sağlık geçmişinde görünür.
Mevcut bir render motoruna eklenen bir yargı bölgesi çözücüsü, yeni bir tane değil
Bu motorun tüm işi doğru PermitStrategy'yi seçmek ve şemasını oluşturmaktır. Kendi render mantığı, kalıcılık katmanı veya ayarlar ekranı yoktur — özellikle İnşaat genelindeki (ve prensipte, ülkeye özel evraka ihtiyaç duyan herhangi bir gelecek add-on'daki) ruhsat/imar/hukuki ekranların "bu yargı bölgesi ne gerektiriyor?" sorusunu bir kez, tek bir yerde sorabilmesi için var.
Sıkça Sorulan Sorular
POST /api/compliance-engine/generate-schema), herhangi bir şey oluşturmadan önce countryCode'un mevcut ve bir dize olduğunu doğrular — eksik veya dize olmayan bir değer, varsayılan bir stratejiye düşmek yerine bir 400 hatası döner.resolveComplianceStrategy(), genel bir ruhsat tipi/adres/notlar formu döndüren ve asla hata fırlatmayan DefaultPermitStrategy'ye düşer. Bu ülkeler, arayüzdeki her yargı bölgesi seçicide hâlâ seçilebilir durumdadır, özellikle bir holding şirketinin bu ülkelerdeki şantiyelerinin, gerçek bir strateji mevcut olmadan önce bile temsil edilebilmesi için.jobsiteId denetim izi ve gelecekteki kullanım için kabul edilir ve iletilir, ancak şema yalnızca countryCode ve permitType'tan oluşturulur. Bu motoru çağırmadan önce countryCode'u şantiyeden türetmek (useJobsiteJurisdiction() aracılığıyla) çağıranın sorumluluğundadır.PermitRecord.formData, ZoningRegulationRecord.formData veya LegalContractRecord.formData içinde saklanır.PermitStrategy deseni ve UiComponent çıktı biçimi, ülkeye özel evraka ihtiyaç duyan herhangi bir gelecek add-on için de eşit derecede işe yarar.PermitStrategy'yi uygulayan yeni bir sınıf ekleyerek (örn. DEPermitStrategy) ve resolveComplianceStrategy()'nin switch ifadesine bir yeni case ekleyerek. Bu motoru çağıran hiçbir ekranın değişmesi gerekmez — zaten şantiyenin taşıdığı hangi countryCode'u iletiyorlarsa onu iletmeye devam ederler.