agent-enderun 1.0.6 → 1.0.8

package/docs/mimari.md

@@ -1,926 +0,0 @@
-# KENTİM — Çok Belediyeli (Multi-Tenant SaaS) Mimari Belgesi (MVP Sürümü)
-
-Bu belge, KENTİM sisteminin tek bir belediye sınırlarının ötesinde, Türkiye genelindeki **birden fazla bağımsız belediyeye (Multi-Tenant SaaS)** nasıl ölçeklendiğini, veri izolasyonu güvenlik katmanlarını ve paylaşılan merkezi ağ geçidi yapısını tanımlar.
-
----
-
-## 1. Çok Belediyeli (Multi-Tenant) Sistem Mimarisi
-
-KENTİM, vatandaşların tek bir mobil uygulama veya web arayüzü üzerinden coğrafi konumlarına göre doğru belediyeyle etkileşime girdiği; belediyelerin ise birbirlerinin verilerini kesinlikle göremediği **izole edilmiş çok kiracılı (multi-tenant) bir SaaS** mimarisine sahiptir.
-
-### Çok Belediyeli Sistem Akış Diyagramı (SaaS)
-
-Aşağıdaki diyagramda görüldüğü üzere, vatandaş katmanı paylaşımlı bir ağ geçidi (Central Gateway) üzerinden gelirken, belediye verileri, personelleri ve iş akışları `tenant_id` bazında PostGIS ve RLS katmanlarıyla tamamen izole edilmiştir.
-
-```mermaid
-graph TD
-    subgraph Vatandaş Katmanı (Paylaşılan Mobil / Web Arayüzü)
-        Citizen[Vatandaş Cihazı] -->|Rapor Oluşturma & Takip| CentralGateway[Central SaaS Gateway API]
-    end
-
-    subgraph Central SaaS Katmanı (central.kentim.com.tr)
-        CentralGateway -->|1. Geofencing ile Belediye Tespiti| TenantRouter[Tenant Router / PostGIS Engine]
-        CentralAdmin[Central Admin] -->|Abonelik & Global Ayarlar| CentralDB[(Central SaaS DB)]
-        TenantRouter -->|Lisans Kontrolü| CentralDB
-    end
-
-    subgraph Belediye A İzolasyon Sınırı (tenant_id: muni_a)
-        TenantRouter -->|Yönlendirme| MuniA_Mod[Muni A Moderatörü]
-        MuniA_Mod -->|Müdürlük Havuzu| MuniA_Mgr[Muni A Departman Müdürü]
-        MuniA_Mgr -->|Şef Havuzu| MuniA_Chief[Muni A Ekip Şefi]
-        MuniA_Chief -->|Görev Atama| MuniA_Worker[Muni A Saha Personeli]
-        MuniA_Worker -.->|Foto & GPS Kanıtları| MuniA_DB[(Belediye A DB / Schema)]
-        MuniA_Admin[Muni A Admin] -->|Kriz Masası & Ayarlar| MuniA_DB
-    end
-
-    subgraph Belediye B İzolasyon Sınırı (tenant_id: muni_b)
-        TenantRouter -->|Yönlendirme| MuniB_Mod[Muni B Moderatörü]
-        MuniB_Mod -->|Müdürlük Havuzu| MuniB_Mgr[Muni B Departman Müdürü]
-        MuniB_Mgr -->|Şef Havuzu| MuniB_Chief[Muni B Ekip Şefi]
-        MuniB_Chief -->|Görev Atama| MuniB_Worker[Muni B Saha Personeli]
-        MuniB_Worker -.->|Foto & GPS Kanıtları| MuniB_DB[(Belediye B DB / Schema)]
-        MuniB_Admin[Muni B Admin] -->|Kriz Masası & Ayarlar| MuniB_DB
-    end
-```
-
----
-
-## 2. Çoklu Belediye Veri İzolasyon Modeli
-
-Çok belediyeli yapının veritabanı seviyesindeki güvenliği ve izolasyonu üç ana katmanda kurgulanmıştır:
-
-### A. Central SaaS Veritabanı (Paylaşılan Katman)
-Tüm sistemin ortak yönetim verilerini tutar. Belediyeler bu veritabanına doğrudan yazamaz veya erişemez:
-*   Belediye kayıtları (Tenant Registry: `muni_a`, `muni_b` listesi)
-*   Lisanslama ve Yıllık Abonelik Takibi (Başlangıç, bitiş tarihleri, ödeme durumları)
-*   **Global Rapor Kategorileri & Seed Yapısı (`global_categories` tablosu)**:
-    Sisteme dahil olan tüm belediyelerin varsayılan olarak devraldığı, central admin tarafından yönetilen global şikayet kategorileridir.
-    - **`global_categories` SQL Tablo Şeması:**
-      ```sql
-      CREATE TABLE global_categories (
-          id SERIAL PRIMARY KEY,
-          name VARCHAR(100) NOT NULL UNIQUE,
-          risk_score INTEGER NOT NULL CHECK (risk_score BETWEEN 1 AND 10),
-          default_public_visible BOOLEAN DEFAULT TRUE,
-          created_at TIMESTAMPTZ DEFAULT NOW()
-      );
-      ```
-    - **Otomatik Kurulum & Kategori Seed'i (`global_categories_seed.sql`)**:
-      Sistem ayağa kaldırılırken çalışan bu seed dosyası, Türkiye'deki belediyecilik standartlarına uygun temel kategorileri otomatik olarak enjekte eder:
-      ```sql
-      INSERT INTO global_categories (name, risk_score, default_public_visible) VALUES 
-      ('Yol Hasarı / Çukur', 5, TRUE),
-      ('Çöp / Temizlik Şikayeti', 3, TRUE),
-      ('Su ve Kanalizasyon Arızası', 8, TRUE),
-      ('Park ve Bahçe Bakımı', 2, TRUE),
-      ('Sokak Aydınlatması Arızası', 4, TRUE),
-      ('Zabıta Şikayeti / İşgal', 6, TRUE);
-      ```
-
-*   **Merkezi Lokasyon Yönetimi & Hiyerarşisi (`central_locations` tablosu)**: Türkiye geneli il ve ilçe verileri central seviyede bir sözlük olarak tutulur. Belediyelerin kayıt esnasında seçtiği il/ilçe alanları doğrudan bu tablodan beslenir.
-    - **`central_locations` SQL Tablo Şeması:**
-      ```sql
-      CREATE TABLE central_locations (
-          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-          name VARCHAR(100) NOT NULL,
-          parent_id UUID NULL REFERENCES central_locations(id) ON DELETE CASCADE,
-          type VARCHAR(20) NOT NULL CHECK (type IN ('province', 'district')),
-          slug VARCHAR(120) NOT NULL,
-          created_at TIMESTAMPTZ DEFAULT NOW(),
-          CONSTRAINT unique_name_parent UNIQUE (name, parent_id)
-      );
-      CREATE INDEX idx_central_locations_parent ON central_locations(parent_id);
-      CREATE INDEX idx_central_locations_type ON central_locations(type);
-      CREATE INDEX idx_central_locations_slug ON central_locations(slug);
-      ```
-    - **Türkiye Coğrafi Seed Yapısı (`turkey_locations_seed.sql`)**: 
-      Sistemin kurulduğu ilk anda çalıştırılan bu SQL göç (migration) betiği, Türkiye'deki **tam olarak 81 ili** (`type = 'province'`) ve bu illere hiyerarşik olarak bağlı **973 ilçeyi** (`type = 'district'`) `central_locations` tablosuna eksiksiz enjekte eder. Örneğin:
-      ```sql
-      -- Örnek İl Enjeksiyonu
-      INSERT INTO central_locations (id, name, parent_id, type, slug) VALUES ('a2e564ad-43ab-41c1-90a1-24c568ad9cf1', 'İstanbul', NULL, 'province', 'istanbul');
-      -- Örnek İlçe Enjeksiyonu (İstanbul'a Bağlı)
-      INSERT INTO central_locations (name, parent_id, type, slug) VALUES ('Kadıköy', 'a2e564ad-43ab-41c1-90a1-24c568ad9cf1', 'district', 'kadikoy');
-      ```
-*   **Merkezi Denetim Logları (`central_audit_logs` tablosu)**: Central SaaS düzeyinde sistem yöneticilerinin gerçekleştirdiği tüm kritik eylemleri, lisans güncellemelerini ve belediye kayıtlarını değişen verilerin geçmiş halleriyle birlikte takip eden global işlem logları tablosudur.
-    - **`central_audit_logs` SQL Tablo Şeması:**
-      ```sql
-      CREATE TABLE central_audit_logs (
-          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-          central_user_id UUID NOT NULL, -- İşlemi gerçekleştiren Central Admin personeli
-          municipality_id UUID NULL,     -- Eğer bir belediye etkilenmişse (örn: lisans askıya alma) referans
-          event_type VARCHAR(50) NOT NULL, -- örn: 'MUNICIPALITY_REGISTERED', 'LICENSE_SUSPENDED', 'GLOBAL_CONFIG_UPDATED'
-          ip_address VARCHAR(45) NOT NULL, -- IPv4 or IPv6 support
-          user_agent TEXT NULL,
-          payload_old JSONB NULL,        -- Güncelleme öncesi ham veri satırı (veri eklemede NULL)
-          payload_new JSONB NULL,        -- Güncelleme sonrası ham veri satırı (veri silmede NULL)
-          created_at TIMESTAMPTZ DEFAULT NOW()
-      );
-      CREATE INDEX idx_central_audit_logs_event ON central_audit_logs(event_type);
-      CREATE INDEX idx_central_audit_logs_muni ON central_audit_logs(municipality_id);
-      CREATE INDEX idx_central_audit_logs_created ON central_audit_logs(created_at);
-      ```
-*   **Merkezi Statik İçerik Yönetimi (`central_static_contents` tablosu)**: SaaS paneli üzerinden "Hakkımızda", "KVKK", "Gizlilik" gibi metinlerin başlık ve içeriklerini yönetmek için kullanılır.
-
-    **Public Web Yol Haritası için Genişletme Önerisi (V1):**
-    - `public_web_roadmap_mvp` → MVP sürümü yol haritası içeriği
-    - `public_web_roadmap_v1` → V1 sürümü yol haritası içeriği
-
-    **Migration Önerisi (Mevcut tabloyu bozmadan):**
-
-    ```sql
-    -- MVP Yol Haritası
-    INSERT INTO central_static_contents (key, title, content, updated_at)
-    VALUES (
-        'public_web_roadmap_mvp',
-        'MVP Sürümünde Neler Var?',
-        '# MVP Sürümünde Neler Var?\n\n- Temel raporlama ve takip\n- +1 desteği\n- Temel katılım araçları\n- ...',
-        NOW()
-    )
-    ON CONFLICT (key) DO NOTHING;
-
-    -- V1 Yol Haritası
-    INSERT INTO central_static_contents (key, title, content, updated_at)
-    VALUES (
-        'public_web_roadmap_v1',
-        'V1 Sürümünde Gelen Özellikler',
-        '# V1 Sürümünde Gelen Özellikler\n\n- Gelişmiş harita deneyimi\n- AI destekli öneriler\n- ...',
-        NOW()
-    )
-    ON CONFLICT (key) DO NOTHING;
-    ```
-
-    **Not:** Schema değişikliği gerekmez. Sadece yeni satır INSERT yeterlidir. Central Admin panelinden güncellenen içerikler bu key’ler üzerinden tutulur.
-    - **`central_static_contents` SQL Tablo Şeması:**
-      ```sql
-      CREATE TABLE central_static_contents (
-          key VARCHAR(50) PRIMARY KEY,
-          title VARCHAR(200) NOT NULL,
-          content TEXT,
-          updated_at TIMESTAMPTZ DEFAULT NOW()
-      );
-      CREATE INDEX idx_central_static_contents_updated ON central_static_contents(updated_at);
-      ```
-*   Global Vatandaş Kayıtları (`citizen` tablosu): Vatandaş kimlik, iletişim ve asenkron doğrulanmış T.C. kimlik bilgileri central düzeyde saklanır.
-
-### B. Belediye Veritabanları / Şemaları (İzole Katman)
-Her belediye kendi verilerini izole bir şemada (`schema_muni_a`) veya bağımsız veritabanı sunucularında tutar. 
-*   **İş Emirleri & Vatandaş Raporları**: Sadece ilgili belediye şemasına ait UUIDv4 kayıtları. `work_orders` tablosunda public harita alanlarının yanı sıra, müdür bypass atamasını ve geofence bypass durumunu yöneten `is_manager_bypassed` (BOOLEAN DEFAULT FALSE) ve `geofence_bypass_requested` (BOOLEAN DEFAULT FALSE) alanları; kronik sorunları birbirine bağlayan `parent_reopened_work_order_id UUID NULL (ref: work_orders.id ON DELETE SET NULL)` alanı; ve iş emri oluşturulduğu andaki PostGIS belediye sınır sürümünü işaret eden `boundary_version_id UUID NULL (ref: municipal_boundary_versions.id)` alanı mevcuttur. Sınır geometrisinin her satırda tekrarlanması engellenerek depolama alanı şişmesi (bloating) önlenmiştir. RLS ve veri güvenliği politikaları bu alanları da kapsar.
-*   **Vatandaş Referansları**: Belediyeler vatandaş verilerine doğrudan erişemez; iş emirlerinde ve oylarda sadece Central SaaS DB'deki vatandaş kaydına ait `citizen_id` (UUID) referans olarak tutulur. GDPR silme taleplerinde sadece ilişkiler maskelenir.
-
-**Vatandaş Harita Deneyimi Notu:** Ana sayfa (`/`) doğrudan public harita olarak açılır. İlk açılış **Türkiye geneli** (düşük zoom) seviyesinde başlar. Kullanıcı zoom yaptıkça ve haritayı kaydırdıkça sistem otomatik olarak il → ilçe → mahalle → sokak seviyesine iner.
-
-**Statik İçerikler:** Hakkımızda, SSS, Gizlilik Politikası, KVKK, Kullanım Koşulları ve İletişim gibi yasal/bilgilendirici içerikler artık ayrı tam sayfa olarak değil, ana sayfadaki public harita üzerinden modal olarak açılır.
-*   **Destek Oyları (support_votes) & Sayaç (support_count)**: Çözülmemiş sorunlara verilen oyları tutan `support_votes(id, work_order_id, citizen_id, created_at)` tablosu ile `(work_order_id, citizen_id)` üzerinde UNIQUE constraint uygulanır.
-    **Ölçeklenebilirlik & Row-Locking Önleme Tasarımı:** Popüler veya kriz anındaki şikayetlerde oluşabilecek yoğun "+1" isteklerinin `work_orders` tablosunda row-lock (satır kilitleme) darboğazı yaratmasını engellemek için, oylar doğrudan `support_votes` tablosuna yazılır (INSERT işlemi kilit oluşturmaz). `work_orders.support_count` (INTEGER DEFAULT 0) sayacı ise gerçek zamanlı DB trigger yerine, PostgreSQL LISTEN/NOTIFY tabanlı bir sayaç/kuyruk üzerinden debounced asenkron worker ile (örn. 5 dakikalık aralıklarla toplu / bulk update şeklinde) PostgreSQL'e yansıtılarak ana operasyonel tabloların kilitlenmesi önlenir.
-*   **Personel & Roller**: Belediyenin kendi bünyesindeki müdür, şef ve saha çalışanları.
-*   **Coğrafi Sınurlar ve Sürüm Kontrolü (Boundaries & Versions)**: Belediyenin PostGIS sınır poligonları, depolama şişmesini önlemek amacıyla `municipal_boundary_versions` tablosunda sürüm kontrolüyle saklanır.
-    - **municipal_boundary_versions Tablo Yapısı:**
-      - `id UUID PRIMARY KEY DEFAULT gen_random_uuid()`
-      - `municipality_id UUID (ref: municipalities.id)`
-      - `boundaries GEOMETRY(MultiPolygon, 4326) NOT NULL` (PostGIS sınır poligonu)
-      - `active_from TIMESTAMPTZ NOT NULL`
-      - `active_to TIMESTAMPTZ NULL` (Mevcut sürüm için NULL)
-      - `created_at TIMESTAMPTZ DEFAULT NOW()`
-*   **Belediye Düzeyi Denetim Logları (`audit_logs` tablosu)**: Belediyenin kendi süreç içi denetim kayıtları. İş emirleri güncellemeleri, durum değişiklikleri, personel atamaları ve geofence bypass onayları gibi tüm kritik veri modifikasyonları, işlemin öncesi ve sonrası raw halini (JSONB) içerecek şekilde kaydedilir. KVKK silme talebi kapsamında yapılacak asenkron regex maskeleme sorgularında tam tablo taramasını (Full Table Scan) önlemek amacıyla, `audit_logs` tablosunda indeksli bir `citizen_id` (UUID NULL) kolonu bulundurulması zorunludur.
-    - **`audit_logs` SQL Tablo Şeması:**
-      ```sql
-      CREATE TABLE audit_logs (
-          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-          tenant_id VARCHAR(50) NOT NULL,
-          user_id UUID NOT NULL,            -- İşlemi gerçekleştiren belediye personeli (müdür/şef/saha)
-          citizen_id UUID NULL,             -- İşleme konu olan vatandaş (KVKK maskeleme performansı için İNDEKSLİ)
-          work_order_id UUID NULL,          -- İşleme konu olan iş emri UUID referansı
-          event_type VARCHAR(50) NOT NULL,   -- örn: 'WORK_ORDER_STATUS_CHANGED', 'GEOFENCE_BYPASS_APPROVED', 'DISPUTE_RESOLVED'
-          ip_address VARCHAR(45) NOT NULL,
-          user_agent TEXT NULL,
-          payload_old JSONB NULL,           -- Güncelleme öncesi ham veri satırı (veri eklemede NULL)
-          payload_new JSONB NULL,           -- Güncelleme sonrası ham veri satırı (veri silmede NULL)
-          created_at TIMESTAMPTZ DEFAULT NOW()
-      );
-      CREATE INDEX idx_audit_logs_tenant ON audit_logs(tenant_id);
-      CREATE INDEX idx_audit_logs_citizen_id ON audit_logs(citizen_id) WHERE citizen_id IS NOT NULL; -- KVKK performansı için kısmi indeks
-      CREATE INDEX idx_audit_logs_work_order ON audit_logs(work_order_id);
-      CREATE INDEX idx_audit_logs_event_created ON audit_logs(event_type, created_at);
-      ```
-*   **Uyuşmazlık Kayıtları (dispute_logs)**: Çevrimdışı senkronizasyon çakışmalarını izler. Şef onay ekranında bütçe/hak ediş kayıplarını ve mükerrer ödemeleri engellemek için veritabanı seviyesinde çalışan "Çift Hak Ediş Uyarısı (Double Payment Alert)" tetikleyici (trigger) mekanizması entegre edilmiştir.
-*   **IoT Cihaz Tanımları & Alan Eşleştirmeleri**: Belediyenin kendi envanterine kayıtlı IoT aygıtları, API anahtarı eşleşmeleri ve admin tarafından tanımlanmış "Custom Payload Mapping" (GUI/JS Parser) kuralları. **V8 Sandbox Kısıtları & Pre-Filtering:** Güvenlik ve kaynak tüketimini kontrol altında tutmak için parser'a girmeden önce ham telemetri payload boyutu **maksimum 10KB** ile sınırlandırılır. Izole parser scriptleri, CPU tüketimini sınırlandırmak için **maksimum 50ms CPU zamanı** ve **maksimum 16MB RAM** ile sınırlandırılmıştır. Harici network veya disk işlemleri kesinlikle engellenmiştir.
-*   **Telemetri Logları (Telemetry Logs)**: Sensörlerden gelen ham ve parse edilmiş geçmiş veriler (yalnızca ilgili belediyenin şemasında saklanır).
-
-### C. PostgreSQL Satır Bazlı Güvenlik (Row-Level Security - RLS)
-Belediyeler aynı fiziksel veritabanı kümesini paylaşsa dahi, RLS politikaları sayesinde veri sızıntısı imkansız hale getirilir. 
-
-#### Örnek RLS Politikası (SQL Örneği):
-```sql
--- İş emirleri tablosunda Row-Level Security aktifleştirme
-ALTER TABLE work_orders ENABLE ROW LEVEL SECURITY;
-
--- Sadece kullanıcının JWT token'ından gelen tenant_id ile eşleşen satırları okuma politikası
-CREATE POLICY tenant_isolation_policy ON work_orders
-    USING (tenant_id = current_setting('app.current_tenant_id'));
-
--- Anonim/Public Harita Okuma RLS Politikası
-CREATE POLICY public_map_read_policy ON work_orders
-    FOR SELECT
-    USING (is_public_visible = TRUE AND status NOT IN ('pending', 'rejected'));
-```
-
-#### Halka Açık Görünüm Katmanı (public_work_orders_view)
-Anonim `GET /v1/public/reports` istekleri için doğrudan tablolara erişim yerine `public_work_orders_view` üzerinden veri sunulur. Bu view:
-1. Kişisel verileri (`citizen_id`, ad, soyad, telefon, e-posta) sunucu seviyesinde filtreler (dışlar).
-2. Tam GPS koordinatları yerine ±0.0005° (yaklaşık 50m) fuzzing (sapma) uygulanmış `approximate_coordinates` projekte eder.
-3. RLS politikaları doğrultusunda sadece public görünür ve modere edilmiş verileri anonim istemcilere açar.
-
-Bu sayede `app.current_tenant_id` ayarı `muni_a` olan bir kullanıcının sorgusu ne olursa olsun veritabanı seviyesinde `muni_b` satırlarına erişmesi engellenir.
-
----
-
-## 3. Central Reverse Proxy ve API Yönlendirme Mimarisi
-
-KENTİM platformunda, istemciler (Vatandaş Web/Mobil, Belediye Paneli, Central Panel) ve belediye backend servisleri arasındaki API iletişimi, **Central Reverse Proxy (Merkezi Ters Proxy)** katmanı aracılığıyla güvenli, izole ve dinamik olarak yönetilir. Bu mimaride, belediyelerin backend sunucuları doğrudan internete maruz kalmaz; tüm trafik merkezi proxy üzerinden güvenli tünellerle yönlendirilir.
-
-```mermaid
-sequenceDiagram
-    autonumber
-    actor Client as İstemci (Belediye Paneli / Vatandaş)
-    participant Proxy as Central Reverse Proxy (api.kentim.com.tr)
-    participant CentralDB as Central SaaS DB
-    participant MuniBackend as Belediye Backend (muni_a_backend)
-
-    Client->>Proxy: POST /v1/work-orders (Authorization: Bearer <JWT>)
-    Proxy->>Proxy: 1. JWT imzasını doğrula ve çöz
-    Proxy->>Proxy: 2. tenant_id (muni_a) ve rol bilgilerini ayıkla
-    Proxy->>CentralDB: 3. Abonelik durumunu kontrol et (Lisans Aktif mi?)
-    CentralDB-->>Proxy: Aktif (muni_a aktif lisans)
-    Proxy->>Proxy: 4. RLS için app.current_tenant_id bağlamını set et
-    Proxy->>MuniBackend: 5. İsteği güvenli tünelle (VPN) ilet (x-tenant-id: muni_a)
-    MuniBackend->>MuniBackend: 6. PostgreSQL RLS & Sorgu kapsamını işlet
-    MuniBackend-->>Proxy: 7. Yanıt Verileri (JSON)
-    Proxy-->>Client: 8. HTTP 200 OK / 201 Created
-```
-
-### Anonim Public-Read Akış Diyagramı
-Central Reverse Proxy'nin JWT gerektirmeyen public okuma isteklerini nasıl yönettiğini gösteren süreç diyagramıdır:
-
-```mermaid
-sequenceDiagram
-    autonumber
-    actor Client as Anonim İstemci (Vatandaş Web)
-    participant Proxy as Central Reverse Proxy (api.kentim.com.tr)
-    participant CacheDB as DB (public_map_cache)
-    participant MuniBackend as Belediye Backend (muni_a_backend)
-
-    Client->>Proxy: GET /v1/public/reports?municipality_id=muni_a&bbox=... (JWT'siz)
-    Proxy->>Proxy: 1. Rate limit kontrol et (IP başına maks 60 req/min)
-    Proxy->>CacheDB: 2. Önbellek kontrol et (tenant_id = muni_a AND bbox_hash)
-    alt Önbellek İsabeti (Cache Hit)
-        CacheDB-->>Proxy: Önbellekteki veriyi (fuzzing uygulanmış JSON) dön
-        Proxy-->>Client: 200 OK (Cache-Control: max-age=30)
-    else Önbellek Iskalama (Cache Miss)
-        Proxy->>MuniBackend: 3. İstek yönlendir (x-tenant-id: muni_a)
-        MuniBackend->>MuniBackend: 4. DB seviyesinde public_work_orders_view sorgula (fuzzing & masking uygulanır)
-        MuniBackend-->>Proxy: 5. Yanıtı dön (JSON)
-        Proxy->>CacheDB: 6. Sonucu unlogged cache tablosuna yaz (expires_at: now + 30s)
-        Proxy-->>Client: 7. 200 OK (Cache-Control: max-age=30)
-    end
-```
-
-
-### A. Central Reverse Proxy ve Tenancy Çözümleme Mantığı
-Tüm istemciler API isteklerini ortak ağ geçidi olan `https://api.kentim.com.tr` adresine gönderir. İletişim akışı şu şekildedir:
-1. **Kimlik ve Kiracı Doğrulama (Auth & Tenancy Resolution):** Gelen her istekteki JWT token'ı proxy katmanında çözülür. Token içerisinden `tenant_id` (örn: `muni_a`) ve kullanıcının yetki rolü (örn: `muni_department_manager`) doğrulanır.
-   - **JWT'siz Public Endpoint İstisnası:** `GET /v1/public/reports` endpoint'i JWT yetkilendirmesi gerektirmez. Kiracı tespiti URL sorgu parametrelerindeki `?municipality_id` veya `?city_slug` ile yapılır. Bu endpoint için IP başına 60 istek/dakika hız sınırı (rate limit) uygulanır. Yanıtlar sunucuda `Cache-Control: max-age=30` ile döner.
-2. **Lisans / Abonelik Durum Denetimi (Licensing Gateway):** 
-   - Proxy, `tenant_id` üzerinden Central SaaS veritabanında lisans durumunu sorgular.
-   - Lisans aktif ise istek yönlendirilir.
-   - **402 Grace Period Durumu:** Lisansın süresi dolmuşsa ve belediye askıya alınmışsa; proxy gelen `POST`, `PUT`, `PATCH`, `DELETE` (yazma/güncelleme) isteklerini `402 Payment Required` hatası ile keser. Ancak, 7 günlük "grace period" (hoşgörü süresi) dahilinde, saha ekiplerinin iş tamamlaması için `pending_chief_approval` durumuna geçiş ve müdürlerin "Mevcut İşi Yeniden Atama (`re-assign`)" isteklerine özel olarak izin verir. `GET` (okuma) ve public harita (`GET /v1/public/reports`) istekleri grace period ve askıya alınma durumlarında da kesintisiz devam eder.
-3. **Güvenli Yönlendirme (Secure Forwarding / Tunneling):** 
-   - Doğrulamadan geçen istekler, ilgili belediyenin Kubernetes iç ağındaki servisine (`http://muni-a-backend.internal:4000`) veya belediyenin kendi özel sunucusuna, proxy ile backend arasında kurulmuş güvenli bir VPN tüneli (örn: WireGuard/IPsec) üzerinden yönlendirilir. İsteğe `x-tenant-id: muni_a` header'ı eklenir.
-
-> [!WARNING]
-> **JWT'siz Public Endpoint Güvenlik Uyarısı:** `GET /v1/public/reports` endpoint'i JWT token korumasına tabi tutulmadığı için kasıtlı olarak veritabanı view katmanı (`public_work_orders_view`) ile sınırlandırılmıştır. Ham tablolara anonim erişim kesinlikle engellenmiştir ve view seviyesindeki PostGIS fuzzing ile RLS koruması devrededir.
-
-
-### B. Belediye Paneli ve API İletişimi (Panel-to-Backend Proxying)
-*   **Tek Ön Yüz Uygulaması (Shared Frontend):** Belediye Paneli (`panel.kentim.com.tr`) tüm belediyelerin ortak kullandığı tek bir web uygulamasıdır. Giriş yapan personelin tarayıcısına yüklenen ön yüz, arka planda hangi belediyeye ait olduğunu sadece JWT içindeki `tenant_id` sayesinde bilir.
-*   **Direct API Maskeleme:** Belediye paneli, belediyelerin gerçek API sunucu adreslerini (IP veya özel URL'lerini) asla bilmez. Tüm istekler `api.kentim.com.tr` proxy'sine gönderildiği için belediye altyapısı doğrudan internetten gelebilecek saldırılara (DDoS, Brute Force, Port Taraması) karşı tamamen maskelenmiştir.
-
-### C. Central Admin ve Belediye Backend İletişimi (Central-to-Backend Command Pipeline)
-Central Admin (`central.kentim.com.tr`) panelinden tetiklenen global komutların (örn: **Afet Modu** veya **Heartbeat Sağlık Kontrolü**) belediye backend'lerine güvenli bir şekilde iletilmesi için çift yönlü bir iletişim boru hattı kurulmuştur:
-
-1. **Belediye -> Central (Push & Heartbeat):**
-   - **Heartbeat:** Belediye backend'leri her 1 dakikada bir Central API'ye `/v1/central/heartbeat` uç noktası üzerinden sinyal gönderir. Central Admin bu sayede sistem sağlığını izler.
-   - **İstatistik Push:** Her belediye 15 dakikada bir veritabanından derlediği anonimleştirilmiş iş/SLA istatistiklerini Central API'ye push eder.
-2. **Central -> Belediye (Secure Command Loopback):**
-   - Central Admin, seçili bir belediyede afet modunu tetiklemek veya lisans durumunu zorla güncellemek istediğinde, Central Proxy ilgili belediye backend'inin kayıtlı **"Command Loopback"** adresine istek gönderir.
-   - Bu isteklerin güvenliği, Central ve Belediye backend'i arasında önceden paylaşılmış olan **HMAC-SHA256 Master Key** (API Secret) ile sağlanan bir imza doğrulama adımıyla (`x-kentim-signature`) korunur. Belediye backend'i imzayı doğrulamadan komutu çalıştırmaz.
-
----
-
-## 4. Çok Belediyeli Operasyonel Kurallar & Çakışma Yönetimi
-
-Birden fazla belediyenin aynı anda aktif çalışması nedeniyle oluşabilecek çakışmalar (conflict) şu kurallarla çözülmüştür:
-
-### 1. Akıllı Konum Tabanlı Yönlendirme (Geofencing Router)
-*   Vatandaş bir sorun raporladığında, koordinatlar (GPS) paylaşılan **Tenant Router** motoruna gönderilir.
-*   Sistem, basit bir bounding box yerine doğrudan hassas sınır poligonunu kullanarak, koordinatın hangi belediyenin PostGIS sınır poligonu (`boundaries`) içerisinde yer aldığını **`ST_Contains`** fonksiyonu ile coğrafi veritabanı düzeyinde anlık tespit eder.
-*   Tespit edilen belediyenin `tenant_id` değeri rapora otomatik işlenir ve o belediyenin moderasyon kuyruğuna aktarılır.
-*   **Sınır Çakışması & Yetki Ayrım Kuralı (Overlap & Category-Based Routing):** Büyükşehir belediyesi ve ilçe belediyesi gibi sınırları tamamen örtüşen/çakışan yetki alanlarında sistem şu akıllı mekanizmaları işletir:
-    1. **Kategori Bazlı Akıllı Yönlendirme:** Yönlendirme motoru sadece koordinata değil, seçilen **kategoriye** de bakar. Örneğin, çakışan alanda "Ana Arter Temizliği/Bakımı", "Metro Hatları", "Su/Kanalizasyon Şebekesi" gibi büyükşehir yetkisindeki kategoriler doğrudan Büyükşehir Belediyesi `tenant_id`'sine; "Sokak Çöpü", "Mahalle Parkı Bakımı" gibi ilçe yetkisindeki kategoriler ise İlçe Belediyesi `tenant_id`'sine otomatik yönlendirilir.
-    2. **Belediyeler Arası Sevk (Cross-Tenant Referral):** Eğer bir rapor sistemsel olarak yanlış belediyeye atanırsa, ilgili belediyenin moderatörü raporu reddetmek yerine tek butonla çakışan diğer belediyeye (örn: İlçeden Büyükşehire) sevk edebilir. Bu durumda rapor eski belediyede referanslı kapatılarak, yeni belediyenin moderation kuyruğuna asenkron olarak aktarılır. Böylece vatandaşın şikayeti iptal edilmemiş olur.
-    3. **Fallback:** Kategoriden ayrım yapılamayan veya tam çakışan belirsiz koordinatlarda `central_admin`'in `priority_order` (öncelik sırası) değeri referans alınır. Birden fazla belediyenin tam çakışması ve çözülememesi durumunda koordinat manuel sevk edilmek üzere `central_admin` Disputes havuzuna düşer. Sınır poligonları `central_admin` tarafından haritadan dinamik olarak yönetilir.
-*   **İstisna**: Acil Durum / Panik Butonu sinyalleri, vatandaşın tahliye sırasında sınır dışına çıkabilmesi ihtimali nedeniyle coğrafi doğrulama engelinden (sınır poligonu kontrolünden) muaftır; en yakın koordinattaki belediyeye kriz masası sinyali iletilir.
- *   **Panik Butonu DDoS Koruması**: Panik butonu rate limiting kurallarından (IP bazlı) muaftır; istismarı önlemek amacıyla **Device ID doğrulama** zorunludur. Aynı Device ID'den dakikada maksimum **5 panik sinyali** kabul edilir; limiti aşan istekler HTTP 429 ile reddedilir (vatandaşa görünmez, sessizce). Device ID doğrulama `/devices/validate` endpoint'iyle yapılır.
-
-### 2. Küresel Kimlik Yapısı (Global UUID Mimarisi)
-*   Sistemde hiçbir kiracıda sıralı tamsayı (auto-increment ID) kullanılmaz.
-*   Tüm iş emirleri, raporlar ve kullanıcılar **UUIDv4** formatında küresel benzersiz kimliklere sahiptir.
-*   Bu sayede, merkezi veri analizlerinde veya merkezi raporlama ekranlarında veriler çakışmadan toplulaştırılabilir (aggregation).
-
-### 3. Bağımsız Çalışma Takvimleri (SLA & Business Hours)
-*   Her belediyenin (ve hatta müdürlüğün) kendi çalışma takvimi, resmi tatil tanımları ve vardiya saatleri bağımsızdır.
-*   SLA sayaçları hesaplanırken, iş emrinin bağlı olduğu `tenant_id` üzerinden ilgili belediyenin yerel çalışma takvimi referans alınır.
-*   **Kritik Kural**: `Acil` veya `Kriz` işaretli iş emirlerinde yerel çalışma saati dikkate alınmaz, 7/24 kesintisiz SLA işletilir.
-
-### 4. Lisans Durdurma / Askıya Alma Modu
-*   Abonelik süresi biten bir belediyenin arayüzleri **kısıtlı salt-okunur** moda çekilir.
-*   Bu durum diğer belediyelerin operasyonunu asla etkilemez.
-*   Askıya alınan belediyenin saha ekipleri, ellerindeki devam eden işleri tamamlayabilmek için **7 günlük "salt-tamamlama" (grace period)** modunda çalışabilir. Bu süre zarfında mevcut işlerin saha koordinasyonunu sağlamak amacıyla **"Mevcut İşi Yeniden Atama (Re-assign)"** işlemine izin verilir, ancak sisteme sıfırdan yeni iş emri veya vatandaş raporu kabul edilmez.
-
-### 5. Dinamik IoT Payload Dönüştürücü ve Telemetri İzolasyonu
-*   **Merkezi Geçit (SaaS Gateway) Katmanı:** Ortak uç noktaya (`/v1/integrations/iot/telemetry`) gelen tüm istekler Central SaaS Gateway tarafından karşılanır. İstekteki `Authorization` başlığındaki API anahtarı çözülerek hedeflenen belediyenin `tenant_id` değeri saptanır.
-*   **Dinamik Dönüştürme Motoru (Dynamic Payload Transformer):** Saptanan belediyenin izole veritabanı şemasındaki en güncel "Payload Mapping" kuralları veya "Custom Parser Script" kod bloğu sunucu üzerindeki paylaşımlı önbellek bellek katmanından (PostgreSQL Shared Buffers & Index Caching) hızlıca çekilir. **Önbellek Invalidation Kuralı:** Admin entegrasyon ayarını kaydettiğinde ilişkili yapılandırma verileri anında güncellenir ve veritabanı belleği invalidation'a uğramadan güncel veriyle senkronize olur. Cihazdan gelen ham JSON verisi, belediyenin kendi tanımladığı bu parser fonksiyonundan geçirilerek KENTİM standart şemasına (UUID, doluluk, arıza durumu, PostGIS koordinatları) dönüştürülür.
-*   **V8 Sandbox Kısıtları & Fastify API Decoupling:** Dynamic Payload Transformer'ın ham veriyi JS ile parse ettiği V8 sandbox motoru için şu kısıtlar geçerlidir: Payload boyutu max 10KB, maks çalışma süresi 50ms, maks bellek 16MB, ağ ve dosya sistemi erişimi yasak, sadece saf hesaplama işlemleri izinlidir.
-
-> **⚠️ V8 Sandbox ile İlgili Kritik Operasyonel Risk:**  
-> Belediyelerin kendi JavaScript parser scripti yazabilmesi, uzun vadede ciddi güvenlik ve bakım riski oluşturur. MVP aşamasında sandbox kısıtları (10KB / 50ms / 16MB) ile bu risk kısmen kontrol altına alınmıştır. Ancak script versiyonlama, kod inceleme (code review), rollback ve hata ayıklama mekanizmaları MVP'de sınırlıdır. Bu konu, "V8 Sandbox Yönetim Riski" olarak bilinçli kabul edilmiştir (bkz. yukarıdaki risk tablosu).
-    **Fastify API Asenkron Çözümleme Hattı (Decoupling):** Yoğun telemetri trafiğinin veya parser CPU kilitlenmelerinin ana Fastify API Gateway thread'ini dondurmasını engellemek amacıyla, parser motorunun çalıştırılması API thread'inden tamamen ayrıştırılmıştır. Gelen ham telemetri verileri anlık olarak **PostgreSQL unlogged tablosu** (`iot_telemetry_queue`) üzerine `INSERT` ile yazılır, ardından `pg_notify('iot_telemetry_channel', device_id)` komutuyla worker'lara sinyal gönderilir ve client'a `202 Accepted` dönülür. Kuyruktaki veriler, ana API'den bağımsız olarak `LISTEN iot_telemetry_channel` dinleyen **asenkron Warm Worker Node.js process'leri** tarafından arka planda sırayla `FOR UPDATE SKIP LOCKED` ile tüketilerek KENTİM standart şemasına dönüştürülür. **Mimari Karar:** Redis kullanılmaz; tüm asenkron kuyruk iletişimi PostgreSQL LISTEN/NOTIFY mekanizması üzerinden yönetilir.
-*   **PostgreSQL RLS Koruması:** Standart hale getirilen veri, veritabanı katmanında `app.current_tenant_id` bağlamı ile kaydedilir. Her belediyenin telemetri geçmişi, RLS politikaları doğrultusunda diğer belediyelerin erişiminden tamamen izole edilmiş bir şekilde kendi şemasında (`schema_muni_x`) saklanır.
-*   **6. Halka Açık Harita Önbellek ve Invalidation Politikası:**  
-    İstemcilerin gönderdiği `/v1/public/reports` istekleri için PostgreSQL üzerinde WAL yazmayan ultra hızlı unlogged `public_map_cache` tablosu (`tenant_id` + `bbox_hash` bazlı, 30 saniye TTL) kullanılmaktadır.
-    **Statik-Dinamik Veri Ayrıştırma & CDN Optimizasyonu:** Yoğun trafik altında harita cache invalidation ve CDN purge maliyetlerini engellemek amacıyla, **Harita Pin Verileri (koordinat, kategori, durum)** ile **Detay Verileri (fotoğraflar, destek oyları, dahili notlar)** API seviyesinde tamamen ayrıştırılır. 
-    1. Harita ilk yüklendiğinde ve kaydırıldığında çağrılan `GET /v1/public/reports` endpoint'i yalnızca hafif pin koordinatlarını döndürür ve 30 saniye boyunca CDN ve unlogged cache seviyesinde agresif olarak önbelleğe alınır.
-    2. Vatandaş bir pine tıkladığında açılan detay pop-up/drawer'ı için ayrı bir `GET /v1/public/reports/:public_id` endpoint'i çağrılır. Bu endpoint asenkron/debounced önbellekten güncel `support_count` ve fotoğraf URL'lerini çeker.
-    Bu sayede haritaya gelen her tekil "+1" desteği veya fotoğraf gizleme işlemi sonrasında tüm harita koordinat önbelleği ve CDN geçersiz kılınmak (purge edilmek) zorunda kalmaz. DB ve network maliyeti %90 oranında düşürülür.  
-    **Mevcut Durum:** Bu altyapı ve cache invalidation mekanizmaları ile CDN purge entegrasyonu tamamen tanımlanıp sisteme entegre edilmiştir.
-
-> **⚠️ Public Harita Ölçeklenebilirlik Riski (Kabul Edilmiş):**  
-> 30 saniyelik unlogged cache + BBOX bazlı dinamik yükleme + Leaflet clustering yaklaşımı, orta ölçekli belediyeler için yeterlidir. Ancak Türkiye geneli açılış + sokak seviyesine kadar zoom senaryosunda (özellikle büyükşehir belediyeleri) ciddi performans riski taşır. 
-> MVP aşamasında bu risk kabul edilmiştir. Erken yük testi ve gerekirse vector tile / pre-aggregate katman geçişi MVP sonrası planlanmalıdır.
-
-*MVP Sürümü — KENTİM Mimari Belgesi*
-
-## EK: Public Harita — Veritabanı, RLS ve Reverse Proxy Değişiklikleri
-
-### Belediye Veritabanı / Şema Güncellemeleri
-- `work_orders` tablosuna eklenecek alanlar: `is_public_visible BOOLEAN DEFAULT TRUE`, `public_hidden_reason TEXT NULL`, `public_hidden_at TIMESTAMPTZ NULL`, `public_hidden_by UUID NULL`, `boundary_version_id UUID (ref: municipal_boundary_versions.id)`, **`priority VARCHAR(10) NOT NULL DEFAULT 'normal' CHECK (priority IN ('low', 'normal', 'high', 'urgent', 'crisis'))`** (düşük/normal/yüksek/acil/kriz öncelik seviyeleri).
-- Yeni tablo: `municipal_boundary_versions(id UUID PRIMARY KEY DEFAULT gen_random_uuid(), municipality_id UUID, boundaries GEOMETRY(MultiPolygon, 4326) NOT NULL, active_from TIMESTAMPTZ NOT NULL, active_to TIMESTAMPTZ NULL, created_at TIMESTAMPTZ DEFAULT NOW())`. **Not:** Belediye sınırları birden fazla bağlantısız coğrafi parçadan (adalar, enklav bölgeler) oluşabileceğinden `MultiPolygon` tipi kullanılmaktadır.
-- Yeni tablo: `support_votes(id UUID, work_order_id UUID, citizen_id UUID, created_at TIMESTAMPTZ)` with UNIQUE(work_order_id, citizen_id).
-- Denormalize: `work_orders.support_count INTEGER DEFAULT 0` — row-locking darboğazını engellemek için asenkron debounced worker ile güncellenmektedir.
-
-### PostgreSQL RLS — Public Read Policy
-- Yeni policy: anonim GET istekleri için `public_map_read_policy`; yalnızca `is_public_visible = TRUE` ve `status NOT IN ('pending','rejected')` dönecek.
-- `public_work_orders_view` view'u uygulama için yalnızca güvenli alanları projekte edecek; koordinatlar ±0.0005° (≈50m) fuzzing uygulanmış `approximate_coordinates` şekilde dönecek. **`photo_urls` Alanı:** View içinde `photo_urls` alanı, `work_order_photos` tablosuna JOIN yapılarak `is_public_visible = TRUE` ve silinmemiş (aktif) fotoğraflar JSONB array olarak aggregate edilir. Gizlenmiş veya silinmiş fotoğraflar view çıktısına yansıtılmaz.
-
-### Central Reverse Proxy — Yeni Public Endpoint
-- `GET /v1/public/reports` JWT gerektirmez; proxy middleware zinciri: JWT atlanır, tenant tespiti `?municipality_id` veya `?city_slug` ile yapılır, IP başına 60 req/min rate limit uygulanır, yanıt `public_work_orders_view` üzerinden döner, `Cache-Control: max-age=30` eklenir.
-- `POST /v1/public/reports/:id/support` ise JWT zorunlu (hesaplı kullanıcılar için +1 desteği).
-
-### Lisans / 402 Grace Period İstisnası
-- `GET /v1/public/reports` endpointi 402 (abonelik bitiş) durumunda bloke edilmez; yalnızca yazma işlemleri engellenir.
-
-### Public Cache Invalidation Kuralı (Operasyonel)
-- Bir iş emrinin `status`, `is_public_visible` veya `support_count` alanı değiştiğinde ilgili tenant'ın `public_map_cache` tablosundaki tüm önbellek satırları transactional delete ile temizlenir.
-
-Bu eklemeler public harita performansı, KVKK uyumu ve anonim okuma güvenliği için zorunludur.
-
-### EK - JWT'siz Public Endpoint Güvenlik Notu ve Anonim Akış
-
-1) Güvenlik Notu (Section 3A genişletme)
-- `GET /v1/public/reports` JWT gerektirmese bile ham tabloya doğrudan erişim **yoktur**. Proxy sadece `public_work_orders_view` view'unu sunar; kişisel veri proje seviyesinde view ile dışlanır. Bu istisna, proxy katmanında özel rate-limit, IP kısıtlaması ve response projection ile korunur. Dokümana açık bir güvenlik uyarısı eklenecektir.
-
-2) Anonim Public-Read Akış Diyagramı (Section 3 Sequence Diagram genişletme)
-- Central Reverse Proxy için ayrı bir JWT'siz akış diyagramı eklenmelidir. Kısa akış:
-    - Client -> Proxy: `GET /v1/public/reports?municipality_id=...&bbox=...` (Anonim)
-    - Proxy: tenant tespiti (query param), rate-limit kontrolü, cache (public_map_cache) kontrolü
-    - Proxy -> MuniBackend: `SELECT` via `public_work_orders_view` (db-level projection)
-    - Proxy -> Client: 200 OK + maskelenmiş `public_work_orders_view` verisi
-
-Bu not ve diyagram eklentisi belgenin güvenlik bölümüne entegre edilecektir.
-
----
-
-## Mimari Dayanıklılık, Önbellek Hata Yönetimi ve Asenkron İşlem Mimarisi
-
-> **Mimari Karar:** KENTİM'de Redis kullanılmaz. Tüm asenkron kuyruk, bildirim ve IPC iletişimi PostgreSQL'in yerel **LISTEN/NOTIFY** mekanizması ve **unlogged tablolar** aracılığıyla yönetilir. Bu karar; bağımlılığı azaltır, belediye backend'lerinin "indir–ayarla–çalıştır" kurulum modeliyle tam uyumlu olmasını sağlar ve Redis yönetimi gerektirmeyen operasyonel sadeliği korur.
-
-> **⚠️ Kritik Mimari Risk (Kabul Edilmiş):**  
-> LISTEN/NOTIFY + unlogged tablo stratejisi, sistemin **en önemli operasyonel risklerinden biridir**. Özellikle afet modu, viral şikayet dalgası veya aynı anda binlerce destek oyu gibi yüksek eşzamanlılık senaryolarında şu riskler mevcuttur:
-> - PostgreSQL connection pool'unun LISTEN bağlantıları tarafından tüketilmesi
-> - `pg_notify` mesajlarının kaybolması (notify storm / queue overflow)
-> - Worker process'lerinin yeniden bağlanamaması durumunda kuyruk birikmesi
-> 
-> Bu risk **MVP aşamasında bilinçli olarak kabul edilmiştir**. Detaylı mitigation stratejileri ve kapasite test zorunlulukları D4 bölümünde tanımlanmıştır. Üretim ortamına alınmadan önce her belediye backend'inin D4'te belirtilen yük testlerini geçmiş olması **zorunludur**.
-
-> **Önerilen Ek Mitigation (V1):** Kritik kuyruklar (panic, dispute, notification DLQ) için V1 sürümünde hafif bir managed queue (Amazon SQS, RabbitMQ veya Cloud Tasks) ile hibrit mimariye geçilmesi önerilir. Detaylar için `proje.md` → KENTİM Sürüm Yol Haritası bölümüne bakınız.
-
-Sistem mimarisi, yüksek yük ve kesinti senaryolarına karşı operasyonel sürekliliği korumak amacıyla şu hata yönetimi ve yedekleme (resilience) modelleriyle donatılmıştır:
-
-### 1. Önbellek Iskalama Davranışı ve Doğrudan Veritabanı Fallback Akışı (Cache Miss Fallback)
-* İstemci `GET /v1/public/reports` isteği gönderdiğinde Central Proxy `public_map_cache` tablosunda `bbox_hash` kontrolü yapar.
-* **Cache Miss (Önbellek Iskalama) Durumu:**
-  1. Proxy, isteği doğrudan ilgili belediyenin backend'ine VPN tüneli üzerinden yönlendirir.
-  2. Belediye backend'i `public_work_orders_view` üzerinden veri tabanını RLS kurallarıyla sorgular.
-  3. Alınan veri istemciye döndürülürken eşzamanlı olarak asenkron bir `Promise` (arka planda, istek yanıtını geciktirmeden) ile unlogged `public_map_cache` tablosuna 30 saniyelik TTL ile yazılır.
-* **Veritabanı Koruma Bariyeri (Mutex Lock):** Çok yüksek eşzamanlı istek altında aynı `bbox_hash` için önbellek bulunamadığında veritabanının kilitlenmesini engellemek için **Single Flight / Mutex Lock** deseni uygulanır. Aynı anda gelen özdeş 100 sorgudan sadece 1 tanesi veritabanına gönderilir, diğer 99 istek bu sorgunun dönmesini ve önbelleğe yazılmasını bekleyerek doğrudan önbellekten yanıt alır.
-
-### 2. Asenkron `support_count` Debouncer Mimarisi (PostgreSQL Tabanlı)
-`support_votes` tablosuna gelen yoğun "+1" oylarının `work_orders.support_count` sayacına row-locking yaratmadan yansıtılması için **tamamen PostgreSQL tabanlı debounce mimarisi** kullanılmaktadır:
-* **Kuyruk Tablosu:** `support_count_queue` adlı **unlogged tablo** kullanılır. Her "+1" oyu bu tabloya `INSERT` ile yazılır; INSERT işlemi row-lock oluşturmaz.
-* **Worker Tetikleme:** `INSERT` sonrasında `pg_notify('support_count_channel', work_order_id)` ile worker Node.js process'i tetiklenir.
-* **Debounced Bulk UPDATE:** `LISTEN support_count_channel` dinleyen worker, gelen bildirimleri **300ms** bekler (debounce), ardından biriktirilen tüm `work_order_id`'leri tek bir `UPDATE work_orders SET support_count = (SELECT COUNT(*) FROM support_votes WHERE work_order_id = id) WHERE id = ANY(:ids)` bulk sorgusuyla işler.
-* **Bellek Koruması (Fallback):** Worker'ın beklenmedik şekilde yeniden başlaması durumunda işlenemeyen kuyruk satırları `support_count_queue` tablosunda kalır ve worker tekrar ayağa kalktığında otomatik olarak işlenir. Maksimum 10,000 işlenmemiş satır biriktiğinde worker bulk flush gerçekleştirir.
-* **İzleme:** Tüm batch işlemler `SUPPORT_COUNT_FLUSH` log tipiyle Pino logger'a yazılır.
-
-### 3. Dinamik Özel Raporlama ve Sayfalama (Pagination) Altyapısı
-* **Read-Replica İzolasyonu:** Belediye yöneticileri tarafından **Custom Report Builder** ile yapılan dinamik raporlama ve sorgulamalar, operasyonel veritabanına ek yük bindirmemek amacıyla **salt-okunur veritabanı kopyaları (Read-Replicas)** üzerinden yürütülür.
-* **Merkezi Konsolidasyon ve SaaS Analitik DB:** Central SaaS panelindeki **Yönetici Sunum Raporları (Executive Presentation-Ready Reports)** için sorgulamalar, tenant'lar arasındaki RLS sınırlarını (cross-tenant leak) ihlal etmemek adına ham belediye veritabanlarına doğrudan dokunmaz. Arka planda çalışan asenkron bir **ETL Scheduler** (cron / event-driven worker) servisi, her belediye şemasındaki verileri anonimleştirip agrege ederek Central SaaS veritabanındaki `central_analytics_metadata` tablosuna aktarır. Sunum raporları doğrudan bu merkezi analitik tablodan beslenir.
-* **Veri Sayfalama (Sayfalama - Pagination) Zorunluluğu:** Platformdaki tüm listeleme endpoint'lerinde (`GET /v1/worker/tasks`, `GET /v1/admin/audit-logs`, `GET /v1/admin/reports/chronic` vb.) ve Leaflet harita veri pin çekme akışlarında, bellek tükenmesini engellemek için **sayfalama (pagination)** kullanımı zorunludur. Performans ve ölçeklenebilirlik için:
-  - **Cursor-based Pagination (Keşifsel Sayfalama):** Sürekli güncellenen anlık listelerde (örn: iş emri kuyruğu) mükerrer kayıt veya satır atlama sorununu önlemek için `next_cursor` (UUID veya timestamp) ve `limit` parametreleri kullanılır.
-  - **Offset-based Pagination (Sayfa Bazlı Sayfalama):** Denetim logları gibi statik tarihsel aramalarda `page` ve `limit` parametreleri tercih edilir.
-  - **Leaflet BBOX Sayfalama:** Leaflet Map viewport sınırlarına göre yapılan coğrafi sorgulamalarda, tek seferde çekilen pin sayısı `limit` parametresiyle sınırlanır ve harita hareket ettikçe dinamik olarak chunk'lar halinde yüklenir.
-
-### Kritik Mimari Risklerin Özeti (MVP Kapsamı)
-
-Aşağıdaki riskler, **"MVP'yi hızlı ve basit şekilde dağıtılabilir kılmak"** hedefiyle bilinçli olarak kabul edilmiştir. Her birinin gerekçesi ve etkisi aşağıda belirtilmiştir.
-
-| Risk Alanı                              | Kabul Seviyesi | Gerekçe (Neden Kabul Ediyoruz?) | Yüksek Yükteki Etki | Mevcut Kontrol | V1 Önerisi |
-|-----------------------------------------|----------------|----------------------------------|---------------------|----------------|------------|
-| PostgreSQL LISTEN/NOTIFY + Unlogged     | Bilinçli Kabul | Redis bağımlılığını ortadan kaldırarak belediye dağıtımını basitleştirmek | Connection exhaustion, notify kaybı, kuyruk birikmesi | Debounce + bulk processing, D4 kapasite test zorunluluğu | Kritik kuyruklar için hibrit managed queue |
-| Tamamen PostgreSQL bağımlılığı          | Bilinçli Kabul | Operasyonel basitlik ve tek veritabanı avantajı | Tek hata noktası, ölçeklenebilirlik sınırlaması | Read replica + unlogged tablo tasarımı | Önemli kuyruklar için SQS/RabbitMQ |
-| Belediye backend'lerinin basit dağıtımı | Bilinçli Kabul | "İndir .env çalıştır" modelini mümkün kılmak | Operasyonel olgunluğu düşük belediyelerde ciddi sorun | D1-D5 operasyonel standartlar | CI/CD pipeline + artifact signing + monitoring |
-| V8 Sandbox ile custom parser            | Bilinçli Kabul | Belediyelere esnek IoT entegrasyonu sunmak | Güvenlik açığı, bakım maliyeti, kod kalitesi sorunu | 10KB / 50ms / 16MB limit + DLQ | Parser script için approval + versiyonlama süreci |
-
-**Sonuç:** KENTİM SaaS mimarisi, yüksek trafik ve altyapı kesintilerine karşı büyük ölçüde dayanıklı hale getirilmiştir. Ancak operasyonel başarı; multi-tenant migration disiplini, secret rotasyon prosedürleri, düzenli restore drill'leri ve LISTEN/NOTIFY kapasite testlerine sıkı bağlıdır. Yukarıdaki riskler MVP aşamasında **"basit dağıtım"** hedefiyle bilinçli olarak kabul edilmiştir.
-
----
-
-## 5. Belediye Sunucusu Hızlı Dağıtım ve Central Sağlık Monitör Standartları
-
-### A. Belediye Backend Hızlı Kurulum Modeli (indir .env ayarla çalıştır)
-
-**⚠️ Önemli Uyarı:** Bu model, teknik olarak mümkün olsa da **gerçek üretim ortamlarında operasyonel olgunluk gerektirir**. Aşağıda tanımlanan kurulum adımları, gerekli altyapı ve süreç disiplini olmadan ciddi riskler doğurabilir.
-
-Her belediye backend servisi, Fastify çatısı altında standartlaştırılmış bir Node.js üretim paketi olarak sunulur. Kurulum süreci şu adımlardan ibarettir:
-
-1. **İndir ve Kurulum**
-2. **.env Yapılandırması** (PostgreSQL + Central bağlantıları)
-3. **Süreç Yönetimi** (PM2 veya systemd)
-
-Ancak bu basit kurulumun **gerçek hayatta çalışabilmesi** için belediyenin aşağıdaki yetkinliklere sahip olması zorunludur:
-
-- PostgreSQL veritabanı yönetimi ve yedekleme
-- SSL/TLS sertifika yönetimi
-- Sistem güncellemeleri ve güvenlik yaması takibi
-- Log izleme ve alert mekanizması
-- Secret rotation ve anahtar yönetimi disiplini
-
-**MVP Kapsamında Kabul Edilen Risk:**  
-Bu model, "her belediye kolayca kendi sunucusunu çalıştırabilsin" vizyonuyla tasarlanmıştır. Ancak operasyonel olgunluğu düşük olan belediyelerde bu yaklaşım **teknik borç ve güvenlik açığı** yaratabilir. Bu risk, D1-D5 operasyonel standartlar ile kısmen kontrol altına alınmıştır.
-
-### B. Merkezi Sistem Sağlığı İzleme ve Polling Mimarisi (Central Health Monitor)
-Merkezi SaaS Sağlık Motoru (`Central Health Monitor Engine`), hem merkez altyapısının hem de dağıtık belediye sunucularının durumunu 1 dakikalık döngülerle izler:
-1. **Belediye `/ready` Polling (Aktif Sorgulama):** Central Health Monitor, Central DB'deki tüm aktif belediyelerin IP/Domain adreslerini sorgular ve her birinin `/ready` endpoint'ine `HMAC-SHA256` imzalı (`x-kentim-signature`) HTTP GET istekleri atarak veritabanı ve disk doluluk durumlarını sorgular.
-2. **Belediye `/heartbeat` Push (Pasif Takip):** Belediyeler ayrıca `/v1/central/heartbeat` üzerinden 1 dakikalık periyotlarla central sunucuya push sinyali gönderir. Central Monitor, son 3 dakika boyunca heartbeat sinyali göndermemiş ve polling isteğine yanıt vermemiş belediye backend'lerini **"UNREACHABLE / DOWN"** durumuna alır ve central_admin paneline e-posta/push uyarı bildirimi gönderir.
-
-
-### C. Merkezi Onay ve Giriş Kilidi (SaaS Lockout Pipeline)
-Belediyenin sistemde panel erişimine sahip olabilmesi, Central Admin tarafından verilecek **"Aktif Onay"** şartına bağlıdır:
-1. **Giriş Engeli Mantığı:** Belediye personeli (müdür, şef, moderatör vb.) belediye paneline giriş yapmaya (`POST /v1/auth/login`) çalıştığında, belediye backend auth modülü JWT üretmeden önce central tenant registry servisinden veya yerel lisans/aktivasyon cache'inden ilgili belediyenin durumunu sorgular.
-2. **Aktivasyon Kontrolü:** Eğer belediyenin Central DB'deki durumu `active` (onaylı) değilse (örn: `pending_approval` veya `passive` ise), giriş isteği anında kesilerek HTTP `403 Forbidden` ve `MUNICIPALITY_NOT_APPROVED` ("Belediyeniz henüz merkez tarafından onaylanmamıştır veya aboneliği askıdadır.") hata koduyla reddedilir. Bu sayede merkezden onay almayan belediyelerin paneline hiçbir personel giriş yapamaz.
-
-### D. Operasyonel Dayanıklılık, Migration ve Güvenlik Operasyonları (Yeni — 2026-05)
-
-"İndir, `.env` ayarla, çalıştır" modelinin **gerçek dünyada güvenli ve sürdürülebilir** olabilmesi için aşağıdaki operasyonel standartlar zorunludur:
-
-#### D1. Multi-Tenant Şema Migration Stratejisi
-- **Araç:** Sqitch veya özel Node.js migration runner (transactional).
-- **Politika:**
-  - Her migration, **Central DB + tüm aktif municipal şemalar** üzerinde sırayla ve idempotent çalışmalıdır.
-  - Migration'lar **blue-green** veya **shadow table** tekniğiyle uygulanır; asla `ALTER TABLE` doğrudan production'da kilit oluşturmamalıdır.
-  - 50+ belediye varsa migration'lar **batch** (örneğin 10'ar 10'ar) ve 5-10 dakika aralıklarla çalıştırılır.
-  - Her belediye backend'i ayağa kalktığında `SELECT * FROM schema_migrations WHERE version = 'xxxx'` kontrolü yapar; eksik migration varsa **startup'ta 503** ile kendini rapor eder (Central Health Monitor bunu yakalar).
-- **Rollback:** Her migration'ın ters script'i zorunludur. Central Admin panelinden "Migration'ı Geri Al" butonu sadece `muni_admin` + 2FA ile tetiklenebilir.
-
-#### D2. Secret ve Anahtar Rotasyon Politikası
-| Anahtar Türü              | Rotasyon Sıklığı | Mekanizma                                      | Sorumlu          |
-|---------------------------|------------------|------------------------------------------------|------------------|
-| HMAC_MASTER_KEY           | 90 gün           | Central → Belediye'ye yeni key + 48 saat overlap | central_admin    |
-| JWT_SECRET (belediye)     | 180 gün          | Belediye admin panelinden manuel rotasyon + tüm refresh token'ların invalidasyonu | muni_admin       |
-| API_KEY (IoT / entegrasyon) | 365 gün veya ihlal durumunda | `/central/municipalities/:id/api-key/rotate` (eski key anında geçersiz) | central_admin + muni_admin |
-| CENTRAL_API_KEY           | 180 gün          | Central yeni key üretir, belediyeye güvenli kanal ile iletir | central_admin    |
-
-- **Zorunlu:** Tüm rotasyonlar `central_audit_logs` ve ilgili belediyenin `audit_logs` tablosuna `KEY_ROTATION` eventi olarak yazılır.
-- **Acil İhlal Prosedürü:** HMAC veya JWT secret sızıntısı şüphesinde Central 15 dakika içinde tüm ilgili belediyelere yeni key push'lar ve eski key'leri reddeder.
-
-#### D3. Backup, Disaster Recovery ve Veri Saklama
-- **Central SaaS DB:** Günlük tam yedek + 15 dakikalık WAL archiving (PITR). 35 gün retain.
-- **Her Belediye Şeması:** 
-  - Haftalık mantıksal dump (`pg_dump --schema-only` + veri).
-  - Günlük fiziksel base backup + WAL.
-  - **Cross-region** replika önerilir (aynı sağlayıcı içinde farklı availability zone).
-- **Restore Testi:** Her 90 günde bir **otomatik restore drill** çalıştırılır (Central Health Monitor tarafından tetiklenir). Başarısız drill → `muni_admin` ve `central_admin`'e kritik uyarı.
-- **KVKK Cold Storage:** 3 yılı aşan metin/loglar S3 Glacier veya eşdeğer "WORM" (Write Once Read Many) depolamaya taşınır. Silme talebi geldiğinde hem aktif DB hem cold storage taranır.
-
-#### D4. PostgreSQL LISTEN/NOTIFY Kapasite ve Hata Senaryoları
-**Bilinen Riskler ve Mitigasyonlar:**
-
-| Risk Senaryosu                        | Etki                                      | Mitigation (Zorunlu) |
-|---------------------------------------|-------------------------------------------|----------------------|
-| 1000+ concurrent panic / support vote | Connection pool tükenmesi, notify kaybı   | Worker pool max 8, debounced bulk insert (max 500 kayıt/batch), 30sn içinde işlenemeyen kuyruk → DLQ + admin alert |
-| PostgreSQL restart / failover         | Tüm LISTEN bağlantıları kopar             | Tüm worker'lar otomatik reconnect + `LISTEN` yeniden abone olur (exponential backoff 1s → 60s) |
-| Unlogged tablo WAL eksikliği          | Crash sonrası kuyruk kaybı                | Kritik kuyruklar (panic, dispute) için **logged** fallback tablo + periyodik "replay from last known good" job |
-| Yüksek trafikte notify storm          | CPU ve I/O şişmesi                        | `pg_notify` payload'ları 2KB ile sınırla; büyük payload'lar için sadece ID gönder + ayrı sorgu |
-
-- **Kapasite Testi Zorunluluğu:** Her belediye backend'i production'a alınmadan önce şu testleri geçmiş olmalıdır:
-  - 5.000 satır/saniye `support_count_queue` insert + worker tüketimi
-  - 200 panic sinyali/saniye debounced bulk upsert
-  - 30 saniye PostgreSQL primary fail-over simülasyonu (pgbouncer + patroni)
-
-#### D5. Artifact, Deployment ve Güvenlik Güncellemeleri
-- Belediye backend production bundle'ları **code signing** (cosign veya sigstore) ile imzalanır.
-- Central Gateway, belediyeden gelen `/ready` ve heartbeat isteklerinde artifact imza hash'ini kontrol eder (opsiyonel, ileri seviye).
-- Güvenlik yamaları (Fastify, PostgreSQL client, crypto kütüphaneleri) **maksimum 14 gün** içinde tüm aktif belediyelere dağıtılmalıdır. Central "Security Patch Required" bayrağı koyabilir; bu bayrak açıkken belediye yeni iş/rapor kabul edemez (salt-okunur + mevcut iş tamamlama).
-
-**Sonuç:** Bu standartlar olmadan "kolay dağıtım" vaadi operasyonel borç yaratır. Central SaaS ekibi, her yeni belediye onboarding'inde bu maddelerin kontrol edildiğini teyit etmekle yükümlüdür.
-
----
-
-## EK: Eksik Tablo Şemaları ve Ek Güvenlik Mimarisi
-
-### 1. Ek Tablo Şemaları
-
-#### `ideas` ve `idea_votes` (Fikir Yönetimi)
-```sql
-CREATE TABLE ideas (
-    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    tenant_id UUID NOT NULL,
-    citizen_id UUID NULL REFERENCES citizens(id),         -- NULL = anonim (izin verilmez; daima hesap zorunlu)
-    title VARCHAR(200) NOT NULL,
-    description TEXT NOT NULL,
-    status VARCHAR(20) NOT NULL DEFAULT 'pending_moderation'
-        CHECK (status IN ('pending_moderation', 'active', 'rejected', 'implemented')),
-    vote_score INTEGER NOT NULL DEFAULT 0,                 -- net puan: +1 ve -1 toplamı
-    is_identity_verified BOOLEAN NOT NULL DEFAULT FALSE,   -- fikir oluşturmak için TRUE zorunlu
-    official_response TEXT NULL,
-    category_id UUID NULL,
-    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-
-CREATE TABLE idea_votes (
-    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    idea_id UUID NOT NULL REFERENCES ideas(id) ON DELETE CASCADE,
-    citizen_id UUID NOT NULL REFERENCES citizens(id),
-    direction SMALLINT NOT NULL CHECK (direction IN (1, -1)), -- +1 veya -1
-    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    CONSTRAINT uq_idea_citizen_vote UNIQUE (idea_id, citizen_id)  -- kişi başı bir oy
-);
--- Oy değiştirme: mevcut satır güncellenir (direction UPDATE), yeni satır eklenmez.
-```
-
-#### `gdpr_requests` (KVKK/GDPR Talep Yönetimi)
-```sql
-CREATE TABLE gdpr_requests (
-    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    tenant_id UUID NOT NULL,
-    citizen_id UUID NOT NULL,
-    request_type VARCHAR(30) NOT NULL
-        CHECK (request_type IN ('account_deletion', 'data_export', 'anonymization')),
-    status VARCHAR(20) NOT NULL DEFAULT 'pending'
-        CHECK (status IN ('pending', 'processing', 'completed', 'failed')),
-    requested_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    processed_at TIMESTAMPTZ NULL,
-    anonymized_at TIMESTAMPTZ NULL,
-    processed_by UUID NULL,   -- muni_admin user_id
-    notes TEXT NULL
-);
-CREATE INDEX idx_gdpr_citizen ON gdpr_requests(citizen_id);
-CREATE INDEX idx_gdpr_status ON gdpr_requests(status);
-```
-
-#### `notification_dlq` (Başarısız Bildirim Dead Letter Queue)
-```sql
-CREATE TABLE notification_dlq (
-    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    tenant_id UUID NOT NULL,
-    recipient_id UUID NOT NULL,          -- citizen_id veya user_id
-    channel VARCHAR(20) NOT NULL CHECK (channel IN ('email', 'sms', 'push')),
-    payload JSONB NOT NULL,              -- gönderilmek istenen içerik
-    error_message TEXT,
-    retry_count SMALLINT NOT NULL DEFAULT 0,
-    last_attempt_at TIMESTAMPTZ,
-    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-CREATE INDEX idx_ndlq_tenant ON notification_dlq(tenant_id);
-```
-
-#### `failed_telemetry_dlq` (Başarısız IoT Telemetri Dead Letter Queue)
-```sql
-CREATE TABLE failed_telemetry_dlq (
-    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    tenant_id UUID NOT NULL,
-    device_id UUID NOT NULL,
-    raw_payload JSONB NOT NULL,          -- ham IoT JSON, parser crash olduğunda saklanır
-    error_type VARCHAR(50),              -- 'PARSER_CRASH', 'OUT_OF_BOUNDS', 'PAYLOAD_TOO_LARGE'
-    error_detail TEXT,
-    received_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-CREATE INDEX idx_fdlq_device ON failed_telemetry_dlq(device_id);
-CREATE INDEX idx_fdlq_tenant ON failed_telemetry_dlq(tenant_id);
-```
-
-### 2. `public_map_cache` bbox_hash Üretim Kuralı
-```sql
-CREATE UNLOGGED TABLE public_map_cache (
-    tenant_id UUID NOT NULL,
-    bbox_hash VARCHAR(64) NOT NULL,      -- SHA-256 (normalize edilmiş bbox string'i)
-    data JSONB NOT NULL,
-    expires_at TIMESTAMPTZ NOT NULL,
-    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    CONSTRAINT pk_pmc PRIMARY KEY (tenant_id, bbox_hash)
-);
-```
-**bbox_hash Üretim Kuralı:** `bbox` parametresi `minLon,minLat,maxLon,maxLat` formatında gelir; her koordinat **6 ondalık basamağa** yuvarlanarak normalize edilir. Normalize string `SHA-256` ile hash'lenir. Örnek: `bbox=28.9785123456,41.0234567890,...` → normalize: `28.978512,41.023457,...` → SHA-256 hex. Bu sayede yakın bbox'ların birbirini es geçmesi (false miss) önlenir.
-
-### 3. Kritik PostGIS GIST İndex'leri
-```sql
--- Belediye sınır poligonu sorguları (ST_Contains)
-CREATE INDEX idx_boundary_versions_geom ON municipal_boundary_versions
-    USING GIST (boundaries);
-CREATE INDEX idx_boundary_active ON municipal_boundary_versions(municipality_id)
-    WHERE active_to IS NULL;  -- aktif sürümler için partial index
-
--- İş emri konum aramaları
-CREATE INDEX idx_work_orders_location ON work_orders
-    USING GIST (location);
-
--- Panik sinyali konum aramaları
-CREATE INDEX idx_crisis_signals_coord ON crisis_signals
-    USING GIST (coordinates);
-```
-
-### 4. Kimlik Doğrulama Güvenlik Mimarisi
-
-#### Refresh Token Rotation
-Her `POST /auth/refresh` çağrısında:
-1. İstemci mevcut refresh token'ı gönderir.
-2. Sunucu token'ı veritabanında kontrol eder (geçerli mi, tek kullanımlık mı).
-3. Eski refresh token anında **geçersiz kılınır** ve silinir.
-4. Yeni access token (15 dk) + yeni refresh token (7 gün / "beni hatırla" ile 30 gün) üretilip döndürülür.
-5. **Çalınan token senaryosu:** Hacker eskimiş token'ı kullanmaya çalışırsa `401 TOKEN_REUSE_DETECTED` döner; oturum güvenlik tedbiri olarak tamamen sonlandırılır ve kullanıcıya "Şüpheli giriş tespit edildi" bildirimi gönderilir.
-
-#### HMAC-SHA256 Replay Koruması (Sistem İç İletişim)
-Central → Belediye komut kanalı ve `/ready` polling için:
-- `x-kentim-timestamp`: Unix milisaniye zaman damgası (zorunlu)
-- `x-kentim-nonce`: UUIDv4 (zorunlu)
-- `x-kentim-signature`: `HMAC-SHA256(HMAC_MASTER_KEY, method + path + timestamp + nonce + body_sha256)`
-- **Geçerlilik Penceresi:** Sunucu zamanından ±5 dakika; dışarısındaki istekler `401` ile reddedilir.
-- **Nonce Koruması:** Her nonce, **PostgreSQL'deki `hmac_nonces` tablosunda** (kısmi indeks: `WHERE used = FALSE`) 10 dakika TTL ile saklanır; aynı nonce ikinci kez gelirse `401 REPLAY_DETECTED` döner. Tablo periyodik olarak temizlenir (`DELETE FROM hmac_nonces WHERE created_at < NOW() - INTERVAL '10 minutes'`).
-
----
-
-### 5. Yeni Eksik Veri Şemaları DDL Tanımları (S1-S7)
-
-#### `work_orders` Tablosu Şeması (S1 Düzeltmesi)
-```sql
-CREATE TABLE work_orders (
-    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    tenant_id VARCHAR(50) NOT NULL,
-    tracking_code VARCHAR(30) UNIQUE NOT NULL, -- Format: KENT-[plaka]-XXXXXXXX
-    title VARCHAR(150) NOT NULL,
-    description TEXT NOT NULL,
-    status VARCHAR(30) NOT NULL DEFAULT 'pending'
-        CHECK (status IN (
-            'pending', 'moderation', 'dispatched_to_department',
-            'assigned_to_team', 'assigned_to_worker', 'in_progress',
-            'pending_chief_approval', 'pending_manager_review',
-            'resolved', 'rejected', 'reopened', 'chronic_archived'
-        )),
-    -- chronic_archived:
-    --   Vatandaş bir raporu maksimum 2 kez reopen ettikten sonra yeni rapor açtığında
-    --   eski rapor bu duruma alınır. is_public_visible = false yapılır, SLA durdurulur.
-    --   Yeni rapor parent_reopened_work_order_id ile eski rapora bağlanır.
-    --   Bu, kronik sorun zincirlerini admin panelinde izlenebilir hale getirir.
-    priority VARCHAR(10) NOT NULL DEFAULT 'normal'
-        CHECK (priority IN ('low', 'normal', 'high', 'urgent', 'crisis')),
-    source_type VARCHAR(20) NOT NULL DEFAULT 'citizen_report'
-        CHECK (source_type IN ('citizen_report', 'manual_internal', 'integration', 'scheduled')),
-    -- Reopen yönetimi
-    reopen_count SMALLINT NOT NULL DEFAULT 0,           -- Max 2; bu sınıra ulaştığında reopen butonu kilitlenir
-    reopen_reason TEXT NULL,
-    reopen_notes TEXT NULL,
-    -- Re-dispatch ve atama yönetimi
-    re_dispatch_count SMALLINT NOT NULL DEFAULT 0,      -- Sadece müdür/admin re-dispatch'leri sayılır
-    is_force_assigned BOOLEAN NOT NULL DEFAULT FALSE,   -- Admin anlaşmazlık kuyruğundan kesin atama yaptığında TRUE
-    is_manager_bypassed BOOLEAN NOT NULL DEFAULT FALSE, -- Müdür şefi bypass edip doğrudan personele atadığında TRUE
-    -- Geofence
-    geofence_bypass_requested BOOLEAN NOT NULL DEFAULT FALSE,
-    geofence_bypass_approved BOOLEAN NOT NULL DEFAULT FALSE,
-    -- Fotoğraf ret devre kesici (circuit breaker)
-    photo_rejection_count SMALLINT NOT NULL DEFAULT 0, -- 3'e ulaştığında pending_manager_review'a eskalasyon tetiklenir; reassign_worker ile sıfırlanır
-    -- Destek oyu sayacı (debounced worker ile güncellenir)
-    support_count INTEGER NOT NULL DEFAULT 0,
-    -- Vatandaş geri bildirimi
-    satisfaction_stars SMALLINT NULL CHECK (satisfaction_stars BETWEEN 1 AND 5),
-    -- Atama zinciri
-    assigned_worker_id UUID NULL,
-    approval_authority_id UUID NULL,                    -- Onay yetkisini kimin alacağı (şef veya müdür)
-    -- Coğrafi bağlantılar
-    boundary_version_id UUID NULL REFERENCES municipal_boundary_versions(id),
-    parent_reopened_work_order_id UUID NULL REFERENCES work_orders(id) ON DELETE SET NULL,
-    location GEOMETRY(Point, 4326) NOT NULL,
-    -- Zaman damgaları
-    sla_started_at TIMESTAMPTZ NULL,                   -- dispatched_to_department anında set edilir
-    sla_deadline_at TIMESTAMPTZ NULL,                  -- Hesaplanmış SLA bitiş zamanı
-    resolved_at TIMESTAMPTZ NULL,
-    is_sla_breached BOOLEAN NOT NULL DEFAULT FALSE,
-    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-CREATE INDEX idx_work_orders_tenant ON work_orders(tenant_id);
-CREATE INDEX idx_work_orders_tracking ON work_orders(tracking_code);
-CREATE INDEX idx_work_orders_status ON work_orders(status);
-CREATE INDEX idx_work_orders_priority ON work_orders(priority);
-CREATE INDEX idx_work_orders_chronic ON work_orders(parent_reopened_work_order_id) WHERE status = 'chronic_archived';
-```
-
-#### `citizens` Tablosu Şeması (S2 Düzeltmesi)
-```sql
-CREATE TABLE citizens (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  email VARCHAR(255) UNIQUE NOT NULL,
-  email_verified BOOLEAN NOT NULL DEFAULT FALSE,
-  email_verified_at TIMESTAMPTZ NULL,
-  is_identity_verified BOOLEAN NOT NULL DEFAULT FALSE,
-  identity_verified_at TIMESTAMPTZ NULL,
-  display_name VARCHAR(100) NOT NULL,
-  status VARCHAR(20) NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'passive', 'anonymized')),
-  kvkk_accepted_at TIMESTAMPTZ NOT NULL,
-  notification_email BOOLEAN DEFAULT TRUE,
-  notification_push BOOLEAN DEFAULT TRUE,
-  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-CREATE INDEX idx_citizens_email ON citizens(email);
-```
-
-#### `crisis_signals` Tablosu Şeması (S3 Düzeltmesi)
-```sql
-CREATE TABLE crisis_signals (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  tenant_id UUID NOT NULL,
-  device_id VARCHAR(255) NOT NULL,
-  citizen_id VARCHAR(255) NOT NULL DEFAULT 'anonymous',
-  coordinates GEOMETRY(Point, 4326) NOT NULL,
-  received_at TIMESTAMPTZ NOT NULL,
-  is_closed BOOLEAN NOT NULL DEFAULT FALSE,
-  closed_at TIMESTAMPTZ NULL,
-  CONSTRAINT uq_device UNIQUE (device_id)
-);
-CREATE INDEX idx_crisis_signals_coord ON crisis_signals USING GIST (coordinates);
-CREATE INDEX idx_crisis_signals_tenant ON crisis_signals(tenant_id);
-```
-
-#### `central_health_logs` Tablosu Şeması (S4 Düzeltmesi)
-```sql
-CREATE TABLE central_health_logs (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  municipality_id UUID NOT NULL,
-  status VARCHAR(20) NOT NULL CHECK (status IN ('UP', 'DEGRADED', 'DOWN')),
-  latency_ms INTEGER NULL,
-  db_connected BOOLEAN NULL,
-  -- redis_connected kaldırıldı: Redis kullanılmamaktadır.
-  disk_usage_percentage DECIMAL(5,2) NULL,
-  pg_listener_active BOOLEAN NULL,               -- LISTEN/NOTIFY worker'larının aktif olup olmadığı
-  error_message TEXT NULL,
-  checked_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-CREATE INDEX idx_health_logs_muni ON central_health_logs(municipality_id, checked_at DESC);
-```
-
-#### `central_analytics_metadata` Tablosu Şeması (S5 Düzeltmesi)
-```sql
-CREATE TABLE central_analytics_metadata (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  municipality_id UUID NOT NULL,
-  month DATE NOT NULL,  -- Ay başlangıcı (YYYY-MM-01)
-  total_work_orders INTEGER DEFAULT 0,
-  sla_compliance_rate DECIMAL(5,2) DEFAULT 0,
-  avg_resolution_time_minutes INTEGER DEFAULT 0,
-  citizen_satisfaction_stars DECIMAL(3,2) DEFAULT 0,
-  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-  CONSTRAINT uq_muni_month UNIQUE (municipality_id, month)
-);
-```
-
-#### `dispute_logs` Tablosu Şeması (S6 Düzeltmesi)
-```sql
-CREATE TABLE dispute_logs (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  tenant_id UUID NOT NULL,
-  work_order_id UUID NOT NULL REFERENCES work_orders(id),
-  offline_worker_id UUID NOT NULL,
-  online_worker_id UUID NULL,
-  local_completed_at TIMESTAMPTZ NOT NULL,  -- Çevrimdışı personelin yerel saati
-  server_handover_at TIMESTAMPTZ NULL,       -- Auto-handover zamanı
-  conflict_type VARCHAR(30) NOT NULL CHECK (conflict_type IN ('AUTO_HANDOVER', 'REASSIGNED', 'DOUBLE_COMPLETE')),
-  status VARCHAR(20) NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'approved', 'rejected', 'approved_override')),
-  resolved_by UUID NULL,
-  resolved_at TIMESTAMPTZ NULL,
-  notes TEXT NULL,
-  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-CREATE INDEX idx_dispute_work_order ON dispute_logs(work_order_id);
-CREATE INDEX idx_dispute_status ON dispute_logs(status, tenant_id);
-```
-
-#### `integration_logs` Tablosu Şeması (S7 Düzeltmesi)
-```sql
-CREATE TABLE integration_logs (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  tenant_id UUID NOT NULL,
-  device_id UUID NOT NULL,
-  event_type VARCHAR(30) NOT NULL CHECK (event_type IN ('SUCCESS', 'FAILED', 'OUT_OF_BOUNDS', 'THRESHOLD_HIT', 'DUPLICATE_SKIPPED')),
-  raw_payload JSONB NULL,
-  error_detail TEXT NULL,
-  work_order_id UUID NULL,  -- Tetiklenen iş emri (varsa)
-  received_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-CREATE INDEX idx_integration_logs_device ON integration_logs(device_id, received_at DESC);
-```
-
-#### `municipalities` Tablosu Şeması (S8 Düzeltmesi)
-```sql
-CREATE TABLE municipalities (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  name VARCHAR(150) NOT NULL UNIQUE,
-  city_slug VARCHAR(100) NOT NULL,
-  status VARCHAR(20) NOT NULL DEFAULT 'pending_approval' CHECK (status IN ('pending_approval', 'active', 'passive', 'suspended')),
-  license_expires_at TIMESTAMPTZ NOT NULL,
-  grace_period_ends_at TIMESTAMPTZ NULL,
-  api_key_hash VARCHAR(64) NOT NULL,          -- Rotasyon ve güvenlik için sha256 hash
-  hmac_master_key VARCHAR(128) NOT NULL,       -- Loopback için şifreli anahtar
-  priority_order INTEGER NOT NULL DEFAULT 1,   -- Çakışma durumundaki fallback sırası
-  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-CREATE INDEX idx_municipalities_slug ON municipalities(city_slug);
-CREATE INDEX idx_municipalities_status ON municipalities(status);
-```
-
-#### PostGIS Centroid Bazlı En Yakın Belediye Sorgu Modellemesi (Afet Panik Yönlendirme)
-Afet modunda coğrafi sınır dışındaki veya çakışan panik sinyallerinin en yakın aktif belediyeye atanabilmesi için veritabanında çalışacak PostGIS mesafe sorgusu:
-```sql
--- Panik koordinatına en yakın aktif belediyeyi bulma
-SELECT m.id AS municipality_id, m.name
-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(:longitude, :latitude), 4326)
-LIMIT 1;
-```
-*(Not: `<->` operatörü, PostGIS GIST indeksi üzerinden 3B/2B bounding box centroid'lerine göre en yakın komşuluğu (KNN) O(log N) karmaşıklığında bularak veritabanını kilitlemeden en hızlı yanıtı üretir.)*
-
-#### Çevrimdışı Çakışma Çözümü Çift Hak Ediş Kontrolü (Double Payout Alert Trigger)
-Bir iş emri hem canlı sistemde çözülüp hak ediş puanı yazılmışsa hem de `dispute_logs` üzerinden onaylanmak isteniyorsa, amire uyarı üretilmesini sağlayan veritabanı trigger tasarımı:
-```sql
-CREATE OR REPLACE FUNCTION check_double_payout_conflict()
-RETURNS TRIGGER AS $$
-DECLARE
-  v_already_payout BOOLEAN;
-BEGIN
-  -- Ana iş emrinde resolved aşamasında başka bir personele puan yazılmış mı kontrol et
-  SELECT EXISTS(
-    SELECT 1 FROM work_orders 
-    WHERE id = NEW.work_order_id 
-      AND status = 'resolved' 
-      AND assigned_worker_id IS NOT NULL 
-      AND assigned_worker_id != NEW.offline_worker_id
-  ) INTO v_already_payout;
-
-  -- Eğer daha önce başka bir personele puan yazılmışsa ve amir onay veriyorsa
-  -- statüyü otomatik 'approved_override' olarak işaretle (amir onayı kayıt altına alınır)
-  IF v_already_payout AND NEW.status = 'approved' THEN
-    NEW.status := 'approved_override';
-  END IF;
-
-  RETURN NEW;
-END;
-$$ LANGUAGE plpgsql;
-
-CREATE TRIGGER trg_dispute_double_payout
-  BEFORE UPDATE ON dispute_logs
-  FOR EACH ROW
-  EXECUTE FUNCTION check_double_payout_conflict();
-```