Ana içeriğe geç

Qapu Servis Audit ve Yapılacaklar

Bu sayfa, Qapu servis dokümantasyonunun mevcut kalite seviyesini ölçmek ve hedef kalite seviyesi olan 9.5+/10 için kalan eksikleri görünür hale getirmek amacıyla hazırlanmıştır.

Değerlendirme Metodu​

Her servis aşağıdaki başlıklara göre değerlendirildi:

  1. Rol netliği: Servis ne yapıyor, ne yapmıyor açık mı?
  2. Girdi/çıktı sözleşmesi: Event, tablo, state ve çıktı net mi?
  3. Akış bütünlüğü: İşlem sırası ve hata akışı yeterince belirgin mi?
  4. Operasyonel olgunluk: Retry, DLQ, idempotency, latency, SLO, ownership gibi konular tanımlı mı?
  5. Dokümantasyon derinliği: FAQ, alt sayfalar, örnekler, referans bağlantıları ve karar kayıtları yeterli mi?

Puan Skalası​

  • 9.5 - 10.0: Yayınlanabilir, mimari olarak güçlü, operasyonel olarak güven veren doküman
  • 8.5 - 9.4: Güçlü ama birkaç kritik boşluk var
  • 7.0 - 8.4: Mimari iyi, operasyonel veya sözleşmesel detaylar eksik
  • < 7.0: Şimdilik özet/index seviyesinde, derinleştirme şart

Genel Sonuç​

Güçlü taraflar​

  • Core pipeline servislerinde mimari omurga belirgin.
  • stream_buffer referans modeli dokümanlar arası ortak omurga haline gelmiş.
  • Ingest, Stream, Raw Writer, Synthesis ve Window tarafında event, Redis ve DB ilişkisi büyük ölçüde net.
  • Çoğu kritik servis için alt akış sayfalarına referans verilmiş, bu iyi bir bilgi mimarisi işareti.

Ana problemler​

  • Bazı servisler çok olgun, bazıları ise yalnız index/özet seviyesinde. Doküman kalitesi homojen değil.
  • Dil standardı tutarsız. Türkçe, İngilizce, ASCII-only ve farklı isimlendirme stilleri karışıyor.
  • Bazı servislerde topic standardı ile diğer sayfalardaki naming aynı çizgide değil.
  • Operasyonel sahiplik, failure mode ve replay stratejisi her serviste aynı derinlikte değil.
  • Bazı sayfalarda "servis kontratı" ile "teknik not" aynı yerde karışıyor.

Servis Bazlı Puanlama​

ServisPuanKısa yorum
Ingest9.4Çok güçlü, neredeyse referans kalite, ama fazla yoğun ve bazı bölümler sadeleştirilmeli
Stream9.1Envanter senkronizasyonu ve akış iyi, birkaç operasyonel netleştirme gerekli
Calibration8.8Temel model net, ancak hata matrisi ve edge-case kapsamı zayıf
Raw Writer8.9Segment yazım modeli güçlü, ama partial failure ve recovery daha net yazılmalı
Synthesis9.0Güçlü teknik içerik var, fakat sayfa biraz dağınık ve bazı bölümler çakışıyor
Window8.9Finalize mantığı iyi, ancak replay/revision politikası daha kesin olmalı
Rule8.3Fikir seviyesi iyi, ama sözleşme ve operasyonel disiplin diğer servislerin gerisinde
Observer8.7Operasyon fikri güçlü, ama veri modeli ve retry ownership daha fazla somutlaştırılmalı
Action Executor8.0İyi yön var, ama hâlâ tasarım notu seviyesi baskın
Communication8.6Komut çözümleme modeli net, ACK timeout ve downlink lifecycle daha da güçlenebilir
API8.2Şık özet var, ama endpoint sınıfları, auth akışı ve domain coverage daha detaylanmalı
Automation8.4Scheduler mantığı net, ama concurrency ve lock stratejisi eksik
Egress8.5Kurumsal entegrasyon yaklaşımı iyi, dönüşüm ve güvenlik policy örnekleri artırılmalı
FOTA8.3Amaç net, ancak FTP lifecycle ve güvenlik kısıtları daha formal olmalı
Heartbeat8.4İşlev net, ama alarm/eskalasyon ve batch davranışı genişletilmeli
Ledger8.2Güzel fikir, fakat zincir doğrulama ve snapshot kapsamı daha formal anlatılmalı
Redis8.0Güzel entry point, ama servis sayfasından çok portal/index gibi duruyor
Kafka8.8Merkezi referans olarak güçlü, fakat bazı event/topic isimleri diğer sayfalarla hizalanmalı

9.5+ Hedefi İçin Öncelikli Eksik Listesi​

P0, doğrudan kalite puanı yükselten işler​

1. Doküman standardını tekle​

Yapılacaklar:

  • Tüm servislerde aynı başlık sırası kullanılmalı:
    • Sorumluluk
    • Girdiler
    • Çıktılar
    • İşlem akışı
    • Veri kaynakları
    • Hata modeli
    • Retry/DLQ
    • Gözlemlenebilirlik
    • Güvenlik
    • SSS / alt sayfalar
  • Türkçe terim standardı sabitlenmeli.
  • İngilizce başlık kalıntıları temizlenmeli (Rule Service gibi).
  • ASCII mecbur değilse Türkçe karakterler normalize edilmeli.

Beklenen etki:

  • Doküman algısında ciddi profesyonellik artışı
  • Servisler arası kıyas kolaylaşır

2. Topic ve event naming bütünlüğünü kilitle​

Gözlenen problem:

  • Bazı sayfalarda qapu.ingest.raw, bazılarında qapu.ingest
  • Bazı sayfalarda qapu.action.requested, bazılarında qapu.action
  • Bazı servislerde topic ve event ayrımı iyi, bazılarında karışık

Yapılacaklar:

  • Tek bir naming policy sayfası referans alınmalı
  • Her servis index sayfası yalnız kendi kullandığı canonical topic isimlerini göstermeli
  • Eski veya alternatif adlar varsa “legacy/not preferred” olarak işaretlenmeli

Beklenen etki:

  • Mimari güven artar
  • Entegrasyon ekiplerinde kafa karışıklığı azalır

3. Her servis için net hata matrisi zorunlu hale getir​

Eksik olan servisler:

  • Calibration
  • API
  • Automation
  • Egress
  • FOTA
  • Heartbeat
  • Ledger
  • Action Executor

Yapılacaklar:

  • Her servise şu tablo eklensin:
    • hata türü
    • retryable mi
    • event/log çıktısı
    • DLQ davranışı
    • operatör müdahalesi gerekiyor mu

Beklenen etki:

  • 8.x servisleri rahatlıkla 9+ bandına taşır

4. Replay ve idempotency politikalarını servis bazında kapat​

Eksik alanlar:

  • Rule
  • Observer
  • Action Executor
  • Communication
  • Automation
  • Ledger
  • Heartbeat

Yapılacaklar:

  • Her servis için tekrar işleme anahtarı tanımlanmalı
  • Replay geldiğinde ne overwrite edilir, ne append edilir yazılmalı
  • Duplicate event durumunda beklenen davranış belirtilmeli

P1, kaliteyi 9.5 üstüne taşıyan derinleştirme işleri​

5. Rule Servisi tam profesyonel seviyeye çıkarılmalı​

Şu an en kritik eksiklerden biri burada.

Yapılacaklar:

  • Rule index sayfası diğer servisler gibi daha formal yeniden yapılandırılmalı
  • Input/output contract bölümü açıklaştırılmalı
  • Rule state Redis şeması ayrı kontrat sayfasına bağlanmalı
  • rule.completed.v1, rule.failed.v1, rule.triggered.v1, rule.reset.v1 ayrımı kesinleştirilmeli
  • Duration counter reset, publish gating ve multi-trigger edge-case tabloları eklenmeli
  • Latency/SLO ve retry ownership netleşmeli

Hedef puan:

  • 8.3 → 9.4+

6. Action Executor servisini tasarım notundan kontrat seviyesine çıkar​

Yapılacaklar:

  • action.execute.requested.v1 payload alanları net tablo ile verilmeli
  • action_plan_steps çözümleme modeli formalize edilmeli
  • Her channel type için adapter lifecycle anlatılmalı
  • Circuit breaker, provider retry ve idempotency guarantee açık yazılmalı
  • Başarı ve kalıcı hata ayrımı tabloya dökülmeli

Hedef puan:

  • 8.0 → 9.2+

7. API sayfasını gerçek servis kontratına dönüştür​

Yapılacaklar:

  • Mobil, admin ve internal domain alanları tablo ile ayrılmalı
  • Auth flow, refresh flow, session invalidation ve auth cache daha görünür olmalı
  • Temel kaynak grupları listelenmeli: devices, rules, actions, automations, firmware, recipients, telemetry
  • API event üretim haritası eklenmeli
  • Audit log ownership ve idempotency davranışı yazılmalı

Hedef puan:

  • 8.2 → 9.1+

8. Observer için operasyonel ownership çok daha net yazılmalı​

Yapılacaklar:

  • Retry kararı Observer mı verir, stage servisleri mi verir, sınır netleştirilmeli
  • observer_pipeline_runs alanları daha somut anlatılmalı
  • Stale stream replacement politikası örnek senaryo ile gösterilmeli
  • Buffer cleanup koşulları tabloya dökülmeli

Yapılacaklar:

  • Cınga kalan yerler Qapu ile hizalanmalıysa temizlenmeli
  • /projects/cinga/... kalan referanslar gözden geçirilmeli
  • FOTA sayfa/dizin adı ftp ve fota arasında tekleştirilmeli
  • Backend index notlarındaki eski path'ler doğrulanmalı

P2, polish ve yayın kalitesi işleri​

10. Dil ve anlatım sıkılaştırması​

Yapılacaklar:

  • Aynı sayfada hem çok kısa hem aşırı uzun bloklar dengelenmeli
  • Gereksiz tekrarlar azaltılmalı
  • Aşırı uzun pseudo-config blokları gerekiyorsa alt sayfaya taşınmalı
  • “bu sayfada tekrar edilmez” denilen yerlerde gerçekten tekrar edilmemeli

11. Her servise kısa “neden var” paragrafı eklenmeli​

Bazı servislerde çok iyi, bazılarında eksik. Özellikle API, Automation, Ledger, Redis, Heartbeat için güçlendirir.

12. Her servise gözlemlenebilirlik minimum paketi eklenmeli​

Zorunlu alanlar:

  • temel metrikler
  • error code family
  • trace bağlamı
  • alarm üretim sınırı

Servis Bazlı Net Yapılacaklar​

Ingest​

  • Çok uzun bölümler sadeleştirilmeli, özellikle rate limiting ve config kısmı ikiye bölünebilir
  • Topic adı merkezi Kafka standardı ile birebir hizalanmalı
  • Warning event isimleri Kafka sayfasıyla birebir kontrol edilmeli

Stream​

  • Envanter eventlerinin retry/idempotency davranışı daha formal yazılmalı
  • message_type sözlük çözümlemesinde observability alanları genişletilmeli
  • Başarı kriteri ve terminal state tek paragrafta özetlenmeli

Calibration​

  • Tam hata matrisi eklenmeli
  • Kural bulunamadı, CT miss, stale cache, invalid range gibi edge-case tablosu eklenmeli
  • Idempotency / replay açıklaması eklenmeli

Raw Writer​

  • Partial segment failure örnekleri eklenmeli
  • Catch-all measurements tablosu için conflict davranışı netleştirilmeli
  • Replay sonrası aynı stream için tablo tutarlılığı anlatılmalı

Synthesis​

  • Aynı sayfadaki bazı tekrarlar sadeleştirilmeli
  • Observer ile SLO ownership bölümü daha temiz ayrılmalı
  • Retry/DLQ bölümü daha kısa ve kontrat odaklı hale getirilmeli

Window​

  • Finalized pencere replay kuralı örneklenmeli
  • window.state.patch.v1 canonical mi taslak mı netleştirilmeli
  • Rollup anında partial failure davranışı yazılmalı

Rule​

  • Sayfa tamamen yeniden düzenlenmeli, diğer servis formatına çekilmeli
  • Event contract bölümü açıklaştırılmalı
  • Redis runtime schema ayrı kontrata bağlanmalı
  • Hata matrisi, retry ve idempotency açık yazılmalı
  • SLO/metrik bölümü eklenmeli

Observer​

  • Replay ownership netleştirilmeli
  • Terminal state tablosu eklenmeli
  • Buffer cleanup kararı örnek akışlarla gösterilmeli

Action Executor​

  • Input event contract tablo halinde verilmeli
  • Channel adapter yaşam döngüsü açıklanmalı
  • Retryable/non-retryable hata matrisi eklenmeli
  • Provider idempotency modeli yazılmalı

Communication​

  • ACK timeout, late ACK ve duplicate ACK davranışları eklenmeli
  • Downlink command lock yaşam döngüsü yazılmalı
  • Source bazlı yetki matrisi tabloya dökülmeli

API​

  • Domain bazlı endpoint haritası eklenmeli
  • Auth/session invalidation akışı özet tablo ile güçlendirilmeli
  • Event üretim matrisi eklenmeli
  • Error contract ve audit trail detaylandırılmalı

Automation​

  • Scheduler concurrency ve distributed lock stratejisi eklenmeli
  • Missed run / drift / node restart davranışı yazılmalı
  • Replay / rerun farkı netleştirilmeli

Egress​

  • Policy dönüşüm pipeline örneği eklenmeli
  • Security profile örnekleri artırılmalı
  • Outbound signing ve replay protection kontratı eklenmeli

FOTA​

  • ftp klasörü ile fota slug/name standardı tekleştirilmeli
  • Transfer yaşam döngüsü ve durum geçiş tablosu eklenmeli
  • Yetki modeli ve checksum doğrulama netleştirilmeli

Heartbeat​

  • Batch ping concurrency limiti yazılmalı
  • Alarm/eskalasyon eşikleri tabloya dökülmeli
  • ICMP yerine alternatif health yöntemleri notu eklenmeli

Ledger​

  • Hash üretim sözleşmesi formalize edilmeli
  • Canonical snapshot kapsamı tablo ile tanımlanmalı
  • Chain verification örneği eklenmeli
  • Replay durumunda yeni halka mı, yeniden yazım mı olacağı netleştirilmeli

Redis​

  • Index/portal rolü korunup minimum operasyonel kontrat bölümü eklenmeli
  • Key family ownership özeti tablo olarak üst seviyeye eklenmeli
  • TTL/invalidation summary box eklenmeli

Kafka​

  • Tüm topic/event adları servis sayfalarıyla tek tek hizalanmalı
  • DLQ standardı her servis için birebir örneklenmeli
  • “Qapu” ve eski mimari isimleri tam normalize edilmeli

Hedef Durum Özeti​

9.5+ kalite seviyesi için minimum başarı koşulları:

  • Her servis aynı doküman iskeletine sahip olmalı
  • Her servis için canonical input/output contract net olmalı
  • Retry, DLQ, replay, idempotency net olmalı
  • Topic/event naming tek standarda bağlanmalı
  • Cross-link ve terminoloji temiz olmalı
  • Rule, Action Executor ve API özellikle bir üst seviyeye çıkarılmalı

Kısa Yönetici Özeti​

Bugünkü durumda Qapu servis dokümantasyonu genel olarak 8.7/10 civarında güçlü bir mimari tabana sahip.

9.5+/10'a çıkmak için en kritik sıralama:

  1. Rule Servisi yeniden düzenleme
  2. Action Executor kontrat derinleştirme
  3. API kontratını genişletme
  4. Topic/event naming standardını kilitleme
  5. Tüm servislerde hata matrisi + replay/idempotency bölümünü tamamlama

Bu 5 başlık kapatılırsa doküman seti ciddi biçimde yayınlanabilir, yatırımcıya/mühendise/ekibe güven veren bir seviyeye çıkar.