agent-enderun 1.0.7 → 1.0.8

package/docs/is_akislari.md

@@ -1,902 +0,0 @@
-# KENTİM — Detaylı İş Akışları ve Süreç Algoritmaları Kılavuzu (MVP Sürümü)
-
-Bu belge, KENTİM (Belediye Vatandaş Etkileşim ve İş Yönetim Sistemi) platformunda çalışan **tüm ana iş akışlarını, durum makinesi geçişlerini, eskalasyon kurallarını ve operasyonel algoritmaları** adım adım ve görsel şemalarla tanımlamaktadır.
-
----
-
-## 1. İş Emri Durum Makinesi (State Machine) Matrisi
-
-Sistemdeki her iş emri (Work Order) aşağıdaki durum geçiş tablosuna sıkı sıkıya bağlıdır. Yetkisiz bir rolün durumu değiştirmesi API katmanında (RBAC Middleware) engellenir.
-
-| Mevcut Durum | Tetikleyici Eylem | Yetkili Rol | Yeni Durum | Sistem Arka Plan Eylemi |
-| :--- | :--- | :--- | :--- | :--- |
-| **- (Başlangıç)** | Vatandaş Rapor Gönderimi | `citizen` / Anonim | **pending** | UUIDv4 atanır. PostGIS Geofencing çalışır, `tenant_id` belirlenir. |
-| **pending** | Spam / Kapsam Dışı Kontrolü | `system` | **moderation** / **rejected** | reCAPTCHA v3 skoru < 0.5 ise veya coğrafi sınır dışındaysa otomatik `rejected` olur. |
-| **moderation** | Müdürlüğe Yönlendirme | `muni_moderator` / `muni_admin` | **dispatched_to_department** | SLA sayacı başlatılır (Normal şartlarda çalışma saatleri/hafta sonu düşülür; ancak `Acil/Kriz` öncelikli işlerde **7/24 kesintisiz SLA sayacı** tetiklenir). Bildirim gönderilir. |
-| **moderation** | Raporu Reddetme | `muni_moderator` / `muni_admin` | **rejected** | Vatandaşa gerekçeli ret bildirimi (SMS/Push) gönderilir. |
-| **dispatched_to_department** | Şefe / Ekibe Havale | `muni_department_manager` | **assigned_to_team** | İş, şefin "atanmamış havuzuna" düşer. Şefe push bildirimi gider. |
-| **dispatched_to_department** | Doğrudan Personele Havale | `muni_department_manager` | **assigned_to_worker** | **Şef bypass kuralı** tetiklenir. Onay yetkisi doğrudan müdüre yazılır. **Not:** Bu kural yalnızca müdürün şefi bypass etmesi içindir. Şef kendi manuel iş emrini doğrudan personele atarsa onay yetkisi şefe kalır (bkz. proje.md F6.1). |
-| **dispatched_to_department** | Re-dispatch (Geri Yönlendirme) | `muni_department_manager` / `muni_admin` | **moderation** | Re-dispatch sayacı 1 artar, SLA çalışmaya devam eder. |
-| **dispatched_to_department** | Re-dispatch (Geri Yönlendirme) | `muni_moderator` | **moderation** | Re-dispatch sayacı artmaz (ping-pong koruması için sayılmaz), SLA çalışmaya devam eder. |
-| **assigned_to_team** | Personele Görev Atama | `muni_team_chief` | **assigned_to_worker** | Görev saha çalışanının mobil cihazına indirilir (MMKV/SQLite). |
-| **assigned_to_team** | Re-dispatch (Geri Yönlendirme) | `muni_department_manager` / `muni_admin` | **moderation** | Re-dispatch sayacı 1 artar, SLA çalışmaya devam eder. |
-| **in_progress** | İşi Tamamlama | `muni_worker` | **pending_chief_approval** | 50m geofence mesafe kontrolü yapılır. Mesafe > 50m ise personel "Geofence Bypass Talebi" (EXIF ve gerekçeyle) oluşturabilir. Şef onaylayınca koordinat güncellenir ve geofence bypass edilir. Fotoğraflı kanıtlar yüklenir. |
-| **in_progress** | Görevi Yarıda Bırakma | `muni_worker` | **assigned_to_team** / **dispatched_to_department** | İş personelden alınır. **Normal şef atamasında:** şef havuzuna (`assigned_to_team`) iade edilir. **Müdür bypass atamasında:** `dispatched_to_department` (müdür havuzu) olarak iade edilir; `is_manager_bypassed = true` flag'i korunur ve şef devreye girmez. (Vardiya kapatma esnasında `pending_chief_approval` durumundaki işler bu devir işleminden muaftır ve personelin üzerinde kalır). |
-| **in_progress** | Re-dispatch (Geri Yönlendirme) | `muni_department_manager` / `muni_admin` | **moderation** | Re-dispatch sayacı 1 artar, SLA çalışmaya devam eder. |
-| **pending_chief_approval** | Kanıtları Onayla | `muni_team_chief` / `muni_department_manager` / `muni_admin` | **resolved** | Şef onaylayabilir veya müdür/admin 'manual_approval' aksiyonu ile şef onayını bypass ederek doğrudan resolved durumuna çekebilir. Çakışan veya mobil çevrimdışıyken `409 Conflict` (sürüm uyuşmazlığı) alan iş teslimleri veritabanındaki "Senkronizasyon Uyuşmazlık Havuzuna" (`dispute_logs`) düşer. Şef çakışan kayıtları inceleyip personelin emeğini ("Hak Edişi Onayla") manuel olarak onaylayabilir; bu durumda personelin hanesine hak ediş yazılır. Vatandaşa çözüldü bildirimi ve kanıt linki gönderilir, SLA durdurulur. |
-| **pending_chief_approval** | Kanıtları Reddetme | `muni_team_chief` | **in_progress** | Ret sayacı `1` artırılır. Sayaç `>= 3` ise otomatik **pending_manager_review** olur ve müdüre eskalasyon bildirimi gönderilir. (QA Düzeltme Grace Period: şef işi reddettiğinde sisteme otomatik ek 2 saatlik veya min 4 saate yuvarlanmış SLA süresi eklenir). |
-| **pending_manager_review** | `force_resolve` — Zorla Çözüldü Yap | `muni_department_manager` / `muni_admin` | **resolved** | "Üst Yetkiyle Kapatma" logu (`force_resolve`) oluşturulur; `muni_admin` performans raporunda ayrı sütunda listelenir. Vatandaşa çözüldü bildirimi gönderilir, SLA durdurulur. |
-| **pending_manager_review** | `reassign_worker` — Personel Değiştir | `muni_department_manager` / `muni_admin` | **assigned_to_team** | İş mevcut personelden alınır; ret sayacı sıfırlanır, `is_manager_bypassed` flag'i sıfırlanır (false yapılır). İş, daha önce atanmış olan şefin ekibinin "atanmamış havuzuna" (`assigned_to_team`) düşer. Bu sayede şef kendi görünümünde işi görebilir ve yeni bir personel atar. Eğer şef de değiştirilmek isteniyorsa müdür önce şefi güncellemeli, ardından atama yapmalıdır. Müdür dilerse şef bypass kuralıyla yeni bir atama yapabilir. |
-| **pending_manager_review** | `reject` — Gerekçeli İptal | `muni_department_manager` / `muni_admin` | **rejected** | Gerekçe zorunludur. Vatandaşa ret bildirimi (SMS/Push) gönderilir; denetim loguna kaydedilir. |
-| **resolved** | Geri Bildirim: 1-2 Yıldız | `citizen` / Anonim | **resolved** (QA Modu) | İş otomatik olarak şefin **Kalite Denetim (QA)** kuyruğuna düşer. SLA sayacı `resolved` durumuna geçtiğinde zaten durdurulmuştu; QA kuyruğunda bekleme süresince **durdurulmuş hâlde kalır** (yeniden başlamaz). **QA SLA Limit ve Otomatik Çözüm:** Şefin QA kuyruğunda bekleyen işleri incelemek için maksimum 5 iş günü (Business Days) süresi vardır. Süre dolduğunda sistem otomatik olarak "Çözümü Kesinleştir" kararı vererek işi resolved olarak kapatır. Şef "İşe Döndür" kararı verirse sayaç dondurulduğu yerden devam eder; "Çözümü Kesinleştir" kararı verirse sayaç değişmez. |
-| **resolved** (QA Modu) | Yetersiz Bulma (İşe Döndür) | `muni_team_chief` | **in_progress** | Veritabanında saklanan `assigned_worker_id` referansına göre iş önceki personele iade edilir. Eğer personel sistemde halâ aktif ve aynı ekipteyse iş doğrudan o personele düşer; personel sistemden ayrılmış veya ekip değiştirmişse iş `assigned_to_team` (atanmamış) olarak şefin havuzuna geri düşer. **SLA Grace Period:** İşe döndürmede yapay SLA aşımlarını önlemek için sisteme otomatik ek 2 saatlik (veya kalan sürenin min 4 saate yuvarlanmasıyla) "QA Düzeltme Grace Period" eklenir. SLA dondurulduğu yerden devam eder. |
-| **resolved** (QA Modu) | Çözümü Kesinleştir | `muni_team_chief` | **resolved** | İş QA kuyruğundan kalkar; `resolved` statüsü korunur. SLA değişmez. |
-| **citizen_report** (`resolved` / `rejected`) | Sorun Devam Ediyor (Reopen) | `citizen` / Anonim | **reopened** | **Yalnızca** kaynak tipi `citizen_report` olan işlere uygulanır. `rejected` bir vatandaş raporu da yeniden açılabilir (moderatör yanlış reddi düzeltme imkânı sağlar). Dahili (`manual_internal`), entegrasyon (`integration`) ve periyodik (`scheduled`) kaynaklı işler vatandaş tarafından açılamaz; bu işler yalnızca amir yetkisiyle (`muni_department_manager` veya üstü) panelden manuel olarak yeniden aktifleştirilebilir ve re-open sayısı uygulanmaz. Maksimum 2 kez yeniden açılabilir; limit dolduktan sonra sistem yeni rapor oluşturulması yönünde uyarı gösterir. **Reopen SLA:** Rapor `reopened` durumuna geçtiğinde eski SLA geçmişi denetim amacıyla saklanır; **yeni SLA henüz başlamaz.** Yeni SLA süresi (standart SLA'in %50'si kadar), moderatörün işi yeniden inceleyip onaylayarak `dispatched_to_department` olarak sevk ettiği anda başlatılır. |
-| **resolved / rejected** | Kronik Arıza Bağlantısı | citizen / Anonim (2. reopen limiti sonrası) | **chronic_archived** | Eski rapor arşive alınır; `is_public_visible = false` yapılarak public haritada görünmez; SLA durdurulur. Yeni rapor `pending` olarak açılır ve eski rapora `parent_reopened_work_order_id` ile bağlanır. |
-| **Herhangi Durum (resolved hariç)** | "+1 Beni de Etkiliyor" Desteği | `citizen` (JWT — E-posta onaylı hesap zorunlu) | **(Durum Değişmez)** | `support_votes` tablosuna benzersiz `(work_order_id, citizen_id)` kaydı atılır. Anonim kullanıcılar +1 desteği veremez; işlem yalnızca JWT sağlamlığı doğrulanmış e-posta onaylı hesaplar için geçerlidir. `work_orders.support_count` PostgreSQL tabanlı debounced asenkron worker ile güncellenir (row-lock önleme); moderatör ekranına 5 dakika içinde yansıtılır. |
-| **Herhangi Durum** | Public Haritada Göster / Gizle | `muni_moderator` / `muni_admin` | **(Durum Değişmez)** | `is_public_visible` değeri güncellenir. Gizleme gerekçesi zorunludur. `PUBLIC_VISIBILITY_CHANGED` denetim logu yazılır ve ilgili önbellek satırları temizlenir. |
-| **assigned_to_worker / in_progress** | `muni_worker` Pasife Alınma | `system` (`ROLE_CHANGE_CLEANUP`) | **assigned_to_team** / **dispatched_to_department** | Personelin üzerindeki `in_progress` ve `assigned_to_worker` işleri otomatik `assigned_to_team` (şef havuzu) durumuna çekilir; eğer iş müdür bypass ataması ise 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` durumundaki işler değişmeden şef onay kuyruğunda kalır (atanan personel alanı pasifleşmiş olarak işaretlenir). Denetim loguna `ROLE_CHANGE_CLEANUP` yazılır. |
-| **moderation (Disputes kuyruğundan)** | Admin Kesin Atama | `muni_admin` | **dispatched_to_department** | Re-dispatch sayacı sıfırlanır. İş emrine `is_force_assigned = true` flag'i yazılır. Bu flag aktifken hedef müdürlük/müdür tarafından re-dispatch yapılması API katmanında engellenir (yalnızca `muni_admin` tekrar müdahale edebilir). |
-
----
-
-## 2. Görselleştirilmiş Detaylı İş Akışları (Mermaid)
-
-
-### AKIŞ 1: Vatandaş Raporlama ve Moderasyon Akışı
-Vatandaşın sorunu haritada işaretlemesiyle başlayan, arka planda PostGIS geofencing denetiminden geçerek moderatör tarafından müdürlüğe havale edildiği süreçtir.
-
-```mermaid
-sequenceDiagram
-    autonumber
-    actor C as Vatandaş (Hesaplı/Anonim)
-    participant G as Central SaaS Gateway
-    participant R as PostGIS Geofence Engine
-    participant DB as Central & Tenant DB
-    actor M as Belediye Moderatörü
-
-    Note over C,DB: 1. Önleyici Mükerrer Rapor Kontrolü
-    C->>G: Haritaya Tıkla & Konum Seç (GPS)
-    G->>DB: GET /public/reports/nearby?lat=&lng=&radius=100
-    DB-->>G: 100m Yakındaki Raporları Dön
-    alt Yakın Konumda Aktif Rapor Varsa
-        G-->>C: Bilgi Kutusu & "+1 Beni de Etkiliyor" Seçeneğini Göster
-        alt Vatandaş "+1" Butonuna Basar
-            C->>G: Raporu Destekle (+1) (JWT Yetkili)
-            G->>DB: support_votes idempotent ekle & support_count güncelle
-            G-->>C: İşlem Başarılı & Haritada Soruna Yönlendir
-        else Vatandaş "Hayır, Farklı Rapor" Der
-            Note over C,G: Normal Rapor Oluşturma Formuna Devam Edilir
-        end
-    end
-
-    Note over C,DB: 2. Normal Rapor Gönderim ve Coğrafi Sınır Akışı
-    C->>G: Rapor Formu Gönder (Konum + Kategori + Fotoğraf + reCAPTCHA)
-    G->>G: rate limiting & CAPTCHA doğrula
-    alt Doğrulama Başarısız
-        G-->>C: 429 Too Many Requests VEYA 400 Bad Request
-    else Doğrulama Başarılı
-        G->>R: Konum Koordinatını Gönder (ST_Contains)
-        R->>R: Belediye sınır poligonu eşleştirmesini sorgula
-        alt Sınır Dışı (Kapsam Dışı)
-            R-->>G: Belediye bulunamadı
-            G->>DB: Rapor durumunu otomatik 'rejected' kaydet
-            G-->>C: "Belediyemiz sınırları dışındasınız" hata mesajı
-        else Sınır İçi (Başarılı)
-            R-->>G: tenant_id = muni_a (Eşleşti)
-            G->>DB: UUIDv4 ile 'pending' durumunda rapora kaydet
-            G-->>C: Takip Kodu Üret (KENT-34-XXXX) & Başarı Sayfası
-            DB->>M: Raporu Moderasyon Kuyruğuna Ekle ('moderation')
-            M->>M: 50m mükerrer rapor kontrolü yap (Moderatör ekranı)
-            alt Mükerrer Kayıt Mevcut
-                M->>DB: Raporu 'Mükerrer' işaretle ve Ana Raporla bağla (Kapat)
-            else Tekil Kayıt (Yeni Sorun)
-                M->>DB: Birincil müdürlüğü seç & SLA öncelik ata & Yönlendir
-                DB-->>DB: SLA Sayacını Başlat ('dispatched_to_department')
-            end
-        end
-    end
-```
-
----
-
-### AKIŞ 2: Departman İçi Atama ve Saha Operasyonu Akışı
-Müdürlüğe ulaşan iş emrinin ekiplere dağıtılması, saha personeli tarafından üstlenilmesi, çevrimdışı çalışma kuralları ve geofence bariyerli tamamlama akışıdır.
-
-```mermaid
-graph TD
-    Start[İş Departmana Düştü <br/> dispatched_to_department] --> MgrDecision{Müdür Atama Kararı}
-    
-    %% Şef Atama Yolu
-    MgrDecision -->|Şefe Ata| AssignToChief[İş Şef Havuzunda <br/> assigned_to_team]
-    AssignToChief --> ChiefAssign[Şef Personele Atadı <br/> assigned_to_worker]
-    
-    %% Müdür Bypass Yolu
-    MgrDecision -->|Personele Doğrudan Ata| DirectAssign[Bypass Kuralı: <br/> assigned_to_worker <br/> Onay Yetkisi: Müdür]
-    
-    ChiefAssign --> WorkerApp[Personel Cihazına Düştü <br/> Offline Pre-fetch]
-    DirectAssign --> WorkerApp
-    
-    WorkerApp --> WorkerStart[Personel İşi Başlattı <br/> in_progress]
-    WorkerStart --> WorkerJob{Saha Çalışma Süreci}
-    
-    %% Vardiya Kapatma / Devir
-    WorkerJob -->|Vardiya Kapat / Yarıda Bırak| ShiftEnd{İşin Durumu Nedir?}
-    ShiftEnd -->|in_progress| Abandon[İş Personelden Alınır <br/> Durum: assigned_to_team]
-    ShiftEnd -->|pending_chief_approval| Exempt[Devir Muafiyeti! <br/> İş Personelde Kalır]
-    Abandon --> AssignToChief
-    
-    %% Çevrimdışı Senkronizasyon ve Çakışma Kontrolü
-    WorkerJob -->|Çevrimdışı İşi Bitir| OfflineSubmit[Çevrimdışı Kaydet]
-    OfflineSubmit --> NetworkRestore[İnternet Bağlantısı Sağlandı]
-    NetworkRestore --> ConflictCheck{Çakışma Kontrolü: <br/> İş Başkasına Atandı mı?}
-    ConflictCheck -->|Evet| DisputePool[Senkronizasyon Uyuşmazlık Havuzu <br/> Manuel Çakışma Çözümü Uyarısı]
-    ConflictCheck -->|Hayır| GeofenceCheck
-    
-    %% Çevrimiçi İşi Tamamlama
-    WorkerJob -->|Çevrimiçi İşi Bitir| GeofenceCheck{Geofence Kontrolü: <br/> Konum ile İş Mesafesi <= 50m?}
-    
-    GeofenceCheck -->|Hayır| LockForm[Formu Kilitle! <br/> 'Noktaya Yaklaşın' Uyarısı]
-    LockForm -->|Yaklaş ve Tekrar Dene| GeofenceCheck
-    
-    GeofenceCheck -->|Evet| PhotoUpload[Konum & Zaman Damgalı <br/> Fotoğraf Yükle]
-    PhotoUpload --> SubmitJob[Şef/Müdür Onayına Gönder <br/> pending_chief_approval]
-```
-
----
-
-### AKIŞ 3: Onay, Fotoğraf Reddi (Circuit Breaker) ve QA Döngüsü
-İş bitiminde sunulan fotoğrafların şef tarafından denetlenmesi, ardışık ret durumunda müdüre eskalasyon ve vatandaşın düşük puan vermesiyle tetiklenen kalite kontrol akışıdır.
-
-```mermaid
-graph TD
-    PendingApp[Şef Onay Bekleyen İş <br/> pending_chief_approval] --> ChiefReview{Şef Fotoğrafları İnceledi}
-    
-    %% Onay Yolu
-    ChiefReview -->|Kanıtlar Yeterli| Approve[İşi Çözüldü Yap <br/> resolved]
-    Approve --> CitizenRating[Vatandaş Puanlama Yapar <br/> 1-5 Yıldız]
-    
-    CitizenRating --> RatingCheck{Puan Durumu}
-    RatingCheck -->|3-5 Yıldız| Complete[İşlem Başarıyla Tamamlandı]
-    RatingCheck -->|1-2 Yıldız| QACycle[Kalite Denetim QA Kuyruğuna Düşür]
-    
-    QACycle --> ChiefQADecision{Şef QA İncelemesi}
-    ChiefQADecision -->|Çözümü Kesinleştir| Complete
-    ChiefQADecision -->|Yetersiz - İşe Döndür| ReOpenToWorker[İşi in_progress Yap <br/> Saha Personeline Bildirim Gönder]
-    ReOpenToWorker -->|Saha Personeli Düzeltir| PendingApp
-    
-    %% Ret ve Devre Kesici Yolu
-    ChiefReview -->|Kanıtlar Yetersiz| Reject[Fotoğrafı Reddet V1]
-    Reject --> IncremetCounter[Ret Sayacını 1 Artır]
-    IncremetCounter --> CounterCheck{Ret Sayacı >= 3?}
-    
-    CounterCheck -->|Hayır < 3| SendBackToWorker[İşi in_progress Yap <br/> Personele Bildirim Gönder]
-    SendBackToWorker -->|Personel Yeni Fotoğraf Yükler| PendingApp
-    
-    CounterCheck -->|Evet >= 3| CircuitBreaker[DEVRE KESİCİ TETİKLENDİ! <br/> pending_manager_review]
-    
-    CircuitBreaker --> MgrReview{Müdür Eskalasyon Kararı}
-    MgrReview -->|force_resolve <br/> Zorla Çözüldü Yap| Approve
-    MgrReview -->|reassign_worker <br/> Başka Personele Aktar| ReassignPool[İş Şefin Atanmamış Havuzuna Döner <br/> assigned_to_team · Ret Sayacı Sıfırlandı]
-    ReassignPool -->|Şef Yeni Personel Atar| PendingApp
-    MgrReview -->|reject <br/> Gerekçeli İptal Et| RejectJob[İşi Reddedildi Yap <br/> rejected]
-    MgrReview -->|manual_approval <br/> Eksiklikleri Onayı Alıp Kapat| Approve
-```
-
----
-
-### AKIŞ 4: Yeniden Yönlendirme (Re-dispatch & Ping-Pong Koruması)
-Müdürlüklerin işi kendilerine ait olmadığı gerekçesiyle başka birimlere yönlendirmesi ve bunun sonucunda oluşan ping-pong döngüsünün engellenmesi akışıdır.
-
-```mermaid
-sequenceDiagram
-    autonumber
-    actor M1 as Fen İşleri Müdürü
-    participant DB as Sistem Veritabanı
-    actor Mod as Belediye Moderatörü
-    actor Admin as Belediye Admini
-
-    M1->>DB: İş Fen İşleri'ne ait değil. Re-dispatch Et.
-    DB-->>DB: Re-dispatch sayacını 1 artır
-    DB->>Mod: İşi Gerekçesiyle Birlikte Moderatörün "Karar Bekleyenler" Kuyruğuna Döndür
-    Mod->>DB: İşi İnceledi ve Park Bahçeler Müdürü'ne Yönlendirdi
-    
-    actor M2 as Park Bahçeler Müdürü
-    M2->>DB: İş Park Bahçeler'e ait değil. Re-dispatch Et.
-    DB-->>DB: Re-dispatch sayacını 1 artır (Sayaç = 2)
-    DB->>Mod: İşi Tekrar Moderatör Kuyruğuna Gönder
-    Mod->>DB: İşi İnceledi ve Temizlik İşleri Müdürü'ne Yönlendirdi
-    
-    actor M3 as Temizlik İşleri Müdürü
-    M3->>DB: İş Temizlik İşleri'ne de ait değil! Re-dispatch Et.
-    DB-->>DB: Re-dispatch sayacını 1 artır (Sayaç = 3)
-    DB-->>DB: PING-PONG KORUMASI DEVREYE GİRDİ!
-    DB->>Admin: İşi Moderatörden alıp Adminin "Anlaşmazlık Çözüm (Disputes)" Kuyruğuna Taşır.
-    Admin->>DB: İşi İnceledi ve Temizlik İşleri'ne "Kesin Atama" Yaptı (Döngü Sonlandırıldı).
-```
-
-> **Not — `is_force_assigned` Kilidi:** Admin kesin atama yaptığında iş emrine `is_force_assigned = true` flag'i yazılır. Bu flag aktifken yeni atanan müdürlük/müdür re-dispatch yapamaz (API `403` döner). Yalnızca `muni_admin` tekrar müdahale edebilir. Re-dispatch sayacı sıfırlanır; iş sıfır sayaçla yeni müdürlüğe düşer. Akış denetim loguna `DISPUTE_RESOLVED` olarak kaydedilir.
-
----
-
-
-### AKIŞ 5: Dinamik IoT Veri Alma ve Payload Eşleştirme Akışı
-
-Her belediyenin kendi bağımsız IoT sensörlerinden (doluluk, arıza, konum vb.) gelen değişken ham JSON verilerinin, belediyenin kendi tanımladığı mapping (eşleştirme) veya JS Parser sandbox motorundan geçirilerek standardize edildiği ve otomatik iş emrine dönüştürüldüğü akıştır.
-
-```mermaid
-sequenceDiagram
-    autonumber
-    actor D as IoT Cihazı (Sensör)
-    participant GW as Central SaaS Gateway
-    participant TS as Dynamic Payload Transformer Engine
-    participant DB as Tenant DB (schema_muni_x)
-    participant SO as İş Emri Durum Makinesi (State Machine)
-
-    D->>GW: POST /v1/integrations/iot/telemetry (API Key + Ham JSON)
-    GW->>GW: API anahtarından tenant_id tespiti
-    alt Geçersiz Anahtar
-        GW-->>D: 401 Unauthorized
-    else Yetki Onaylandı
-        GW->>DB: Belediye entegrasyon ayarlarını sorgula (Config önbelleği)
-        DB-->>GW: Eşleştirme (Mapping) kuralları & Parser Script
-        GW->>TS: Ham JSON + Parser Script ilet
-        TS->>TS: V8 Sandbox içinde Custom JS betiğini çalıştır
-        alt Parser Hatası
-            TS-->>GW: Parser Error
-            GW->>DB: integration_logs tablosuna FAILED olarak kaydet
-            GW-->>D: 422 Unprocessable Entity
-        else Başarılı Dönüşüm
-            TS-->>GW: KENTİM Standart IoT Şeması (JSON)
-            GW->>GW: ST_Contains ile PostGIS Geofence Sınır Kontrolü
-            alt Sınır Dışı
-                GW->>DB: integration_logs tablosuna FAILED (Out of Boundaries) kaydet
-                GW-->>D: 400 Bad Request
-            else Sınır İçi (Başarılı)
-                GW->>DB: Telemetri logunu & Cihaz durumunu güncelle
-                GW->>SO: Eşik Kontrolü (%85 doluluk veya arıza var mı?)
-                alt Doluluk >= %85 VEYA Durum = faulty
-                    SO->>SO: Aktif / kapatılmamış iş emri kontrolü
-                    alt Aktif İş Emri Zaten Var
-                        SO-->>GW: İş emri oluşturma (Mükerrerlik bypass)
-                        GW-->>D: 200 OK (Telemetri kaydedildi, iş emri zaten var)
-                    else Yeni İş Emri Tetiklendi
-                        SO->>DB: Temizlik/Sıfır Atık Müdürlüğüne "dispatched_to_department" kaydet
-                        DB-->>GW: Yeni iş emri oluşturuldu (work_order_id)
-                        GW-->>D: 201 Created (Yeni İş Emri Oluşturuldu)
-                    end
-                else Eşik Aşılmadı
-                    GW-->>D: 200 OK (Telemetri kaydedildi, aksiyon gerekmiyor)
-                end
-            end
-        end
-    end
-```
-
-### Dinamik IoT Entegrasyonu Süreç Algoritması
-
-1.  **İstek Karşılama ve Ön Filtreleme:** Akıllı çöp veya geri dönüşüm cihazı, belediye sistem yöneticisinden aldığı `API_KEY` ile platformun ortak `/v1/integrations/iot/telemetry` adresine veri basar. API Gateway ham telemetri payload boyutu **maksimum 10KB** olacak şekilde ön filtreleme yapar; sınırı aşan istekler `400 Bad Request` ile anında reddedilir.
-2.  **Kimlik ve İzolasyon Çözümleme:** API Gateway, gelen istekteki API anahtarı üzerinden veritabanında `tenant_id` sorgusu yapar. RLS kuralları uyarınca veriler anında o belediyenin izole şemasıyla ilişkilendirilir.
-3.  **Kuyruklama ve Asenkron Çözümleme (Decoupling):** Ana API thread'ini meşgul etmemek veya parser kilitlenmelerinin Fastify'ı dondurmasını önlemek için, telemetri paketi anlık olarak bir PostgreSQL tabanlı kuyruğa yazılır (`INSERT` into `iot_telemetry_queue`) ve `LISTEN/NOTIFY` mekanizması ile worker'lar tetiklenir, cihaza `202 Accepted` dönülür.
-4.  **Dinamik Dönüştürme (Transformer & V8 Sandbox):** Arka planda çalışan warm-worker instance'lar (Isolate Havuzu) kuyruktan gelen veriyi asenkron olarak tüketir:
-    *   Eğer entegrasyon tipi `generic_webhook` ise standart JSON eşleştirmesi uygulanır.
-    *   Eğer entegrasyon tipi `custom_iot_sensor` ise belediyenin girdiği JavaScript kodu izole **V8 Sandbox** motorunda (max 50ms CPU, 16MB RAM) çalıştırılır.
-    *   Dönüştürme sonucunda `"device_id"`, `"device_type"`, `"fill_level_percentage"`, `"status"`, `"coordinates"` ve `"waste_type"` alanları standart formatta elde edilir.
-5.  **Coğrafi Sınır (PostGIS) Denetimi:** Standartlaştırılan koordinat bilgisi veritabanında `ST_Contains` fonksiyonuyla o belediyenin PostGIS aktif sınır sürümü (`municipal_boundary_versions` tablosundaki boundaries) kapsamında test edilir. Koordinat sınır dışındaysa işlem sonlandırılır ve log tablosuna `FAILED` yazılır.
-6.  **Durum ve Eşik Kontrolü:**
-    *   Sensör doluluk oranı `%85` ve üzerinde ise veya sensör sağlık durumu `"faulty"` ise sistem otomatik olarak **belediye adminin entegrasyon formunda belirlediği hedef müdürlüğe (örn. Temizlik İşleri veya Sıfır Atık)** havale edilmek üzere `dispatched_to_department` durumunda bir iş emri tetikler (moderatör onayı bypass edilir). **402 Grace Period Kısıtı:** Belediyenin aboneliği askıdayken telemetri paketleri sensör tampon bellek taşmalarını önlemek amacıyla 202 Accepted ile kuyruğa alınmaya devam edilir; ancak sandbox ve eşik kontrolü sonrasında doluluk >= %85 olsa dahi yeni iş emri tetiklenmesi Fastify transformer pipeline tarafından aktif olarak engellenir ve telemetri logu static olarak kaydedilir.
-    *   Eğer o cihaz kimliğine (`device_id`) ait henüz çözülmemiş (`resolved` olmayan) aktif bir iş emri varsa, mükerrer iş gücü kaybını engellemek için **yeni bir iş emri oluşturulmaz**, telemetri logu güncellenir.
-
----
-
-## 3. Akışların Teknik Validasyon Sınırları
-
-Tüm iş akışlarında sunucu tarafında (Server-Side) çalıştırılan ve bypass edilmesi imkansız olan validasyon kuralları şunlardır:
-
-1.  **Idempotency Anahtarı (`x-idempotency-key`)**: Rapor oluşturma (`POST /reports`) veya durum güncelleme (`PATCH /work-orders/:id`) isteklerinde UUIDv4 formatında bir idempotency key gönderilmelidir. Sunucu aynı istek anahtarını görürse işlemi tekrarlamaz, ilk başarılı cevabı döner (24 saatlik önbellek).
-2.  **SLA Hesaplama ve Durdurma Noktaları**: SLA sayacı iş `dispatched_to_department` durumuna geçtiğinde başlar. Normal durumlarda belediyenin yerel çalışma saatleri ve hafta sonu tatilleri SLA hesaplamasından düşülür. Ancak `Acil` veya `Kriz` seviyesindeki iş emirlerinde bu kural tamamen bypass edilerek **7/24 kesintisiz SLA sayacı** işletilir. Şef veya müdür işi onaylayıp `resolved` yaptığında, gerekçeli ret verip `rejected` durumuna çektiğinde veya moderatör tarafından **mükerrer rapor olarak işaretlenip kapatıldığında** SLA sayacı anında durdurulur. Mükerrer rapor birleştirmelerindeki anlık durdurma işlemi SLA uyum oranlarına (SLA Compliance) olumlu/nötr olarak yansıtılarak yapay aşımlar önlenir. **SLA Öncelik Çarpanları:** İş öncelik seviyelerine göre SLA süreleri çarpanlarla hesaplanır: `low = x1.5 SLA`, `normal = x1.0 SLA`, `high = x0.5 SLA`, `urgent = x0.25 SLA`, `crisis = x0.1 SLA` (7/24 kesintisiz). **Re-dispatch sürecinde iş moderation kuyruğunda beklerken SLA sayacı durmaz, çalışmaya devam eder.** **QA Döngüsü SLA Davranışı:** İş `resolved` durumuna geçtiğinde SLA sayacı durdurulur. Vatandaş 1-2 yıldız verip iş QA kuyruğuna düştüğünde sayaç durdurulmuş hâlde kalır. Şef QA incelemesinde işi tekrar `in_progress` yaparsa SLA sayacı **dondurulduğu noktadan kaldığı yerden devam eder** (yeniden başlamaz). Şef `resolved` kararı verirse sayaç değişmez. **Ping-Pong Koruma Eşiği:** Re-dispatch sayacı her müdür re-dispatch'inde `1` artırılır. Sayaç `> 2` (yani 3. re-dispatch gerçekleştiğinde) ping-pong koruması devreye girer; iş moderatör kuyruğundan alınarak doğrudan `muni_admin`'in "Anlaşmazlık Çözüm" kuyruğuna taşınır. Moderatör re-dispatch'leri bu sayaca dahil edilmez; yalnızca müdür/admin seviyesindeki re-dispatch'ler sayılır. **Admin anlaşmazlık kuyruğundan kesin atama yaptığında re-dispatch sayacı sıfırlanır, iş sıfır sayaçla yeni müdürlüğe düşer.**
-3.  **Vardiya Devir İşlemi**: Personel vardiyayı kapattığında sunucu üzerindeki `in_progress` işleri tarar. Varsa, RLS kapsamında bu işlerin `assigned_worker_id` alanı `NULL` yapılır ve durum `assigned_to_team` olarak güncellenir. Ancak tamamlanıp fotoğrafı yüklenmiş olan ve onay bekleyen `pending_chief_approval` durumundaki işler bu devir işleminden muaftır ve personelin üzerinde kalmaya devam eder.
-4.  **GDPR Anonimleştirme ve Derin Temizlik Tetikleyicisi**: 
-    *   *Hesap Silme*: Kullanıcı hesabını sildiğinde `muni_admin` onay mekanizması tetiklenir. Onay alındığında vatandaşın `citizen` tablosundaki kişisel verileri silinir; `work_orders` tablosundaki rapor tanımları korunurken, raporu açan vatandaşın kişisel alanları (Ad, Soyad, Telefon, E-posta) maskelenir ve veritabanı loglarındaki IP adresleri `0.0.0.0` olarak güncellenir.
-    *   **Denetim Logu Geçmişi Maskeleme (Yeni — KVKK Zorunluluğu):** Ana silme/anonimleştirme işlemi tamamlandıktan sonra asenkron bir arka plan job'u başlatılır. Bu job, `audit_logs` tablosundaki `old_value` ve `new_value` JSON alanlarında silinen vatandaşa ait kayıtları indeksli `citizen_id` kolonu üzerinden doğrudan filtreleyerek (full table scan yapmadan) tarar ve telefon numarası, T.C. kimlik numarası, e-posta adresi ile ad-soyad bilgilerini `[KİŞİSEL VERİ SİLİNDİ]` mask'iyle değiştirir. Job tamamlandığında `gdpr_requests` tablosundaki ilgili talep kaydı `completed` + `anonymized_at` zaman damgasıyla güncellenir. Bu adımın atlanması KVKK/GDPR ihlali oluşturur.
-    *   *Derin Temizlik Regex Filtreleri*: Gerek vatandaş raporu açıklaması gerekse personelin serbest açıklama metinleri içerisinde bulunabilecek hassas kişisel veriler (telefon numaraları, T.C. Kimlik numaraları, e-posta adresleri) derin regex filtreleri kullanılarak kayıt aşamasında sunucu tarafında maskelenir. Regex tanımları:
-        *   **Telefon**: `(?:\+?90[-. ]?)?5[0-9]{2}[-. ]?[0-9]{3}[-. ]?[0-9]{2}[-. ]?[0-9]{2}` -> `[TELEFON MASKELENDİ]`
-        *   **E-posta**: `[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}` -> `[E-POSTA MASKELENDİ]`
-        *   **T.C. Kimlik**: `[1-9][0-9]{10}` -> `[TCKN MASKELENDİ]`
-5.  **"+1 Desteği" Idempotency ve Benzersizlik Sınırı**: `support_votes` tablosunda `(work_order_id, citizen_id)` alanı üzerinde benzersiz bir kısıt (unique constraint) bulunur. Kullanıcı aynı rapora birden fazla kez "+1" vermeye çalışırsa sunucu sessizce `200 OK` döner (idempotent davranış), ancak veri tekrar yazılmaz. Rapor çözüldüğünde (`resolved` durumunda) veya silindiğinde destek oyu geri çekilemez.
-6.  **Public API Veri Maskeleme ve Güvenlik Sınırı**: Halka açık haritada sunulan raporlarda (`GET /v1/public/reports`) vatandaş kimliği (`citizen_id`, ad, soyad, telefon, e-posta) tamamen maskelenir. Coğrafi koordinatlar, tam noktanın tespit edilerek kişisel mahremiyetin ihlal edilmesini önlemek amacıyla ±0.0005° (yaklaşık 50 metre) fuzzing (sapma) uygulanarak `approximate_coordinates` şeklinde sunulur.
-7.  **Kategori Seviyesinde Public Engelleme**: Central Admin tarafından yönetilen global kategorilerde `default_public_visible = false` veya "kategori-level deny" olarak işaretlenmiş olan kategoriler, ilgili belediyenin ayarlarından bağımsız olarak hiçbir koşulda public haritada (`is_public_visible = false`) gösterilemez.
-8.  **`ROLE_CHANGE_CLEANUP` — Otomatik Yetki Devir Sınırı**: Herhangi bir belediye personelinin rolü değiştiğinde veya hesabı pasife alındığında, sistem `ROLE_CHANGE_CLEANUP` akışını sunucu tarafında otomatik olarak tetikler; bu bypass edilemez. Hiyerarşi kuralları şunlardır:
-    *   **Müdür pasife alınırsa** → tüm aktif işler `muni_admin` havuzuna.
-    *   **Şef pasife alınırsa** → `in_progress` ve `assigned_to_team` işleri müdür havuzuna; `pending_chief_approval` işlerinin onay yetkisi müdüre geçer.
-    *   **`muni_worker` pasife alınırsa** → `in_progress` ve `assigned_to_worker` işleri `assigned_to_team` (şef atanmamış havuzu) durumuna çekilir; **müdür bypass atamasıyla gelen işler ise `dispatched_to_department` (müdür havuzu) olarak iade edilir** (`is_manager_bypassed = true` korunur); `pending_chief_approval` işleri muaftır ve şefin onay kuyruğunda kalmaya devam eder (atanan personel alanı pasifleşmiş olarak işaretlenir). Tüm akış denetim loguna `ROLE_CHANGE_CLEANUP` olarak kaydedilir.
-    *   **`is_force_assigned` Kilidi**: Admin tarafından anlaşmazlık kuyruğundan kesin atama yapılan iş emirlerinde `is_force_assigned = true` flag'i bulunur. Bu flag aktifken müdür veya şef tarafından re-dispatch yapılması API katmanında reddedilir (`403 Forbidden`); yalnızca `muni_admin` müdahale edebilir.
-9.  **Çevrimdışı (Offline) Uyuşmazlık Çözümü Edge-Case Kuralları**: Saha personeli çevrimdışıyken tamamladığı bir iş emrini internet geldiğinde sunucuya senkronize etmeye çalışırken `409 Conflict` (işin başkasına atanmış olması) çakışması yaşanırsa şu kurallar işletilir:
-    *   **Çevrimdışı Handover İstisnası:** Saha çalışanının yerel cihazındaki yerel tamamlanma zaman damgası (local timestamp), sunucunun otomatik vardiya kapatma (auto-handover) zaman damgasından daha önce ise sistem bunu `409 Conflict` olarak reddetmez, doğrudan uyuşmazlık havuzuna (`dispute_logs` tablosu) "Hak Ediş Teyidi Bekliyor" notuyla yönlendirir. Şef onaylayınca hak ediş puanı personelin hesabına yazılır.
-    *   *Senaryo A (Yeni Atanan İşe Başlamamışsa)*: Eğer işin atandığı yeni personel işi henüz başlatmamış (`in_progress` yapmamış) veya tamamlamamışsa; sistem otomatik olarak işi yeni personelden geri alır (`assigned_to_team` havuzuna çeker), iş emrini çevrimdışı bitiren personelin kimliğiyle `pending_chief_approval` durumuna getirir ve şefe bildirim gönderir. Yeni personele görevin iptal edildiğine dair push gider.
-    *   *Senaryo B (Yeni Atanan İşe Başlamış/Bitirmişse)*: Eğer yeni personel işi zaten üstlenmiş veya bitirmişse; çevrimdışı tamamlanan bu eski iş kaydı doğrudan **Senkronizasyon Uyuşmazlık Havuzuna** (`dispute_logs` tablosu) asenkron aktarılır. Şef "Çakışma Çözümü" ekranında iki personelin de kanıtlarını ve zaman damgalarını karşılaştırır. Yerinde incelemeye göre çevrimdışı personelin emeğini `"Hak Edişi Onayla"` butonu ile onaylayabilir. Bu onay, ana işin durumunu bozmaz ancak personelin performans hak ediş puanını sisteme artı olarak yansıtır.
-10. **Hata Dayanıklılığı ve Dead Letter Queue (DLQ) Mekanizmaları**:
-    *   *Bildirim Hataları*: Vatandaş veya personele gönderilecek SMS/E-posta veya Push bildirimleri servis sağlayıcı kesintileri nedeniyle başarısız olursa; sistem PostgreSQL tabanlı asenkron kuyruğunda üst üste 3 kez exponential backoff ile tekrar dener. 3 deneme sonunda halâ başarısız olan bildirim paketleri `notification_dlq` tablosuna (Dead Letter Queue) taşınır ve muni_admin panelinde "Hatalı İletişimler" olarak listelenir.
-    *   *IoT Parser Betiği Çökmeleri*: V8 Sandbox üzerinde çalışan custom parser betiği bir syntax veya bellek hatası nedeniyle çökerse (`crash`); sistem ilgili telemetri paketini `failed_telemetry_dlq` tablosuna ham JSON halinde yazar, ilgili IoT cihazını otomatik olarak "Pasif/Hatalı" durumuna çeker ve admin paneline `INTEGRATION_PARSER_CRASH` audit loguyla beraber kritik sistem uyarısı basar.
-11. **Otomatik Transactional Denetim Loglama (Audit Logging) ve JSONB Geçmişi**:
-    *   **Transactional Bütünlük:** Tüm durum geçişleri, eskalasyonlar, geofence bypass onayları, offline çakışma çözümleri ve yetkilendirilmiş administratör müdahaleleri (`force_resolve`, `manual_approval`, `re-dispatch`, `role_change_cleanup`) veritabanında gerçekleştirilen ana operasyonla aynı **SQL Transaction (`BEGIN ... COMMIT`)** bloğu içerisinde kaydedilir. Bu sayede, iş emri durumu değiştiği halde denetim logunun yazılamaması veya denetim logu yazılıp durumun güncellenememesi gibi veri tutarsızlıkları tamamen önlenir.
-    *   **JSONB Old/New Payloads Oluşturma:** Loglama mekanizması, güncellenen tablonun (örn: `work_orders`, `municipalities`, `users`) ilgili satırının güncellemeden hemen önceki tüm sütun değerlerini `payload_old` (JSONB) alanına, güncellemeden sonraki halini ise `payload_new` (JSONB) alanına kaydeder.
-    *   **Asenkron Tetikleme ve Trigger Kurgusu:** Yoğun durum geçişlerinde veritabanına ek gecikme (latency) bindirmemek için, personelin gerçekleştirdiği durum güncellemeleri PostgreSQL'deki `AFTER UPDATE` satır düzeyindeki trigger'ları veya API katmanındaki asenkron audit interceptor'ları aracılığıyla `audit_logs` tablosuna yazılır.
-    *   **Bypass ve Özel Log Akışları:**
-        *   *Geofence Bypass Onayı:* Şef geofence bypass talebini onayladığında, `event_type = 'GEOFENCE_BYPASS_APPROVED'` logu tetiklenir. `payload_old` içinde `geofence_bypass_requested = true` ve eski personel bilgileri yer alırken, `payload_new` içinde onaylanan yeni koordinat ve `is_manager_bypassed` durumu yansıtılır.
-        *   *Ping-Pong Dispute Çözümü:* Admin dispute kuyruğundan kesin atama gerçekleştirdiğinde `event_type = 'DISPUTE_RESOLVED'` logu yazılır; `payload_old` içinde re-dispatch limitini aşan eski departman bilgileri, `payload_new` içinde ise `is_force_assigned = true` ve atanan kesin departman verisi JSONB olarak yer alır.
-
-*MVP Sürümü — KENTİM İş Akışları ve Süreç Algoritmaları Belgesi*
-
-## EK AKIŞLAR: Public Görünürlük ve "+1 Beni de Etkiliyor" İşlemleri
-
-### "+1 Desteği" Aksiyonu (Tekilleştirme)
-- Uygulama: `moderation` ve sonrası (`resolved` hariç) durumdaki raporlara hesaplı kullanıcılar "+1" desteği verebilir.
-- Veri modeli: `support_votes(work_order_id, citizen_id, created_at)` tablosu ile idempotent unique constraint `(work_order_id, citizen_id)` uygulanır.
-- Arka plan: `work_orders.support_count` alanı asenkron debounced worker ile güncellenmektedir (row-locking önleme tasarımı).
-
-### Public Görünürlük Yönetimi Akışı
-- Moderatör veya admin: raporu public haritadan gizleyebilir veya tekrar gösterebilir (`is_public_visible` boolean toggle).
-- Gizleme gerekçesi (zorunlu): `personal_data` / `sensitive_location` / `inappropriate` / `official_investigation` / `other (text)`.
-- İşlem sonucu: `public_hidden_reason`, `public_hidden_at`, `public_hidden_by` alanları güncellenir ve `PUBLIC_VISIBILITY_CHANGED` audit log kaydı oluşturulur.  
-  **Not:** `public_map_cache` invalidation mekanizması entegre edilmiştir. Rapor durumu, public görünürlüğü veya destek sayısı değiştiğinde önbellek otomatik olarak temizlenir.
-
-### EK - GDPR / Hesap Silme ve IoT Kaynaklı İşlerin Public Davranışı
-
-1) GDPR: Hesap Silme ve +1 Oyların Kaldırılması (Cascade)
-- Kullanıcı hesabı silinmeye onay verildiğinde aşağıdaki transactional + asenkron akış çalışır:
-    - `BEGIN TRANSACTION`
-    - `DELETE FROM support_votes WHERE citizen_id = <deleted_citizen_id>`
-    - `UPDATE work_orders SET support_count = (SELECT COUNT(1) FROM support_votes WHERE work_order_id = work_orders.id) WHERE id IN (SELECT work_order_id FROM support_votes WHERE citizen_id = <deleted_citizen_id>)`
-    - `COMMIT`
-    - **[Asenkron Job — Ayrı Görev]:** `audit_logs` tablosunda silinene ait geçmiş `old_value`/`new_value` alanları regex ile taranarak kişisel veriler `[KİŞİSEL VERİ SİLİNDİ]` ile maskelenir. `gdpr_requests` kaydı `completed` + `anonymized_at` ile güncellenir.
-
-2) AKIŞ 5 Genişletme: IoT Kaynaklı İşlerde `default_public` Davranışı
-- IoT entegrasyonundan tetiklenen yeni iş emirleri oluşturulurken entegrasyon tanımında bulunan `default_public` boolean alanı okunacak:
-    - Eğer `default_public = true` ise yeni iş `is_public_visible = TRUE` ile oluşturulur.
-    - Eğer `default_public = false` ise yeni iş `is_public_visible = FALSE` ile oluşturulur ve moderatör onayı olmadan public görünür yapılmaz.
-- Bu davranış, IoT parser/transformer pipeline'ına açıkça eklenmelidir; ayrıca admin panelindeki entegrasyon formunda `default_public` checkbox'u gösterilerek sistem yöneticisinin entegrasyon bazında politika belirlemesine izin verilecektir.
-
-### Rapor Oluşturma — Önleyici Mükerrer Akışı (Akış 1: genişletme)
-- Adım: Konum seçildiğinde sistem `GET /public/reports/nearby?lat=&lng=&radius=100` çağrısı yapar.
-- Eğer yakın konumda aktif rapor bulunursa: kullanıcıya bilgi kutusu gösterilir; kullanıcı +1 verirse form kapanır ve ana sayfadaki harita ilgili pine odaklanarak gösterilir; "Hayır, farklı" derse normal forma devam eder.
-Bu ek akışlar, moderatör iş yükünü azaltmak ve vatandaş katılımını artırmak için tasarlanmıştır.
-
----
-
-## 4. Gelişmiş Sistem Algoritmaları (MVP Mimarisine Entegre)
-
-### Algoritma 5: Asenkron Panik Sinyali ve Debouncing Mimarisi
-**Amaç:** Afet Modu aktifken binlerce vatandaştan aynı anda saniyede gelen binlerce `POST /v1/emergency/panic` GPS sinyalinin PostgreSQL I/O tıkanmalarına ve kilitlenmelerine (DB Deadlocks) yol açmasını engellemek, cihaz bazlı istismarları (Spam/DDoS) debouncing katmanı ile engellemek.
-
-```javascript
-// Sunucu Tarafı Panik Alım ve Hız Sınırlama Akışı
-async function handleEmergencyPanic(request, reply) {
-  const { device_id, latitude, longitude, altitude, citizen_id } = request.body;
-  const clientIp = request.ip;
-
-  // 1. Cihaz Bazlı Hız Sınırlama (Device-Level Sliding-Window Rate Limiter)
-  // PostgreSQL tabanlı sayaç veya bir fonksiyon ile hız sınırlama uygulanır.
-  // Bu, 'panic_rate_limits' gibi bir tabloda device_id ve timestamp tutularak yönetilebilir.
-  const isRateLimited = await checkAndIncrementPanicRateLimit(device_id);
-  
-  if (isRateLimited) {
-    return reply.status(429).send({ error: "Çok fazla istek, lütfen sakin olun ve bekleyin." });
-  }
-
-  // 2. Asenkron Kuyruğa Yazma (Fast-Ingest Pipeline via PostgreSQL Table + LISTEN/NOTIFY)
-  const panicPayload = {
-    device_id,
-    citizen_id: citizen_id || 'anonymous',
-    latitude: latitude.toString(),
-    longitude: longitude.toString(),
-    altitude: altitude ? altitude.toString() : '0',
-    received_at: new Date().toISOString(),
-    ip: clientIp
-  };
-
-  // Veritabanı transaction içinde panik sinyali kuyruk tablosuna eklenir
-  await db.query('INSERT INTO emergency_panic_queue (payload) VALUES ($1) RETURNING id', [panicPayload]);
-  // LISTEN/NOTIFY ile worker'lara sinyal gönderilir
-  await db.query("SELECT pg_notify('emergency_panic_channel', $1)", [device_id]);
-
-  // Veritabanı yazma işlemi beklenmeksizin vatandaşa 202 Accepted ve takip UUID'si döndürülür
-  const tempTrackingId = uuid.v4(); // Gerçek bir tracking_id daha sonra worker tarafından üretilebilir
-  return reply.status(202).send({ 
-    status: "Accepted", 
-    message: "Konumunuz afet koordinasyon merkezine asenkron olarak iletilmiştir.",
-    tracking_id: tempTrackingId 
-  });
-}
-
-// Arka Plan Consumer Worker Servisi (Bulk Debouncer Engine)
-async function panicQueueConsumer() {
-  const client = await pgPool.connect();
-  await client.query('LISTEN emergency_panic_channel');
-
-  client.on('notification', async (msg) => {
-    logger.info('Received notification on emergency_panic_channel:', msg.payload);
-    // İşleme alınacak mesajlar için bir bekleme veya toplama mekanizması (debouncing) burada uygulanır.
-    // Örneğin, belirli bir süre içinde gelen bildirimleri toplayıp toplu işlem yapmak.
-
-    // Kuyruktan işlenecek öğeleri çek (toplu okuma)
-    const unprocessedPanics = await client.query(`
-      SELECT id, payload FROM emergency_panic_queue WHERE processed = FALSE LIMIT 50 FOR UPDATE SKIP LOCKED;
-    `);
-
-    if (unprocessedPanics.rows.length === 0) {
-      return;
-    }
-
-    const uniquePanics = new Map();
-
-    // Debouncing: Aynı Device ID'den gelen ardışık sinyalleri grupla, sadece en son/güncel koordinatı tut
-    for (const row of unprocessedPanics.rows) {
-      const panicObj = row.payload; // payload zaten JSONB olduğu varsayılıyor
-      uniquePanics.set(panicObj.device_id, {
-        ...panicObj,
-        queue_id: row.id // Kuyruk ID'sini de takip et
-      });
-    }
-
-    // Toplu Yazma (Bulk Database Transaction)
-    if (uniquePanics.size > 0) {
-      const dbWorkerClient = await pgPool.connect(); // İşlemler için ayrı bir client
-      try {
-        await dbWorkerClient.query("BEGIN");
-        for (const [deviceId, data] of uniquePanics) {
-          // PostGIS Centroid-based Nearest Neighbor (KNN) ile sinyale en yakın aktif belediyeyi (tenant_id) tespit et
-          const nearestMuni = await dbWorkerClient.query(`
-            SELECT m.id AS tenant_id 
-            FROM municipalities m
-            JOIN municipal_boundary_versions mbv ON m.id = mbv.municipality_id
-            WHERE m.status = 'active' AND mbv.active_to IS NULL
-            ORDER BY mbv.boundaries <-> ST_SetSRID(ST_MakePoint($1, $2), 4326)
-            LIMIT 1;
-          `, [data.longitude, data.latitude]);
-          
-          const targetTenantId = nearestMuni.rows[0]?.tenant_id || null; // default null, worker belirlesin
-
-          // PostgreSQL bulk upsert ile kriz masası can haritası tablosuna yazılır
-          await dbWorkerClient.query(`
-            INSERT INTO crisis_signals (device_id, citizen_id, coordinates, received_at, tenant_id)
-            VALUES ($1, $2, ST_SetSRID(ST_MakePoint($3, $4), 4326), $5, $6)
-            ON CONFLICT (device_id) 
-            DO UPDATE SET coordinates = EXCLUDED.coordinates, received_at = EXCLUDED.received_at, tenant_id = EXCLUDED.tenant_id;
-          `, [deviceId, data.citizen_id, data.longitude, data.latitude, data.received_at, targetTenantId]);
-
-          // İşlenen panik sinyalini kuyruktan çıkar (veya processed = TRUE yap)
-          await dbWorkerClient.query(`UPDATE emergency_panic_queue SET processed = TRUE WHERE id = $1`, [data.queue_id]);
-        }
-        await dbWorkerClient.query("COMMIT");
-      } catch (err) {
-        await dbWorkerClient.query("ROLLBACK");
-        logger.error("Panic bulk insert error, moving to DLQ: ", err); // Gerekirse DLQ mekanizması eklenebilir
-      } finally {
-        dbWorkerClient.release();
-      }
-    }
-  });
-
-  client.on('error', (err) => {
-    logger.error('PostgreSQL LISTEN client error:', err);
-  });
-}
-
-// Yardımcı fonksiyon: Basit bir debouncing için rate limit kontrolü (örnek, gerçekte daha kompleks olabilir)
-async function checkAndIncrementPanicRateLimit(deviceId) {
-  const result = await db.query(`
-    INSERT INTO panic_rate_limits (device_id, last_request_at, request_count)
-    VALUES ($1, NOW(), 1)
-    ON CONFLICT (device_id) DO UPDATE SET 
-      request_count = CASE 
-        WHEN (NOW() - panic_rate_limits.last_request_at) < INTERVAL '1 minute' THEN panic_rate_limits.request_count + 1
-        ELSE 1 
-      END,
-      last_request_at = NOW()
-    RETURNING request_count;
-  `, [deviceId]);
-
-  return result.rows[0].request_count > 5; // 1 dakikada 5 isteği aşarsa rate-limited say
-}
-```
-
-### Algoritma 6: Geofence Boundary Snapshot Kilitlenme Önleyici Doğrulama
-**Amaç:** Belediye sınırları (`boundaries` poligonu) meclis kararı veya coğrafi güncellemeler nedeniyle daraltıldığında ya da değiştirildiğinde, personelin üzerinde açık olan (`in_progress`) işleri kapatırken "Belediye Sınırları Dışında" (lockout) hatası alarak kilitlenmesini engellemek.
-
-```sql
--- 1. İş Emri Oluşturulma Anında Sınır Kilitleme (Trigger / Ingestion Aşaması)
-CREATE OR REPLACE FUNCTION snap_municipal_boundary_on_creation()
-RETURNS TRIGGER AS $$
-BEGIN
-  -- İş emrinin oluşturulduğu andaki aktif belediye PostGIS sınır poligonu sürümü (ID) sorgulanır
-  -- ve doğrudan work_orders.boundary_version_id kolonuna atanarak kilitlenir.
-  SELECT id INTO NEW.boundary_version_id
-  FROM municipal_boundary_versions
-  WHERE municipality_id = NEW.municipality_id
-    AND active_from <= NOW()
-    AND (active_to IS NULL OR active_to >= NOW())
-  LIMIT 1;
-
-  -- Eğer aktif sınır sürümü bulunamazsa sistem hata fırlatmaz, default fallback sürüm atar.
-  RETURN NEW;
-END;
-$$ LANGUAGE plpgsql;
-
-CREATE TRIGGER trg_lock_boundary_snapshot
-  BEFORE INSERT ON work_orders
-  FOR EACH ROW
-  EXECUTE FUNCTION snap_municipal_boundary_on_creation();
-```
-
-```javascript
-// 2. İş Kapatma Anında Validasyon Akışı (Server-Side ST_Contains Validation)
-async function validateGeofenceOnCompletion(workOrderId, workerLat, workerLng, isBypassRequested) {
-  // Veritabanından iş emrinin boundary_version_id ve bypass durumu çekilir
-  const workOrder = await db.query(
-    "SELECT boundary_version_id, geofence_bypass_approved FROM work_orders WHERE id = $1", 
-    [workOrderId]
-  );
-  
-  if (!workOrder) throw new Error("İş emri bulunamadı.");
-
-  // Eğer personel şef onaylı geofence bypass talebi onaylanmışsa direkt başarılı say
-  if (workOrder.geofence_bypass_approved) {
-    return { success: true, bypass: true, message: "Geofence kontrolü şef onaylı bypass edildi." };
-  }
-
-  // ST_Contains ile personelin son konumunu, boundary_version_id üzerinden JOIN ile kontrol et
-  const result = await db.query(`
-    SELECT ST_Contains(
-      mbv.boundaries, 
-      ST_SetSRID(ST_MakePoint($2, $3), 4326)
-    ) as is_inside
-    FROM municipal_boundary_versions mbv
-    WHERE mbv.id = $1;
-  `, [workOrder.boundary_version_id, workerLng, workerLat]);
-
-  if (result.rows[0]?.is_inside) {
-    return { success: true, bypass: false, message: "Personel snap konum sınırları içerisindedir." };
-  } else {
-    // Sınır dışındaysa hata fırlatılır; personel geofence bypass talebi ekranına yönlendirilir
-    return { 
-      success: false, 
-      bypass: false, 
-      message: "Koordinatlarınız iş emrinin oluşturulduğu andaki geçerli hizmet sınırlarının dışındadır. Konum düzeltme/bypass talebi oluşturabilirsiniz." 
-    };
-  }
-}
-```
-
-### Algoritma 7: Reopen Sınırı ve Kronik Arıza (Parent Link) Kayıt Zinciri
-**Amaç:** Vatandaşların aynı sorunu sonsuza kadar "reopen" ederek spam yapmasını engellerken (max 2 limit), çözülemeyen kronik sorunların tarihsel ve konumsal bağını kaybetmeden yeni biletler (`parent_reopened_work_order_id`) üzerinden takip edilmesini ve analiz edilmesini sağlamak.
-
-```javascript
-// Rapor Reopen ve Kronik Rapor İlişkilendirme Algoritması
-async function processReportReopenOrNew(trackingCode, reopenReason, userNotes) {
-  // 1. Raporu veri tabanından getir
-  const report = await db.query("SELECT id, status, reopen_count FROM work_orders WHERE tracking_code = $1", [trackingCode]);
-  if (!report) throw new Error("Rapor bulunamadı.");
-
-  // 2. Eğer reopen sayısı limitin altındaysa ( < 2 ) normal reopen sürecini işlet
-  if (report.reopen_count < 2) {
-    await db.query(`
-      UPDATE work_orders 
-      SET status = 'reopened',
-          reopen_count = reopen_count + 1,
-          reopen_reason = $2,
-          reopen_notes = $3,
-          updated_at = NOW()
-      WHERE id = $1
-    `, [report.id, reopenReason, userNotes]);
-
-    return { 
-      action: "REOPENED", 
-      message: "Raporunuz başarıyla yeniden açıldı ve incelemeye alındı.", 
-      reopen_count: report.reopen_count + 1 
-    };
-  }
-
-  // 3. Reopen limiti dolmuşsa ( >= 2 ) buton pasifleşir. Vatandaş yeni rapor oluşturduğunda:
-  // İstemci yeni rapor oluşturma modalına parent_id = report.id parametresini geçirir.
-  return {
-    action: "LOCKED",
-    message: "Bu rapor için maksimum yeniden açma sınırına (2) ulaşıldı. Lütfen yeni bir sorun kaydı oluşturun.",
-    parent_reopened_work_order_id: report.id // İstemciye aktarılan kronik ilişki ID'si
-  };
-}
-
-// Kronik Bağlantılı Yeni Rapor Kaydetme Fonksiyonu
-async function createNewChronicReport(data) {
-  const { category_id, coordinates, description, parent_reopened_work_order_id } = data;
-
-  const result = await db.query(`
-    INSERT INTO work_orders (
-      category_id, 
-      coordinates, 
-      description, 
-      parent_reopened_work_order_id, -- Kronik arıza bağlayıcı referans UUID
-      reopen_count,
-      status
-    )
-    VALUES ($1, ST_SetSRID(ST_MakePoint($2, $3), 4326), $4, $5, 0, 'pending')
-    RETURNING id, tracking_code;
-  `, [category_id, coordinates.lng, coordinates.lat, parent_reopened_work_order_id, description]);
-
-  // Eğer parent varsa, eski raporun durumunu 'chronic_archived' olarak güncelle ki haritada kalabalık yapmasın
-  if (parent_reopened_work_order_id) {
-    await db.query("UPDATE work_orders SET status = 'chronic_archived' WHERE id = $1", [parent_reopened_work_order_id]);
-    
-    // Denetim loguna kronik ilişki zincirini kaydet
-    await db.query(`
-      INSERT INTO audit_logs (event_type, description, citizen_id)
-      VALUES ('CHRONIC_LINK_CREATED', 'Kronik arıza bağlandı. Eski Rapor: ' || $1 || ' -> Yeni Rapor: ' || $2, $3)
-    `, [parent_reopened_work_order_id, result.id, data.citizen_id]);
-  }
-
-  return result;
-}
-```
-
-### Algoritma 8: Çoklu Belediye Rapor Derleme ve Güvenlik Filtreleme Algoritması
-**Amaç:** Belediye panellerinde yöneticiler tarafından çalıştırılan dinamik sorgularda (Custom Report Builder) ve SaaS merkez panelindeki (Executive Presentation-Ready Reports) karşılaştırma işlemlerinde, kiracılar arası (cross-tenant) veri sızıntılarını sıfırlamak, devasa verilerde bellek tükenmelerini önlemek ve yüksek performanslı sayfalama (pagination) mekanizmasını işletmek.
-
-```javascript
-// 1. Belediye Özel Rapor Oluşturucu (Read-Replica & Custom Query Builder with Cursor Pagination)
-async function compileMunicipalCustomReport(tenantId, queryConfig) {
-  const { dimensions, metrics, filters, limit = 50, next_cursor } = queryConfig;
-
-  // Güvenlik Önlemi: Sorguyu doğrudan canlı OLTP yerine read-replica bağlantı havuzuna yönlendir
-  const replicaClient = await pgReplicaPool.connect();
-
-  try {
-    let selectClause = dimensions.map(d => sanitizeColumn(d)).join(", ");
-    let groupByClause = dimensions.map(d => sanitizeColumn(d)).join(", ");
-    
-    // Metrik Eşleştirmeleri
-    let metricClauses = [];
-    if (metrics.includes("total_jobs")) metricClauses.push("COUNT(id) as total_jobs");
-    if (metrics.includes("avg_resolution_time")) metricClauses.push("AVG(EXTRACT(EPOCH FROM (resolved_at - created_at)))/3600 as avg_resolution_time_hours");
-    if (metrics.includes("sla_breach_rate")) metricClauses.push("COUNT(CASE WHEN is_sla_breached = true THEN 1 END)::float / COUNT(id) * 100 as sla_breach_rate");
-    if (metrics.includes("avg_satisfaction_score")) metricClauses.push("AVG(satisfaction_stars) as avg_satisfaction_score");
-
-    let sql = `
-      SELECT ${selectClause}, ${metricClauses.join(", ")}
-      FROM work_orders
-      WHERE tenant_id = $1 -- %100 Multi-Tenant RLS İzolasyon Güvencesi
-    `;
-
-    const params = [tenantId];
-    let paramIndex = 2;
-
-    // Dinamik Filtreler
-    if (filters.category_id) {
-      sql += ` AND category_id = $${paramIndex++}`;
-      params.push(filters.category_id);
-    }
-    if (filters.start_date && filters.end_date) {
-      sql += ` AND created_at BETWEEN $${paramIndex++} AND $${paramIndex++}`;
-      params.push(filters.start_date, filters.end_date);
-    }
-
-    // Cursor-Based Sayfalama Validasyonu (Anlık listelemeler ve pivotlar için)
-    if (next_cursor) {
-      sql += ` AND created_at < $${paramIndex++}`;
-      params.push(Buffer.from(next_cursor, 'base64').toString('ascii')); // Cursor çözümü
-    }
-
-    sql += ` GROUP BY ${groupByClause}`;
-    sql += ` ORDER BY created_at DESC LIMIT $${paramIndex++}`;
-    params.push(limit + 1); // Sonraki sayfa kontrolü için +1 kayıt çekilir
-
-    const result = await replicaClient.query(sql, params);
-    
-    let hasNextPage = false;
-    let nextCursorBase64 = null;
-    
-    if (result.rows.length > limit) {
-      hasNextPage = true;
-      result.rows.pop(); // Fazlalık satırı çıkar
-      const lastRowDate = result.rows[result.rows.length - 1].created_at;
-      nextCursorBase64 = Buffer.from(lastRowDate.toISOString()).toString('base64');
-    }
-
-    return {
-      data: result.rows,
-      pagination: {
-        hasNextPage,
-        next_cursor: nextCursorBase64,
-        limit
-      }
-    };
-  } finally {
-    replicaClient.release();
-  }
-}
-
-// 2. Central SaaS Karşılaştırmalı Yönetici Raporu Derleme Algoritması (Analytical DB Model)
-async function compileCentralExecutiveReport(centralUserId, reportConfig) {
-  const { municipality_ids, target_metrics, format = 'pdf' } = reportConfig;
-
-  // Güvenlik & RLS Denetimi: Bireysel citizen veya ham work_order verilerine asla erişilmez!
-  // Sadece asenkron ETL ile `central_analytics_metadata` tablosuna aktarılan agrege veriler taranır.
-  const sql = `
-    SELECT 
-      m.name as municipality_name,
-      cam.month,
-      cam.total_work_orders,
-      cam.sla_compliance_rate,
-      cam.avg_resolution_time_minutes,
-      cam.citizen_satisfaction_stars
-    FROM central_analytics_metadata cam
-    JOIN municipalities m ON cam.municipality_id = m.id
-    WHERE cam.municipality_id = ANY($1) -- Sadece yetkilendirilmiş belediyeler
-    ORDER BY cam.sla_compliance_rate DESC;
-  `;
-
-  const reportData = await db.query(sql, [municipality_ids]);
-
-  if (format === 'pdf') {
-    // Stilize, modern kurumsal renk paletleriyle (Danger Red #a44a3f, Forest Green #2C5F2D)
-    // KENTİM logolu, sayfa numaralı vektörel PDF sunum dosyası oluşturulup stream edilir.
-    return generateStyledPresentationPdf(reportData.rows);
-  }
-
-  return reportData.rows; // Pivot Excel (XLSX) için ham agrege veri
-}
-
-### 5. Gelişmiş Dağıtık Sağlık ve Onay Sistem Algoritmaları (Yeni)
-
-#### Algoritma 10: Merkezi Sistem Sağlığı İzleme ve Dağıtık Polling Döngüsü (Central Health Monitor)
-Bu algoritma, Central SaaS sunucusunun kendi servislerinin yanı sıra, tescilli tüm belediyelerin `/ready` sağlık uç noktalarını 1 dakikalık periyotlarla aktif olarak nasıl sorguladığını (polling) ve heartbeat sinyallerini nasıl değerlendirdiğini gösterir.
-
-```javascript
-// Central SaaS Sağlık Sorgulama Döngüsü (Her 1 dakikada bir tetiklenir)
-async function centralSaaSHealthCheckScheduler() {
-  const municipalities = await db.query(
-    "SELECT id, name, backend_url, status FROM municipalities WHERE status IN ('active', 'suspended')"
-  );
-
-  for (const muni of municipalities.rows) {
-    const start = Date.now();
-    try {
-      // HMAC-SHA256 Master Key ile sorgu bütünlük imzası üretme (x-kentim-signature)
-      const timestamp = Date.now().toString();
-      const message = `${muni.id}:${timestamp}`;
-      const signature = crypto.createHmac('sha256', process.env.HMAC_MASTER_KEY).update(message).digest('hex');
-
-      // 1. Belediye sunucusuna /ready (health check) isteği gönderilir
-      const response = await axios.get(`${muni.backend_url}/ready`, {
-        headers: {
-          'x-kentim-timestamp': timestamp,
-          'x-kentim-signature': signature
-        },
-        timeout: 5000 // 5 saniye zaman aşımı bariyeri
-      });
-
-      const latency = Date.now() - start;
-
-      // 2. Yanıt içeriği doğrulanır ve central_health_logs tablosuna yazılır
-      if (response.status === 200 && response.data.status === 'ok') {
-        await db.query(`
-          INSERT INTO central_health_logs (municipality_id, status, latency_ms, db_connected, pg_listener_active, disk_usage_percentage, checked_at)
-          VALUES ($1, 'UP', $2, $3, $4, $5, NOW())
-        `, [
-          muni.id, 
-          latency, 
-          response.data.services.database === 'connected', 
-          response.data.services.pg_listener_active === true,
-          response.data.services.disk_usage_percentage
-        ]);
-      } else {
-        throw new Error("Sistem servisleri hazır değil.");
-      }
-    } catch (error) {
-      // 3. Hata durumunda pasif heartbeat kaydı kontrol edilir. Son 3 dakika heartbeat alınmış mı?
-      const lastHeartbeatResult = await db.query(`SELECT last_heartbeat_at FROM muni_heartbeats WHERE municipality_id = $1`, [muni.id]);
-      const lastHeartbeat = lastHeartbeatResult.rows[0]?.last_heartbeat_at ? new Date(lastHeartbeatResult.rows[0].last_heartbeat_at).getTime() : 0;
-      const isHealthyByHeartbeat = lastHeartbeat && (Date.now() - lastHeartbeat) < 180000;
-
-      const finalStatus = isHealthyByHeartbeat ? 'DEGRADED' : 'DOWN';
-
-      await db.query(`
-        INSERT INTO central_health_logs (municipality_id, status, latency_ms, error_message, checked_at)
-        VALUES ($1, $2, $3, $4, NOW())
-      `, [muni.id, finalStatus, Date.now() - start, error.message]);
-
-      if (finalStatus === 'DOWN') {
-        await triggerCentralAlert(muni.id, `Belediye Sunucusu Çöktü veya Yanıt Vermiyor: ${muni.name}`);
-      }
-    }
-  }
-}
-```
-
-#### Algoritma 11: Belediye Giriş Kilidi ve Merkezi SaaS Onay Kontrolü (SaaS Lockout Pipeline)
-Belediye personellerinin sisteme giriş talepleri sırasında, belediye backend'inin Central DB/Cache üzerinden belediyenin merkezi onay durumunu (`status`) nasıl kontrol ettiğini ve onaylanmayan belediyelerin girişini nasıl kilitlediğini tanımlar.
-
-```javascript
-// Belediye Personeli Giriş Doğrulama ve SaaS Lockout Kontrolü
-async function validateMunicipalUserLogin(email, password, ipAddress, userAgent) {
-  // 1. Kullanıcıyı ve şifresini yerel veritabanında doğrula
-  const user = await db.query(
-    "SELECT id, tenant_id, password_hash, role, status FROM users WHERE email = $1", 
-    [email]
-  );
-  
-  if (user.rows.length === 0) {
-    throw new Error("E-posta veya şifre hatalı.");
-  }
-
-  if (user.rows[0].status === 'passive') {
-    throw new Error("Kullanıcı hesabınız pasif durumdadır.");
-  }
-
-  const isPasswordValid = await bcrypt.compare(password, user.rows[0].password_hash);
-  if (!isPasswordValid) {
-    throw new Error("E-posta veya şifre hatalı.");
-  }
-
-  // 2. Merkezi SaaS (Central DB) aktivasyon durumunu kontrol et
-  // Municipal backend, central tenant registry üzerinden belediye lisans ve aktivasyon durumunu sorgular
-  const muniStatus = await db.query(
-    "SELECT status, license_expires_at, grace_period_ends_at FROM central_municipalities WHERE tenant_id = $1",
-    [user.rows[0].tenant_id]
-  );
-
-  if (muniStatus.rows.length === 0) {
-    throw new Error("Belediye tescil kaydı bulunamadı.");
-  }
-
-  const { status } = muniStatus.rows[0];
-
-  // 3. Central onay kontrolü (Giriş Kilidi)
-  // Durum 'active' değilse giriş anında reddedilir (Lockout)
-  if (status !== 'active') {
-    // Security audit log kaydı yazılır
-    await logSecurityAudit(user.rows[0].id, 'LOGIN_ATTEMPT_LOCKED', ipAddress, userAgent, {
-      reason: "Belediye central onaylı değil (aktif değil).",
-      municipality_status: status
-    });
-    
-    const err = new Error("Belediyeniz henüz merkez (Central SaaS) tarafından onaylanmamıştır veya aboneliği askıdadır.");
-    err.code = "MUNICIPALITY_NOT_APPROVED";
-    err.statusCode = 403;
-    throw err;
-  }
-
-  // 4. JWT Üret ve başarılı oturum açma logu yaz (Access Token: 15 dakika, Refresh Token Rotation ile desteklenir)
-  const token = jwt.sign({
-    userId: user.rows[0].id,
-    tenantId: user.rows[0].tenant_id,
-    role: user.rows[0].role
-  }, process.env.JWT_SECRET, { expiresIn: '15m' });
-
-  await logSecurityAudit(user.rows[0].id, 'LOGIN_SUCCESS', ipAddress, userAgent);
-
-  return { 
-    token, 
-    user: { 
-      id: user.rows[0].id, 
-      email, 
-      role: user.rows[0].role,
-      tenant_id: user.rows[0].tenant_id
-    } 
-  };
-}
-```
-
-```javascript
-// Yardımcı Güvenlik Loglama Fonksiyonu
-async function logSecurityAudit(userId, eventType, ipAddress, userAgent, metadata = {}) {
-  await db.query(`
-    INSERT INTO audit_logs (user_id, event_type, ip_address, user_agent, payload_new, created_at)
-    VALUES ($1, $2, $3, $4, $5, NOW())
-  `, [userId, eventType, ipAddress, userAgent, JSON.stringify(metadata)]);
-}
-```
-
----
-
-*MVP Sürümü — KENTİM İş Akışları ve Süreç Algoritmaları Belgesi*
-