agent-enderun 1.0.7 → 1.0.8

package/docs/moduller.md

@@ -1,294 +0,0 @@
-# KENTİM — Detaylı Modüler Yapı ve Fonksiyonel Analiz Raporu (MVP Sürümü)
-
-Bu belge, KENTİM (Belediye Vatandaş Etkileşim ve İş Yönetim Sistemi) platformunun bünyesinde barındırdığı **tüm fonksiyonel modülleri, alt modülleri, bunların birbiriyle olan ilişkilerini ve teknik sorumluluklarını** en detaylı şekilde ortaya koymaktadır.
-
----
-
-## 1. Modüler Mimari Genel Bakış
-
-KENTİM sistemi, yüksek ölçeklenebilirlik sağlamak ve çok belediyeli (Multi-Tenant SaaS) yapının gerekliliklerini karşılamak adına **7 ana fonksiyonel modül** altında kurgulanmıştır.
-
-```mermaid
-graph TD
-    subgraph Vatandaş Katmanı
-        M_Vatandas[1. Vatandaş Etkileşim Modülü]
-    end
-
-    subgraph Belediye Operasyon Katmanı
-        M_Moderasyon[2. Moderasyon Modülü]
-        M_IsYonetimi[3. Saha ve İş Yönetim Modülü]
-        M_BelediyeAdmin[4. Belediye Sistem Yönetim Modülü]
-    end
-
-    subgraph Merkezi SaaS Katmanı
-        M_Central[5. Central SaaS Yönetim Modülü]
-    end
-
-    subgraph Arka Plan ve Güvenlik Katmanı
-        M_Core[6. Proje Çekirdeği & Veri İzolasyon Modülü]
-        M_Aux[7. Yardımcı Sistem Servisleri Modülü]
-    end
-
-    M_Vatandas -->|Rapor & Sinyal| M_Core
-    M_Core -->|Yönlendirme| M_Moderasyon
-    M_Moderasyon -->|İş Emri| M_IsYonetimi
-    M_BelediyeAdmin -->|Kurallar & Planlar| M_IsYonetimi
-    M_Central -->|Abonelik & Afet Sinyali| M_Core
-    M_Aux -->|SMS/Push/E-posta & Arşivleme| M_IsYonetimi
-```
-
----
-
-## 2. Modüllerin Detaylı Analizi
-
-### MODÜL 1: Vatandaş Etkileşim Modülü (Citizen Interaction)
-Vatandaşların (web ve mobil arayüzler üzerinden) belediyeyle temas kurduğu, sorun bildirdiği ve şehir yönetimine katıldığı modüldür.
-
-*   **1.1. Kimlik ve Profil Yönetimi**:
-    *   *Opsiyonel Kayıt*: Hesap oluşturmadan (anonim) veya tamamen E-posta OTP (E-posta Doğrulaması) ile doğrulanmış hesapla kullanım (telefon/SMS kaydı bulunmaz, SMS maliyet riski sıfırlanmıştır).
-    *   *KVKK Uyumluluğu*: Profil ve veri silme taleplerinin (`muni_admin` onaylı) işlenmesi, raporların anonimleştirilmesi.
-*   **1.2. Raporlama Motoru**:
-    *   *Harita Tabanlı Konumlandırma*: Leaflet entegrasyonu ile haritadan pin bırakma, adresin otomatik doldurulması.
-    *   *Fotoğraflı Kanıt*: Base64/Multipart ile max 5 fotoğraf (kategoriye göre zorunlu tutulabilir).
-    *   *Benzersiz Takip Kodu*: `KENT-[plaka]-XXXXXXXX` formatında kod üretimi ve PDF indirilebilmesi.
-    *   *Spam Bariyeri*: Google reCAPTCHA v3 doğrulaması ve IP tabanlı Rate Limiting (Dakikada 2, günde 10 rapor).
-    *   *Önleyici Mükerrer Kontrolü*: Pin bırakıldığı anda sistem 50-100m yakın aktif sorunları harita üzerinden sorgular ve mükerrer raporlamayı önleyici uyarı kartı gösterir.
-    *   *Kişisel Veri Tespit Uyarı Katmanı*: Metin alanlarında ad-soyad, telefon gibi kişisel verilerin girilmesini önlemek amacıyla istemci tarafında popüler isim sözlükleri ve asenkron regex tabanlı uyarı/sansürleme katmanı çalışır.
-*   **1.3. Katılım ve Geri Bildirim**:
-     *   *Puanlama & Yorum*: Çözülen işlere 1-5 yıldız arası puanlama.
-     *   *Sorun Devam Ediyor (Reopen)*: Maksimum 2 kez işi yeniden açarak moderatör havuzuna geri döndürme.
-     *   *Fikir Havuzu*: Şehir önerileri sunma, +1/-1 oylama. **Oy vermek** için yalnızca E-posta onaylı hesap gereklidir. **Fikir oluşturmak** için E-posta onayına ek olarak TC Kimlik doğrulaması (`is_identity_verified = true`) zorunludur. **Displays Adı ve MERNIS Ayrımı (Nick-Name Lockout Koruması):** MERNIS doğrulaması vatandaşın displays adı (takma adı) ile değil, doğrulama modalında girilen resmi kimlik formu bilgileriyle yapılır. Doğrulama başarılı olduğunda displays adı korunur, profil onaylanır. **E-posta OTP kuralı:** OTP doğrulaması hesap kaydında **tek seferlik** yapılır, her oyda OTP gönderilmez, JWT oturumu yeterlidir.
-    *   *"+1 Beni de Etkiliyor" Desteği*: Çözülmemiş public raporlara vatandaşların "+1" desteği vermesi; oyların `support_votes` tablosunda benzersiz olarak saklanması. **Performans Tasarımı:** Yoğun trafik altında row-locking darboğazını önlemek amacıyla `work_orders.support_count` sayıcı gerçek zamanlı DB trigger yerine **PostgreSQL LISTEN/NOTIFY tabanlı debounced asenkron worker** ile (toplu bulk update) yansıtılır. Her "+1" oyu önce `support_count_queue` unlogged tablosuna `INSERT` edilir, `pg_notify` ile worker tetiklenir.
-*   **1.4. Acil Durum & Afet Modülü**:
-    *   *Panik Butonu*: Konum bilgisiyle kriz masasına anlık GPS sinyali (Geofencing limitlerinden muaftır). **İstismar ve DDoS Koruması:** IP korumasından muaf olması sebebiyle sahte isteklerle kriz masasını kilitleme riskini azaltmak üzere, sunucu seviyesinde Device ID (cihaz kimliği) doğrulaması yapılarak aynı cihazdan dakikada **maksimum 5 acil durum sinyali** kabul edilir; fazlası engellenir.
-    *   *Tahliye Rotası*: Afet durumunda en yakın 3 resmi toplanma alanını haritada gösterip rota çizme.
-    *   *Geri Dönüşüm Haritası*: Atık türlerine göre en yakın toplama noktalarını filtreleme ve navigasyon başlatma.
-*   **1.5. Halka Açık Sorun Haritası (Public Issue Map)**:
-    *   *Map-First + Türkiye Geneli Başlangıç*: Vatandaş ana sayfada (`/`) doğrudan public haritayı görür. Harita ilk açıldığında **Türkiye geneli** (düşük zoom, il bazlı özet cluster'lar) gösterilir. Kullanıcı zoom yaptıkça ve haritayı kaydırdıkça sistem otomatik olarak il → ilçe → mahalle → sokak seviyesine iner.
-    *   *Serbest Keşif + Dinamik Yükleme*: Veriler BBOX + zoom seviyesine göre dinamik yüklenir. Düşük zoom'da büyük cluster'lar, yüksek zoom'da tekil fuzzied pinler görünür. Leaflet.markercluster ile istemci tarafında kümelenme yapılır.
-    *   *Detay Popupları & Filtreleme*: Kategori, tarih ve destek sayısına göre filtreleme, pin popup'ında vatandaş ad-soyad maskeleme ve "+1" buton entegrasyonu.
-    *   **Statik İçerikler (Modal)**: Hakkımızda, SSS, Gizlilik Politikası, KVKK, Kullanım Koşulları ve İletişim sayfaları ayrı tam sayfa olarak değil, ana harita üzerinden modal olarak açılır.
-
----
-
-### MODÜL 2: Belediye Moderasyon Modülü (Muni Moderation)
-Vatandaştan gelen tüm raporların ilk karşılandığı, süzüldüğü ve yönlendirildiği kontrol merkezidir.
-
-*   **2.1. İnceleme ve Yönlendirme Kuyruğu**:
-    *   `pending`, `moderation` ve `reopened` durumundaki raporları öncelik, kategori, mahalle ve "+X Destekçi" (support_count) sayısına göre filtreleme/sıralama ("En Çok Desteklenen" sıralaması mevcuttur).
-    *   *Toplu İşlem*: Birden fazla yeni raporu tek tıkla ilgili müdürlüğe havale etme.
-*   **2.2. Mükerrer Rapor Konsolidasyonu**:
-    *   Aynı konumun 50 metre yarıçapında ve aynı kategoride son 24 saatte açılmış işlerin listelenmesi.
-    *   Yeni raporu "Mükerrer" işaretleyip ana iş emriyle ilişkilendirerek kapatma; ana iş çözüldüğünde mükerrer kayıtların da otomatik kapanması.
-*   **2.3. Akıllı Havale ve Dağıtım**:
-    *   Sistem yönlendirme kurallarına göre varsayılan birincil müdürlüğü önerme.
-    *   Çok müdürlüklü sorunlarda "İkincil Müdürlükleri" seçerek bilgi logu oluşturma.
-    *   SLA öncelik çarpanlarının belirlenmesi (Düşük = x1.5 SLA / Normal = x1.0 SLA / Yüksek = x0.5 SLA / Acil = x0.25 SLA / **Kriz = x0.1 SLA — 7/24 kesintisiz**).
-*   **2.4. Halka Açık Görünürlük Yönetimi (Public Visibility Management)**:
-    *   *Gizle/Göster Kontrolü*: Raporları public haritadan gizleme/gösterme (`is_public_visible` toggle) ve zorunlu gizleme gerekçesi (KVKK, uygunsuz içerik vb.) dropdown'u.
-    *   *Görsel ve Denetim Kontrolü*: Fotoğrafları rapordan bağımsız olarak ayrı yönetebilme/gizleyebilme; tüm public görünürlük değişikliklerinin `PUBLIC_VISIBILITY_CHANGED` denetim loguyla izlenmesi.
-
-
----
-
-### MODÜL 3: Saha ve İş Yönetim Modülü (Field & Task Operations)
-Müdürlük havalesinden saha ekibinin işi tamamlamasına ve şef onayına kadar geçen tüm operasyonel süreci yönetir.
-
-*   **3.1. Müdürlük İş Akışı Yönetimi (`muni_department_manager`)**:
-    *   İş emirlerini şefe atama veya şefi bypass edip doğrudan saha personeline atama.
-    *   *Bypass Onay Kuralı*: Doğrudan atamalarda şef devre dışı kalır, iş bittiğinde onay doğrudan müdüre düşer.
-    *   *Müdür İncelemesi (Circuit Breaker)*: Şef tarafından 3 kez fotoğraf reddi alan veya re-dispatch ping-pong sınırını aşan işler için eskalasyon yönetimi. Müdür 4 aksiyondan birini alır: `force_resolve` (zorla kapat), `reassign_worker` (şefin ekibinin havuzuna gönder, ret sayacı sıfırlanır), `manual_approval` (eksiklikleri kabul edip kapat) veya `reject` (gerekçeli iptal).
-    *   *Abonelik Askı Modu Yetkileri (402 Grace Period)*: 402 abonelik süresi dolduğunda girilen 7 günlük "salt-tamamlama" süresi boyunca sıfırdan yeni iş/rapor açılamazken, sahada kilitlenme yaşanmaması için departman yöneticileri mevcut işlerin saha koordinasyonunu sağlamak adına **"Mevcut İşi Yeniden Atama (Re-assign)"** yetkisine sahip olmaya devam eder.
-    *   *IoT Kaynaklı İş Dağıtım Akışı*: Belediye bazlı tanımlanmış akıllı donanımlardan (çöp/geri dönüşüm sensörleri) gelen telemetri verilerinin, doluluk oranı %85'i aştığında veya arıza durumunda moderasyon gerektirmeksizin doğrudan belediye adminin entegrasyon formunda belirlediği hedef müdürlüğün havuzuna (örn. Temizlik İşleri) (`dispatched_to_department`) iş emri olarak otomatik yönlendirilmesi.
-*   **3.2. Ekip Şefliği Planlama ve QA (`muni_team_chief`)**:
-    *   *OSRM Rota Optimizasyonu*: Sürükle-bırak Günlük Plan ekranı üzerinden personellerin günlük rotalarını harita üzerinde en kısa mesafeye göre dizme.
-    *   *Fotoğraf Kanıt Onayı & Geofence Bypass*: Personel fotoğraflarını GPS konum ve zaman damgasıyla (exif) denetleme. Konum sapması durumunda şefe iletilen "Geofence Bypass Talebi"ni (EXIF kanıt ve gerekçeyle) onaylayıp resmi koordinatı güncelleyebilme yetkisi.
-    *   *Kalite Denetim (QA) Çevrimi*: Vatandaşın 1-2 yıldız verdiği işleri şefin QA kuyruğuna düşürerek "Çözümü Onayla" veya "İşe Döndür" kararı alma. **QA SLA Kuralı:** Şefin QA kuyruğunda bekleyen işleri incelemek için 5 iş günü (Business Days) süresi vardır. Bu süre dolduğunda arka plan servisi işi otomatik olarak "Çözümü Kesinleştir" olarak işaretler ve kuyruktan kaldırır.
-*   **3.3. Mobil Saha Uygulaması (`muni_worker`)**:
-    *   *Offline-First (MMKV/SQLite)*: Çevrimdışıyken iş başlatma, fotoğraf yükleme ve not ekleme işlemlerini yerel kuyruğa alma; internet geldiğinde Idempotency kurallarıyla otomatik eşitleme (Sync). **Concurrency Yönetimi:** İstemci internete bağlandığında eşitleme yaparken `409 Conflict` (sürüm uyuşmazlığı) hatası alırsa, yerel taslağı silmeyip korur ve personeli uyarıp işi otomatik olarak uyuşmazlık havuzuna yönlendirir.
-    *   *Senkronizasyon Uyuşmazlık Havuzu*: Personel çevrimdışıyken tamamladığı iş, o esnada (örneğin merkezden) başkasına atanırsa veri kaybı ve emek kaybı yaşanmaması için sunucu tarafında bir **"Senkronizasyon Uyuşmazlık Havuzu"** (`dispute_logs` tablosu) oluşturulur. Sistem bu paketi silmeyip şefin onay ekranına "Manuel Çakışma Çözümü" uyarısıyla sunar. Şef çakışan kayıtları inceleyip personelin emeğini ("Hak Edişi Onayla") onaylama veya reddetme yetkisine sahiptir. **Double Payout Alert Kısıtı:** Şef çakışmayı onaylamak istediğinde, eğer ana iş emrinden ötürü diğer personele hak ediş puanı zaten yazılmışsa, panel üzerinde HSL Danger Red renkli bir uyarı şeridi belirecektir. Şef bu uyarıya rağmen onaylarsa, onay türü `approved_override` olarak denetim geçmişine yazılır ve personelin hanesine performans hak edişi asenkron işlenir.
-    *   *Geofence Engeli ve Bypass*: İş koordinatına 50 metreden uzak mesafede olan personelin "İşi Bitir" butonunu kilitleyen geofence doğrulaması. Sapma durumunda şefe "Geofence Bypass Talebi" gönderebilme arayüzü.
-    *   *Vardiya Kapatma ve Auto-Handover*: Personel vardiyayı kapattığında active `in_progress` işlerin şef havuzuna devredilmesi. 8 saat GPS hareketsizliği veya 12 saat açık vardiya durumunda arka planda otomatik vardiya kapatma (Auto-Handover) tetiklenmesi.
-
----
-
-### MODÜL 4: Belediye Sistem Yönetim Modülü (Muni Admin)
-Belediyenin kendi parametrelerini, kurallarını ve saha organizasyonunu yönettiği admin konsoludur.
-
-*   **4.1. Organizasyon ve İK Yapılandırma**:
-    *   Müdürlüklerin eklenmesi, kısa kodlarının belirlenmesi.
-    *   Ekiplerin kurulması, şef ve saha çalışanlarının atanması, davet maillerinin yönetimi.
-*   **4.2. Kategori ve Akıllı SLA Yönetimi**:
-    *   Kategori bazlı fotoğraf zorunluluğu, risk skorları, varsayılan müdürlük atamaları ve "Public Haritada Görünür mü?" toggle alanı.
-    *   *Çalışma Saatleri SLA*: Mesai saatleri dışındaki ve hafta sonlarındaki sürelerin SLA sayacından otomatik düşülmesi.
-    *   *Acil/Kriz Durum Bypass'ı*: `Acil` veya `Kriz` öncelikli iş emirlerinde bu muafiyet tamamen bypass edilerek **7/24 kesintisiz SLA sayacı** işletilir ve belediyenin hayati olaylara müdahale süresi gecikmeksizlik denetlenir.
-
-*   **4.3. Kriz Masası Canlı Haritası**:
-    *   Afet durumunda paylaşılan panik sinyallerini gerçek zamanlı haritada ısı haritası ve kümelenmiş pinlerle izleme. Afet modunda ana sayfadaki (`/`) public harita üzerinde otomatik olarak afet katmanı (toplanma alanları, tahliye rotaları, açık panik sinyalleri) aktif hale getirilir.
-    *   Toplu sinyal kapatma ve müdahale yönetimi.
-*   **4.4. Otomasyon ve Entegrasyon**:
-    *   *Periyodik İş Takvimi (Scheduler)*: Cron ifadeleriyle rutin/bakım işlerinin otomatik üretilmesi (Çakışma korumasıyla mükerrer iş engellenir).
-    *   *Dinamik IoT Entegrasyonu ve Payload Eşleştirme (Self-Service Payload Mapping)*: Belediyenin kullandığı farklı marka/model akıllı cihazların (çöp, geri dönüşüm vb.) gönderdiği değişken JSON verilerini KENTİM standart şemasına dönüştürecek alan eşleştirmelerinin (GUI Mapper) ve izole JavaScript parser betiklerinin (Sandbox JS Parser) belediye admini tarafından tanımlanması, API anahtarlarının yönetimi ve hata loglarının takibi. **Sandbox Güvenlik ve Fastify API Decoupling:** Güvenlik ve CPU kilitlenmesi risklerini önlemek için parser'a girmeden önce ham payload boyutu **maksimum 10KB** ile sınırlandırılır. Parser motorunun çalıştırılması API thread'inden tamamen ayrıştırılmıştır; veriler **PostgreSQL unlogged tablosu** (`iot_telemetry_queue`) üzerine `INSERT` + `pg_notify` mekanizmasıyla Warm Worker Isolate Havuzunda (V8 Sandbox: max 50ms CPU süresi, 16MB bellek) arka planda asenkron işlenir. 
-*   **4.5. Dinamik Özel Rapor Oluşturucu (Custom Report Builder)**:
-    *   *Sürükle-Bırak Tasarım Motoru*: `muni_admin` veya yetkilendirilmiş rollerin; boyutlar (kategori, mahalle, öncelik, personel, kronik zinciri, müdürlük) ve metrikler (SLA uyum %, ortalama çözüm süresi, memnuniyet ortalaması, iş sayısı) arasında dinamik pivot şablonlar oluşturması.
-    *   *Zamanlanmış Rapor Göndericisi (Scheduler)*: Oluşturulan özel şablonların otomatik e-posta gönderimine bağlanması (Haftalık/Aylık).
-    *   *Read-Replica Entegrasyonu*: Raporlama yükünün canlı operasyonel DB'yi yormasını önleyen okuma replikası bağlantı katmanı.
-*   **4.6. Denetim Günlüğü (Audit Logs Visualizer) & Lokasyon Yönetimi**:
-    *   *Denetim Logu Vizörü (`/admin/audit-logs`)*: Belediye düzeyinde `audit_logs` tablosundaki JSONB alanlarını (güncelleme öncesi `payload_old` ve güncelleme sonrası `payload_new`) görselleştiren **Visual JSONB Diff Viewer** arayüzü. Bu arayüz, değişen alanları yeşil (eklenen) ve kırmızı (silinen/değişen) renk kodlu diff görünümünde listeler. Etkinlik türüne (`event_type`), iş emri UUID'sine, tarih aralığına, IP adresine veya indeksli `citizen_id` kolonuna göre sayfa bazlı hızlı arama ve filtreleme sunar.
-    *   *Dinamik Lokasyon Bağlama:* Saha organizasyonu oluşturulurken veya belediyenin hizmet mahalle sınırları düzenlenirken, dropdown verileri doğrudan Central SaaS DB'deki coğrafi lokasyon yapısı üzerinden dinamik olarak çağrılır.
-
----
-
-### MODÜL 5: Central SaaS Yönetim Modülü (Central Admin)
-Tüm belediyeleri koordine eden, abonelik ve lisans takibi yapan, global ayarları yöneten en üst seviyedeki platform yönetim panelidir.
-
-*   **5.1. Multi-Tenant Belediye Yönetimi**:
-    *   Yeni belediyelerin sisteme eklenmesi, API anahtarlarının ve abonelik başlangıç/bitiş tarihlerinin takibi.
-    *   Abonelik bitişinde ilgili belediyeyi otomatik **kısıtlı salt-okunur moda** alma.
-    *   Central Admin belediye listesinde "Public Harita Aktif mi?" sütununun ve belediye detayında public harita ayarları (aktif/pasif durumu, varsayılan görünürlük politikası) kısayollarının sunulması.
-*   **5.2. Global Veri Ağacı**:
-    *   Global kategorilerin, risk puanlarının ve global kategoriler için default public görünürlük durumunun (`default_public_visible: true|false` - central deny rule) yönetimi.
-    *   Türkiye lokasyon hiyerarşisinin (bölge, il, ilçe, mahalle, sokak) CSV ile toplu yönetimi.
-*   **5.3. Sistem Sağlığı & Heartbeat**:
-    *   *Çift Yönlü Sağlık Denetimi:* Central Health Monitor motoru üzerinden hem merkezi altyapı bileşenlerinin hem de kayıtlı belediyelerin backend sunucu sağlık durumlarının izlenmesi.
-    *   *Aktif Polling & Heartbeat:* 1 dakikalık döngülerle belediye `/ready` endpoint'lerinin polling ile sorgulanması (veritabanı, `pg_listener_active` (LISTEN/NOTIFY worker durumu), disk doluluk kontrolü) ve gelen pasif `/heartbeat` push sinyallerinin takibi. Çöken sunucular için central panelde anlık "DOWN / UNREACHABLE" uyarılarının üretilmesi.
-*   **5.4. Afet Modu Tetikleyicisi**:
-    *   Seçili belediyelerde veya tüm ülkede "Afet Modu" sinyali göndererek vatandaş haritalarında acil durum butonunu öne çıkarma ve toplanma alanları katmanını aktif etme.
-*   **5.5. Central Kullanıcı Yönetimi**:
-    *   Merkez teşkilatı içerisindeki diğer `central_admin` ve salt-okunur yetkili `central_moderator` kullanıcı hesaplarının oluşturulması, rollere atanması ve pasife alınması (fiziksel silme engeli) işlemlerini yönetir.
-*   **5.6. Yönetici Sunum Raporları (Executive Presentation-Ready Reports)**:
-    *   *Karşılaştırmalı Karar Destek Analitiği*: Tüm belediyelerin SLA uyum performanslarını, iş hacimlerini, bütçe projeksiyonlarını ve vatandaş memnuniyet puanlarını karşılaştırmalı olarak meclis ve yönetim kurullarına sunmaya hazır vektörel şık grafiklerle bir araya getirme.
-    *   *Konsolidasyon Motoru*: RLS sınırlarını koruyarak her belediyenin verilerini asenkron olarak central analytics DB'ye aktaran ETL pipeline'ı.
-    *   *Gelişmiş Sayfalama (Pagination)*: Büyük ölçekli belediye verilerinin listelenmesinde istemci ve sunucu bellek tükenmelerini engelleyen sayfa/limit/cursor sayfalama altyapısı.
-*   **5.7. Global Denetim Günlüğü Vizörü & Türkiye Coğrafi Sözlük Yönetimi**:
-    *   *Global Audit Log Arayüzü (`/central/audit-logs`)*: Platform genelinde SaaS yöneticilerinin yaptığı lisans dondurma, yeni belediye kaydetme veya global risk kategorilerini düzenleme gibi kritik eylemlerin JSONB diff visualizer ile takibi.
-    *   *Türkiye Coğrafi Lokasyon Hiyerarşisi Modülü*: 81 il ve 973 ilçeyi barındıran `turkey_locations_seed.sql` veri yapısını, belediye kayıt arayüzlerinde dinamik olarak binding eden ve dropdown seçimlerinde il seçimine göre ilgili ilçeleri API üzerinden getiren (`GET /v1/central/locations/hierarchy`) lokasyon sözlük servisidir.
-*   **5.8. Statik İçerik Yönetimi**:
-    *   *Merkezi İçerik Editörü*: Vatandaş arayüzünde (`/about`, `/privacy`, `/kvkk` vb.) gösterilen statik sayfaların başlık ve içeriklerinin (`central_static_contents` tablosu) Markdown destekli bir panelden yönetilmesi.
-    *   *Anlık Güncelleme*: Değişikliklerin `PUT /v1/central/static-contents/:key` ile kaydedilmesi ve public API'ye (`GET /v1/public/static-contents/:key`) anında yansıtılması.
-
-
----
-
-### MODÜL 6: Proje Çekirdeği ve Veri İzolasyon Modülü (Core & IAM)
-Sistemin veritabanı seviyesindeki tutarlılığını, rollerin hiyerarşisini ve kiracı izolasyonunu sağlayan temel altyapı modülüdür.
-
-*   **6.1. Veri İzolasyon Motoru (Multi-Tenancy & RLS)**:
-    *   PostgreSQL Row-Level Security (RLS) ile `tenant_id` bazlı satır kilitlenmesi.
-    *   ORM seviyesinde otomatik sorgu kapsamı (Query Scoping) ile izinsiz veri erişiminin engellenmesi.
-*   **6.2. Eşzamanlılık ve Tutarlılık Kontrolü**:
-    *   Kayıt güncellemelerinde `version` kontrolü (Optimistic Locking) ile `409 Conflict` yönetimi.
-    *   `POST` / `PATCH` işlemlerinde mükerrerliği önleyen `x-idempotency-key` (24 saatlik) doğrulaması.
-*   **6.3. Rol Bazlı Yetkilendirme (RBAC Middleware)**:
-    *   `citizen` rolünden `central_admin` rolüne kadar olan 9 rolün sayfa ve API seviyesindeki yetkilerinin kontrolü.
-    *   **Genişletilmiş `ROLE_CHANGE_CLEANUP` Kuralı:** Rolü değişen veya pasife alınan her kullanıcı için hiyerarşik iş devri geçerlidir:
-        *   Müdür pasife alınırsa → işler `muni_admin` havuzuna.
-        *   Şef pasife alınırsa → `in_progress` ve `assigned_to_team` durumundaki işler müdür havuzuna (`dispatched_to_department`); `pending_chief_approval` işlerinin onay yetkisi müdüre geçer.
-        *   **Saha Personeli (`muni_worker`) pasife alınırsa →** `in_progress` ve `assigned_to_worker` işleri otomatik `assigned_to_team` (şef havuzu) durumuna çekilir; eğer iş müdür bypass ataması ile gelmişse (`is_manager_bypassed = true`) doğrudan `dispatched_to_department` (müdür havuzu) durumuna iade edilerek sahibine döner ve `is_manager_bypassed = true` flag'i korunur. `pending_chief_approval` durumundakiler ise atanan personel alanı pasifleşmiş olarak şef onay kuyruğunda kalmaya devam eder.
-*   **6.4. Halka Açık Harita Veri Güvenliği (Public Read RLS & Fuzzing)**:
-    *   *Satır Bazlı Güvenlik (RLS)*: Anonim `GET /v1/public/reports` istekleri için yalnızca `is_public_visible = true` ve `status NOT IN ('pending', 'rejected')` durumundaki satırları sunan veritabanı RLS politikası (`public_map_read_policy`).
-    *   *Koordinat Fuzzing & Görünüm Katmanı*: `public_work_orders_view` üzerinden veri süzme; tam konum yerine ±0.0005° (yaklaşık 50 metre) fuzzing (sapma) uygulanmış `approximate_coordinates` projeksiyonu; kişisel verilerin (citizen_id, telefon, e-posta) view seviyesinde engellenmesi.
-*   **6.5. GDPR / KVKK Denetim Logu Anonimleştirme Motoru**:
-    *   Vatandaş hesap silme (`DELETE /citizen/account`) talebi onaylandığında; `work_orders`, `support_votes` ve `citizen` (Central DB) tabloları standart anonimleştirme kurallarıyla temizlenir.
-    *   **Denetim Logu Geçmişi Maskeleme (Yeni):** `audit_logs` tablosundaki `old_value` ve `new_value` alanları, silinmeye onay verilen vatandaşa ait kayıtlara indeksli `citizen_id` kolonu üzerinden filtre uygulanarak asenkron regex işleminden geçirilir. Bu indeks sayesinde tam tablo taraması (Full Table Scan) bypass edilerek DB kilitlenmesi önlenir. Telefon numaraları, T.C. kimlik numaraları, e-posta adresleri ve ad-soyad alanları `[KİŞİSEL VERİ SİLİNDİ]` ile maskelenir. Bu işlem ana silme transaction'ından bağımsız asenkron bir job olarak çalışır ve tamamlandığında `gdpr_requests` tablosundaki talep kaydı `completed` olarak güncellenir. **DB Yükü ve Kilit Engelleme:** Bu regex tarama ve güncelleme işlemi, veritabanının kilitlenmesini ve performans kaybını önlemek için **maksimum 500 satırlık paketler (chunks)** halinde ve her paket güncellendikten sonra **100ms gecikme (delay)** eklenerek çalıştırılır.
-
----
-
-### MODÜL 7: Yardımcı Sistem Servisleri Modülü (System Services)
-Kullanıcı etkileşimini artırmak ve arka plan temizlik işlerini yürütmek için sunucu tarafında çalışan servislerdir.
-
-*   **7.1. Bildirim Dağıtıcısı (Notification Dispatcher)**:
-    *   Tetikleyici olaylara (Yeni rapor, iş atandı, fotoğraf reddedildi, SLA kritik vb.) bağlı olarak vatandaşa ve personele SMS, Push veya E-posta kanallarından anlık bildirim iletimi.
-*   **7.2. Medya Saklama & Arşivleme Pipeline (Data Retention)**:
-    *   İşi kapatılmış görsellerin 6 ay sonra sıkıştırılarak optimize edilmesi (boyut küçültme).
-    *   1 yıl sonra kapatılan iş görsellerinin sunucudan otomatik silinmesi.
-    *   3 yılını dolduran metinsel kayıt ve denetim loglarının veritabanından soğuk depolamaya (S3 / Cold Storage) taşınması.
-*   **7.3. Halka Açık Harita Önbellek Servisi (Public Map Cache Service):**
-    *   *Yapı:* PostgreSQL üzerinde `public_map_cache` adında WAL yazmayan unlogged tablo (`tenant_id` + `bbox_hash` bazlı, 30s TTL) ile public rapor verilerinin hızlı önbelleğe alınması sağlanmıştır.
-    *   *Invalidation:* Raporun `status`, `is_public_visible` veya `support_count` alanları değiştiğinde ilgili tenant'ın cache satırlarının `DELETE WHERE tenant_id = :tenant_id` ile anında temizlenmesi (cache invalidation) ve CDN purge işlemleri otomatik tetiklenmektedir.
-    *   **Mevcut Durum:** Bu altyapı ve cache invalidation mekanizmaları ile CDN purge entegrasyonu tamamen tanımlanıp sisteme entegre edilmiştir.
-
----
-
-## 3. Modüller Arası Kritik Veri Akışı Örneği
-
-Bir vatandaş raporunun (Yol Hasarı) oluşturulup kapatılma sürecindeki modüller arası veri akışı:
-
-```
-[Modül 1: Vatandaş Etkileşim]
-         │ (Haritadan konum seçildi, fotoğraf yüklendi, Geofence doğrulandı)
-         ▼
-[Modül 6: Proje Çekirdeği & RLS] ──► (tenant_id tespit edildi, UUIDv4 atandı, yazma izni verildi)
-         │
-         ▼
-[Modül 2: Belediye Moderasyon] ──► (Mükerrer kontrolü yapıldı, öncelik atandı, müdürlüğe havale edildi)
-         │
-         ▼
-[Modül 3: Saha ve İş Yönetimi] ──► (Müdür şefe atadı ──► Şef rotayı optimize edip işçiye atadı)
-         │
-         ▼
-[Modül 3: Mobil Saha (Offline/Geofence)] ──► (İşçi işi yaptı, 50m geofence ile kanıt yükledi)
-         │
-         ▼
-[Modül 3: QA & Fotoğraf Onayı] ──► (Şef fotoğrafları onayladı ──► Durum 'resolved' oldu)
-         │
-         ▼
-[Modül 7: Yardımcı Servisler] ──► (Vatandaşa SMS/Push gitti ──► 6 ay sonra görseller sıkıştırıldı)
-```
-
-*MVP Sürümü — KENTİM Modüler Yapı Belgesi*
-
-## EK MODÜL: Public Harita ve İlgili Alt Modüller
-
-### 1.5. Public Sorun Haritası (Public Issue Map)
-- Amaç: Vatandaşın şehir genelindeki tüm raporları ve iş emirlerinin durumunu şeffaf biçimde harita üzerinden izlemesi.
-- Harita Altyapısı: Vatandaş haritayı serbestçe keşfeder. Viewport (BBOX) + zoom seviyesine göre dinamik veri yüklenir; Leaflet.markercluster ile kümelenme.
-- Pin popup içeriği (kişisel veri YOK): kategori, kısa başlık, durum rozeti, oluşturulma tarihi, foto thumbnail (moderatör onaylıysa), destek sayacı ve "Bu sorun beni de etkiliyor" butonu.
-- Isı Haritası / Pin Toggle, filtreler (kategori, durum, tarih), view-based API çağrıları.
-
-### 1.2 (güncelleme). Raporlama Motoru — Public entegrasyon
-- Pin bırakıldığı anda sistem 50–100m yarıçapındaki public raporları API'den çeker ve kullanıcıyı uyarır; eşleşme durumunda "+1" butonu gösterilir, kullanıcı "hayır" derse form devam eder.
-
-### 1.3 (güncelleme). Katılım ve Geri Bildirim
-- "+1 Beni de Etkiliyor" mekanizması: resolved olmayan raporlara hesaplı kullanıcılar destek verebilir; destekler `support_votes` tablosunda tutulur ve `work_orders.support_count` denormalize sayacı trigger ile güncellenir.
-
-### 2.4. Public Görünürlük Yönetimi (Yeni Alt Modül)
-- Moderatörler raporu public haritadan gizleyebilir/tekrar gösterebilir; fotoğraf görünürlüğü ayrı yönetilir; otomatik hassas veri önerisi (regex) moderatöre sunulur.
-
-### 7.3. Public Harita Cache Servisi (Yeni Alt Modül)
-- Public pin verisi PostgreSQL `public_map_cache` unlogged tablosunda `tenant_id` ve `bbox_hash` bazlı 30s TTL ile tutulur; iş emri `status` veya `is_public_visible` değiştiğinde belediyenin (tenant) public cache satırları transactional delete ile anında temizlenir (invalidate edilir).
-
-Detaylı değişiklikler için proje ve mimari belgelerindeki public-read politika, DB alanları ve API tanımları takip edilmelidir.
-
----
-
-## Modüler Kapsam Sınırları (MVP) ve V1 Yol Haritası
-
-> Detaylı MVP / V1 ayrımı ve tüm özelliklerin hangi sürümde yer alacağı için bkz. `proje.md` → **KENTİM Sürüm Yol Haritası** bölümü.  
-> **Yönetim Notu:** Public Web Yol Haritası (MVP ve V1) sadece Merkez Panel (`central_admin`) üzerinden yönetilebilir. Belediye paneli bu içeriğe erişemez. Detay için `yapı.md` → 3.11 Public Web Yol Haritası Yönetimi ekranına bakınız.
-
-Sistemdeki 7 ana fonksiyonel modülün geliştirme aşaması, kapsam bütünlüğünü korumak ve hızlı devreye alımı sağlamak için net olarak fazlandırılmıştır:
-
-### 1. MVP Modüler Proje Kapsamı ve Dağılımı
-
-Tüm gelişmiş ve operasyonel modüller doğrudan MVP kapsamında devreye alınmıştır ve tamamı zorunludur:
-
-| Modül | Core MVP Kapsamındaki Alt Modüller (Zorunlu ve Tamamı Dahildir) |
-| :--- | :--- |
-| **Modül 1: Vatandaş Etkileşim** | 1.1 Profil (Temel), 1.2 Raporlama Motoru (Konum/Foto), 1.3 Geri Bildirim ve Reopen, 1.3 Fikir Önerisi (E-posta Onaylı Oylama), 1.4 Acil/Afet (Toplanma Rotaları, asenkron panik debouncer), 1.5 Public Harita, Geri Dönüşüm Haritası, **kronik sorunlar zinciri (`parent_reopened_work_order_id`)**. Tamamı **Leaflet (Leaflet Map)** entegrasyonu ile çalışır. |
-| **Modül 2: Moderasyon** | 2.1 İnceleme ve Yönlendirme Kuyruğu, 2.2 Mükerrer Rapor Konsolidasyonu, 2.3 Akıllı Havale, 2.4 Görünürlük Kontrol. AI Tabanlı Otomatik Fotoğraf Kategorizasyonu, Sesli Yanıt Sistemi (IVR) Şikayet Entegrasyonu. Listelerde **cursor/offset bazlı sayfalama (pagination)** kullanımı. |
-| **Modül 3: Saha ve İş Yönetimi** | 3.1 Müdürlük İş Akışı, 3.2 Ekip Şefliği Planlama, 3.3 Mobil Saha Uygulaması (Offline Görev ve Geofence, **PostGIS geofence sürüm kilidi `boundary_version_id` ve `municipal_boundary_versions` ilişkisi**), 3.2 OSRM Rota Optimizasyonu motoru, Senkronizasyon Uyuşmazlık Havuzu (`dispute_logs`) görsel arayüzü (çevrimdışı auto-handover local timestamp istisnası dahil). |
-| **Modül 4: Belediye Admin** | 4.1 İK Yapılandırma, 4.2 Akıllı SLA Tanımları, 4.3 Kriz Masası Canlı Haritası, 4.4 Otomasyon ve Hazır JS/IoT Webhook Parser Sandbox, 4.4 GUI Tabanlı Drag-and-Drop IoT Payload Mapper Görsel Editörü, **4.5 Dinamik Özel Rapor Oluşturucu (Custom Report Builder) ve e-posta zamanlayıcı (Read replica destekli).** |
-| **Modül 5: Central SaaS** | 5.1 Multi-Tenant Belediye Yönetimi, 5.2 Global Veri Ağacı, 5.3 Sistem Sağlığı & Heartbeat Grafikleri, 5.4 Global Afet Sinyali tetikleyicisi arayüzü, 5.5 Central Kullanıcı Yönetimi, **5.6 Yönetici Sunum Raporları (Executive Presentation-Ready Reports) PDF/XLSX motoru (analytical DB destekli).** |
-| **Modül 6: Proje Çekirdeği** | 6.1 RLS İzolasyonu, 6.2 Eşzamanlılık (Optimistic Lock), 6.3 RBAC Yetkilendirme Middleware katmanı, 6.4 RLS Fuzzing, **6.5 GDPR log regex maskeleme motoru + `/gdpr/requests/:id/process` tetikleme endpoint'i**. 6.5 Admin arayüzü. |
-| **Modül 7: Yardımcı Servisler** | 7.1 Bildirim Dağıtıcısı (SMS/Push), 7.2 Medya Sıkıştırma/Arşiv, 7.3 `public_map_cache` Önbellek Servisi, 7.1 Dead Letter Queue (DLQ) bildirim arayüzü, gelişmiş e-posta şablon motoru. |
-
-### 2. Modül 1.3 Altında Analitik Takibi ve Event Entegrasyonu
-* Vatandaş Etkileşim Modülü altındaki **1.3 Katılım ve Geri Bildirim** ve **1.5 Public Harita** bileşenlerinde, kullanıcı deneyimini ölçümlemek amacıyla her modal geçişinde ve butona tıklanma olayında analitik sunucusuna asenkron push (analytics pipeline) tetiklenir:
-  * Rapor oluştururken konum seçildiğinde `GET /public/reports?bbox=&radius=100m` önleyici mükerrer araması yapıldıktan sonra arayüze mükerrer kartı düşerse `duplicate_check_triggered` event'i fırlatılır.
-  * Kullanıcı "+1 Beni de Etkiliyor" butonuna bastığında `support_vote_added` event'i tetiklenir.
-  * Vatandaş `resolved` olmuş rapora 1-2 yıldız verip QA kuyruğuna tetikleme yaptığında `qa_loop_triggered` event'i sisteme push edilir.
-
-**Sonuç:** KENTİM modüler mimarisi ve tüm fonksiyonel alt bileşenleri tam standartta belgelenmiş olup, projenin modüler yapısında hiçbir eksiklik kalmamıştır.
-
-