agent-enderun 1.0.2 → 1.0.4

package/docs/proje.md

@@ -0,0 +1,521 @@
+# Belediye Vatandaş Etkileşim ve İş Yönetim Sistemi (KENTİM)
+## MVP Teknik Spesifikasyon Belgesi
+
+---
+
+## Proje Özeti (Madde Madde)
+
+- **Platform Tanımı**: KENTİM, Türkiye’deki belediyeler için geliştirilen çok kiracılı (multi-tenant) SaaS tabanlı vatandaş şikayet ve saha iş yönetim sistemidir.
+- **Temel Akış**: Vatandaş harita üzerinden sorun bildirir → Moderatör inceler ve müdürlüğe havale eder → Müdür şefe atar → Şef personele dağıtır → Saha personeli işi yapıp fotoğraf kanıtı yükler → Şef onaylar → Vatandaşa bildirim gider.
+- **Kullanıcı Rolleri**: 9 rol tanımlıdır (citizen, muni_moderator, muni_department_manager, muni_team_chief, muni_worker, muni_admin, central_moderator, central_admin, system).
+- **İş Emri Durum Makinesi**: Detaylı state machine (pending → moderation → dispatched_to_department → assigned_to_team → assigned_to_worker → in_progress → pending_chief_approval → resolved/rejected) + circuit breaker, ping-pong koruması, QA döngüsü ve reopen (max 2) kuralları içerir.
+- **Güvenlik ve Uyumluluk**: UUIDv4 kimlikler, PostgreSQL Row-Level Security (RLS), tenant izolasyonu, RBAC middleware, 50m geofencing, KVKK, rate limiting, idempotency, veri saklama (retention) politikaları (görseller 1 yıl, metin 3 yıl) ve **JSONB formatında old_value/new_value içeren detaylı denetim ve işlem logları (audit & transaction logs)**.
+- **Mimari Yapı**: Central SaaS Gateway + her belediye için izole veritabanı/şema ve backend. Tüm trafik reverse proxy üzerinden yönlendirilir.
+  > **Bilinen Kritik Riskler (MVP):** Tamamen PostgreSQL LISTEN/NOTIFY bağımlılığı, basit dağıtım modelinin operasyonel yükü, V8 Sandbox yönetim maliyeti ve public harita ölçeklenebilirliği. Detaylar için `mimari.md` → "Kritik Mimari Risklerin Özeti" bölümüne bakınız.
+- **Vatandaş Arayüzü**: Public sorun haritası ana sayfadır. Rapor oluşturma, takip, duyurular, fikirler gibi tüm akışlar modal üzerinden yönetilir. Statik ve bilgilendirici içerikler (Hakkımızda, SSS, Gizlilik Politikası, KVKK, Kullanım Koşulları, İletişim) de ana harita üzerinden modal olarak açılır. Ayrı tam sayfa kullanılmaz.
+- **Belediye Paneli**: 5 rol için özelleşmiş arayüzler (Moderatör kuyruğu, Müdür iş emirleri, Şef planlama ve QA, Personel mobil görevler, Admin yönetim).
+- **Mobil Saha Uygulaması**: Offline-first çalışma, arka plan GPS, 50m geofence ile fotoğraf zorunluluğu, vardiya handover ve senkronizasyon uyuşmazlık havuzu.
+- **Otomasyon ve Entegrasyon**: IoT telemetri (dinamik payload mapping + V8 sandbox), periyodik iş takvimi (cron), akıllı yönlendirme kuralları ve SLA (Acil/Kriz için 7/24 kesintisiz).
+- **Central Yönetim & Güvenlik**: Birden fazla belediyeyi yönetme (Merkezi Lokasyon Hiyerarşisinden dinamik il/ilçe seçimi ile), global kategoriler, **statik içerik yönetimi ("Hakkımızda", "KVKK" vb.)**, lokasyonlar (Türkiye geneli 81 il ve 973 ilçenin tamamını içeren seed veritabanı entegrasyonu ile), abonelik/lisans takibi, afet modu tetikleme ve sistem sağlığı izleme.
+- **Merkezi Onay ve Giriş Engeli (SaaS Lockout)**: Belediyeler, Central Admin tarafından onaylanıp aktif edilmeden (`status = 'active'`) panellerine ve mobil uygulamalarına kesinlikle giriş yapamazlar. Giriş istekleri merkezi tenant registry üzerinden sorgulanarak kontrol edilir; aktif olmayan belediye personeli giriş yapmaya çalıştığında sistem `403 Forbidden` (`MUNICIPALITY_NOT_APPROVED`) hatası fırlatır.
+- **Belediye Backend Kolay Dağıtımı (indir.env ayarla çalıştır)**: Belediye backend servisleri, standart bir Node.js üretim paketi (production bundle) halinde sunulmaktadır. "İndir, `.env` ayarla (PostgreSQL Veritabanı bağlantısı, Central API Key, JWT ve HMAC Master anahtarları) ve PM2 / systemd ile çalıştır" (`npm install && npm run build && pm2 start`) basitliğinde, Docker veya harici bir container katmanı olmaksızın anında ayağa kaldırılacak şekilde standartlaştırılmıştır.
+- **Merkezi Sistem Sağlığı Monitörü**: Central SaaS health engine, hem merkezi veritabanının (Central DB) hem de tüm kayıtlı belediye backend sunucularının sağlık durumunu (`/ready` sorgulama endpoint'leri ve 1 dakikalık heartbeat pushes üzerinden) gerçek zamanlı izler.
+- **Public Harita ve Şeffaflık**: Vatandaş raporları kimlik maskelenerek halka açık haritada yayınlanır. Vatandaş harita üzerinde **serbestçe kaydırıp zoom** yapabilir; veriler zoom seviyesine ve görünen alana (BBOX) göre dinamik olarak yüklenir (büyük cluster'lardan tekil fuzzied pinlere kadar). +1 desteği ve filtreleme desteklenir.
+- **Veri Yaşam Döngüsü**: Fotoğraflar 1 yıl sonra otomatik silinir; metin ve loglar 3 yıl sonra soğuk depolamaya taşınır; KVKK silme taleplerinde kişisel veriler maskelenir.
+- **Bildirim Sistemi**: SMS, e-posta ve push bildirimleri ile tüm kritik olaylar (atama, onay, ret, SLA aşımı, reopen) anlık iletilir.
+
+---
+
+## Vatandaş Arayüzü – Map-First + Modal Modeli
+
+**Tasarım Kararı (MVP Kapsamı):**  
+Vatandaş web arayüzü radikal olarak basitleştirilmiştir. Artık ayrı sayfalar yerine **tek ana sayfa + modal tabanlı deneyim** uygulanır.
+
+### 1. Temel Yaklaşım
+- Ana sayfa (`/`) **doğrudan tam ekran Halka Açık Sorun Haritası** olarak açılır.
+- **Başlangıç Görünümü:** Harita ilk açıldığında **Türkiye geneli** (ülke seviyesi) gösterilir. Düşük zoom’da (yaklaşık Zoom 5-8) büyük bölgesel cluster’lar veya il bazlı özet sayıları görünür.
+- Kullanıcı zoom yaptıkça ve haritayı kaydırdıkça sistem otomatik olarak daha detaylı seviyeye iner:
+  - Orta zoom (il/ilçe seviyesi)
+  - Yüksek zoom (mahalle/sokak seviyesi)
+  - Çok yüksek zoom’da (17+) tekil fuzzing’li pinler gösterilir.
+- Vatandaş harita üzerinde serbestçe gezinebilir (pan + zoom).
+- Rapor oluşturma, takip, duyurular, fikir önerileri, profil gibi tüm akışlar **modal / slide-over drawer** olarak harita üzerinde açılır.
+- Ayrı tam sayfalar (`/map`, `/report/new`, `/dashboard`, `/announcements`, `/ideas`, `/profile` vb.) kaldırılmıştır.
+
+### 2. Modal + Deep Linking Stratejisi (Resmi Karar)
+
+**URL Stratejisi:** Query Parameter tabanlı yaklaşım tercih edilmiştir (temiz, SEO dostu ve kolay yönetilebilir).
+
+#### Desteklenen Modal URL Örnekleri
+| Amaç | URL Örneği | Açıklama |
+|------|------------|----------|
+| Normal Harita | `/` | Harita yüklenir, hiçbir modal açık değildir |
+| Rapor Oluşturma | `/?modal=report` | Konum seçimi yapılmış şekilde rapor modal'ı açılır |
+| Rapor Takip | `/?modal=track&code=KENT-34-ABC123` | Takip modal'ı + sonuç drawer açılır |
+| Fikir Detayı | `/?modal=idea&id=uuid` | İlgili fikir modal'ı açılır |
+| Duyuru Detayı | `/?modal=announcement&id=uuid` | Duyuru modal'ı açılır |
+| Profil | `/?modal=profile` | Giriş yapmış kullanıcı için profil modal'ı |
+| Dashboard | `/?modal=dashboard` | Kişisel raporlar ve destekler modal'ı |
+
+**Davranış Kuralları:**
+- Doğrudan link geldiğinde harita önce yüklenir, ardından ilgili modal otomatik olarak açılır.
+- Modal kapatıldığında URL temizlenir (`/` haline döner) — history kirletilmez.
+- Kullanıcı modal içindeyken URL’yi kopyalarsa, link ilgili modal’ı yeniden açar.
+- Tarayıcı geri butonu modal’ı kapatır (önceki duruma döner).
+- Sayfa yenilendiğinde modal durumu query param’dan tekrar oluşturulur.
+
+**Geriye Uyumluluk (Opsiyonel):**
+- Eski linkler (`/report/track/KENT-34-XXX`, `/ideas/123` vb.) geldiğinde sistem bunları query param’lı forma yönlendirir veya otomatik modal açar.
+
+### 3. Edge Case’ler ve Fallback’ler
+- Modal açılırken veri çekilemezse: Modal içinde hata mesajı + "Kapat" butonu gösterilir.
+- Yetkisiz erişim (örneğin giriş yapmadan profil modal’ı): Login modal’ı tetiklenir.
+- Birden fazla modal çakışması: Her zaman tek modal açık olur (stacking yasak).
+- Afet modu aktifken: Panik butonu ve afet katmanları öncelikli gösterilir, diğer modal’lar arka plana alınabilir.
+
+### 4. Analytics ve History Yönetimi
+- Her modal açılışı `modal_open` event’i olarak gönderilir (parametre: modal tipi + ilgili id).
+- Sayfa yenileme ve direkt link ile açılma ayırt edilir.
+- Tarayıcı history’si sadece ana harita durumunu tutar (modal’lar history’ye yazılmaz).
+
+### 5. Bilinen Riskler (Bu Bölümle İlgili)
+- Mobil cihazlarda harita + drawer kombinasyonu dokunma ve kaydırma çakışması riski taşır.
+- Deep link analitiği ve conversion takibi henüz detaylandırılmamıştır.
+- WCAG odak yönetimi (focus trap) modal’lar için zorunlu hale gelmiştir.
+
+---
+
+## Modül A: Proje Çekirdeği (Core)
+
+| Alt Modül | Açıklama |
+| :--- | :--- |
+| **A1. Proje Tanımı** | Dağıtık şehir sorun yönetim platformu. Raporlar, vatandaş kimliği maskelenerek halka açık haritada yayınlanır. Vatandaşlar harita üzerinden rapor oluşturur; belediyeler bu raporları moderatör panelinde inceleyip ilgili müdürlüğe havale eder, müdürlükler ekip şeflerine atar, şefler saha personeline yönlendirir, saha ekipleri işi yapıp kapatır ve vatandaşa otomatik bildirim gider. Platform aynı zamanda vatandaş raporu bağımsız olarak dahili iş emirleri, dış sistem entegrasyonları ve periyodik/rutin bakım işlerini de yönetir. |
+| **A2. Vizyon** | Türkiye'deki tüm belediyelere ölçeklenebilir, her belediye kendi bağımsız backend'ini çalıştırırken merkezi yönetim (SaaS) tüm belediyeleri koordine eder. |
+| **A3. Problem Çözümü** | Mevcut WhatsApp / Excel / çağrı merkezi / kâğıt süreçl| **A5. İş Emri Durum Makinesi** | Ana akış: `pending` → `moderation` → `dispatched_to_department` → `assigned_to_team` → `assigned_to_worker` → `in_progress` → `pending_chief_approval` → `resolved` / `rejected`. **İstisna Durumlar:** Circuit breaker devreye girdiğinde `pending_chief_approval` → `pending_manager_review` → (müdür kararıyla) `resolved` / `rejected` / `assigned_to_team`. Vatandaş düşük puan verdiğinde `resolved` → QA Modu (durum korunur) → (QA kararıyla) `resolved` veya `in_progress`. Yeniden açma: `resolved` / `rejected` → `reopened` → `moderation`. 
+**Reopened (Yeniden Açma) Akışı:** Vatandaş tarafından "Sorun Devam Ediyor" denilerek yeniden açılan işler, `reopened` durumuna geçer ve otomatik olarak **moderatörün** "Karar Bekleyenler" (`moderation`) kuyruğuna geri döner. Moderatör işi tekrar inceleyip aynı veya farklı bir müdürlüğe havale edebilir. **Reopen SLA Süresi:** Rapor `reopened` durumuna geçtiğinde eski SLA geçmişi denetim amacıyla saklanır; **yeni SLA henüz başlamaz.** Yeni SLA, **moderatörün işi `dispatched_to_department` olarak sevk ettiği anda** başlar ve ilgili kategori için tanımlanmış standart SLA süresinin **%50'si** kadardır. (`reopened` → `moderation` arasındaki bekleme süresi yeni SLA'ya dahil edilmez.) **2. Reopen Sonrası Kronik Arşivleme (`chronic_archived`):** Vatandaş bir raporu en fazla 2 kez reopen edebilir. Limit dolduğunda reopen butonu kilitlenir; vatandaş "Yeni Rapor Oluştur" bağlantısıyla sıfırdan başvurduğunda: (a) Eski raporun `status` alanı `chronic_archived` yapılır — bu gerçek bir `work_orders.status` değeridir, flag kombinasyonu değildir. (b) `is_public_visible = false` yapılarak eski rapor public haritadan kaldırılır. (c) Yeni rapor `pending` olarak açılır ve `parent_reopened_work_order_id` (eski raporun UUID'si) ile eski rapora bağlanır. Bu sayede kronik sorunlar zinciri oluşturularak admin panelinde "Kronik Arızalar" başlığı altında izlenebilir.
+**Asenkron Panik Sinyali Kuyruğu:** Afet modunda `POST /v1/emergency/panic` ile gelen panik sinyalleri veritabanı kilitlenmelerini engellemek için doğrudan DB'ye yazılmak yerine asenkron olarak **PostgreSQL unlogged tablosu** (`emergency_panic_queue`) üzerine `INSERT` ile alınır; ardından `pg_notify('emergency_panic_channel', device_id)` ile worker process'leri tetiklenir. Worker'lar `FOR UPDATE SKIP LOCKED` ile kuyruktaki sinyalleri toplu (debounced bulk update) şekilde tüketerek kriz masası haritasına yansıtır. **Mimari Karar:** Redis kullanılmaz; tüm kuyruk yönetimi PostgreSQL LISTEN/NOTIFY mekanizmasıyla gerçekleştirilir.
+**Geofence Boundary Sürüm Kilidi:** İş tamamlandığında saha çalışanının mobil cihazından yapılan geofence `ST_Contains` kontrolü, belediyenin o anki güncel sınır poligonunu değil, iş emrinin **oluşturulma anında aktif olan PostGIS sınır poligonu sürümü** (`boundary_version_id` referansı ve `municipal_boundary_versions` tablosu) üzerinden gerçekleştirilir. Bu sürüm kilidi sayesinde her satıra büyük coğrafi veriler kopyalanarak veritabanının depolama şişmesi (bloating) önlenir, aynı zamanda belediye sınırı sonradan daraltılsa dahi saha çalışanı lockout hatası almaz.
+**Durum Detayları:**
+- `assigned_to_team`: İş müdürlük tarafından bir şefe/ekibe havale edildiğinde oluşur. Personel atanana kadar şefin "atanmamış havuzunda" bekler.
+- `assigned_to_worker`: Şef (veya doğrudan müdür) işi spesifik bir personele atadığında oluşur. İş bu aşamada personelin mobil cihazına düşer.
+- `in_progress`: Saha personelinin işi aktif olarak üstlendiğini (başlattığını) gösterir.
+- `pending_chief_approval`: Personelin işi tamamlayıp fotoğraf yüklediği, şefin onayını beklediği ara durumdur.
+- **Geofence Bypass:** Personel 50m geofence engeline takıldığında "Geofence Bypass Talebi" oluşturarak EXIF konumlu fotoğraf ve gerekçe sunabilir; şef onayladığında resmi koordinat güncellenir ve geofence bypass edilir.
+- **Auto-Handover:** 8 saat GPS sinyali göndermeyen veya 12 saat açık olan aktif saha çalışanlarının vardiyaları arka plan cron servisi ile otomatik kapatılır, `in_progress` işler şef havuzuna devredilir.
+- **Sensör Spam Koruması:** Çözülen bir entegrasyon (IoT) iş emrinin ardından 1 saat içinde aynı sensörden tekrar doluluk uyarısı gelirse sensör otomatik olarak "suspicious" moduna alınır, yeni iş emri tetiklenmez ve admin paneline arıza kontrol uyarısı düşer.
+**Fotoğraf Ret Devre Kesici (Circuit Breaker):** Bir iş emri üst üste 3 kez fotoğraf reddi alırsa, sistem işi otomatik olarak `in_progress` yerine `pending_manager_review` (Müdür İncelemesi) durumuna çeker ve müdüre eskalasyon bildirimi gönderir. 
+**Müdür İnceleme Aksiyonları:** `pending_manager_review` durumundaki iş için müdür; `force_resolve` (kanıtları kabul edip kapat), `reassign_worker` (işi başka personele aktar - bu işlemde ret sayacı sıfırlanır, `is_manager_bypassed` flag'i de sıfırlanarak iş şefin ekibinin atanmamış havuzuna `assigned_to_team` gönderilir, böylece şef yeni atama yapabilir), `reject` (gerekçeyle iptal et) veya `manual_approval` (eksikleri kabul ederek şef onayını bypass edip işi doğrudan resolved durumuna çekme - circuit breaker eskalasyonu sonrası onay) aksiyonlarından birini alarak döngüyü sonlandırır. **Kritik Denetim:** Müdürün şef onayını bypass ettiği (`force_resolve` veya `manual_approval`) veya pending_chief_approval aşamasındayken `force_approve` (şef onayı bypass) ile kapattığı her işlem, sistem tarafından "Üst Yetkiyle Kapatma" olarak işaretlenir ve `muni_admin` performans raporlarında ayrı bir sütunda listelenir.
+**Müdür Force Approve:** Müdürler, şeflerin onay bekleyen tüm işlerini (`pending_chief_approval`) üst yetkiyle doğrudan onaylama (`resolved`) yetkisine sahiptir. Müdür pending_chief_approval'ı doğrudan onayladığında MANAGER_FORCE_APPROVE loguyla kaydedilir, performans raporunda Üst Yetkiyle Kapatma sütununda görünür.
+**Personel Devamsızlık / İşi Bırakma:** Personel işi "Yarıda Bırakıldı" olarak işaretlediğinde, iş otomatik olarak personelin üzerinden alınır. **Normal şef atamasında** iş şefin atanmamış havuzuna (`assigned_to_team`) döner. **Müdür bypass atamasında** ise `dispatched_to_department` (müdür havuzu) olarak iade edilir; `is_manager_bypassed = true` flag'i korunur ve şef bu işleme dahil edilmez. 
+**Re-dispatch (Ping-Pong Koruması):** Müdür veya şef tarafından yapılan re-dispatch işlemleri, işi doğrudan başka müdürlüğe göndermek yerine, gerekçesiyle birlikte moderatörün "Karar Bekleyenler" (`moderation`) kuyruğuna geri döndürür. **Ping-Pong Eşiği:** Yalnızca müdür ve admin (`muni_department_manager`, `muni_admin`) seviyesindeki re-dispatch'ler sayılır. Moderatörün havale işlemleri bu sayıca dahil edilmez. Re-dispatch sayacı `> 2` (3. müdür/admin re-dispatch'i gerçekleştiğinde) ping-pong koruması devreye girer; iş moderatörden alınır ve `muni_admin` "Anlaşmazlık Çözüm" kuyruğuna taşınır. Son kararı admin verir. **Moderatör Re-dispatch Kısıtı:** Moderatör (`muni_moderator`) re-dispatch yetkisini yalnızca `dispatched_to_department` aşamasında kullanabilir; iş daha ileri bir aşamadaysa re-dispatch yapamaz. 
+**SLA Hesaplama Mantığı:** Sistemdeki tüm SLA süreleri, ilgili müdürlüğün tanımlı çalışma takvimine (Business Hours) göre hesaplanır. Hafta sonu, resmi tatiller ve çalışma saatleri dışındaki süreler SLA sayacından otomatik olarak düşülür. **SLA Öncelik Çarpanları:** İş öncelik seviyelerine göre SLA süreleri şu çarpanlarla hesaplanır: `low = x1.5 SLA`, `normal = x1.0 SLA`, `high = x0.5 SLA`, `urgent = x0.25 SLA`, `crisis = x0.1 SLA`. **Mükerrer Rapor SLA İndirimi:** Moderatör bir biletini "Mükerrer" olarak işaretleyip ana iş emriyle birleştirdiği anda mükerrer biletlerin SLA sayacı **anında durdurulur** ve SLA uyum oranlarına olumlu/nötr olarak yansıtılır. Bu sayede yapay SLA ihlalleri tamamen engellenir. **Kritik İstisna:** Öncelik seviyesi `Acil` veya `Kriz` olarak belirlenmiş olan iş emirlerinde belediye çalışma saatleri dikkate alınmaz; SLA sayacı **7/24 kesintisiz** olarak çalıştırılır.
+**Kalite Denetim (QA) Döngüsü:** Vatandaş tarafından 1 veya 2 yıldız verilen tüm `resolved` durumundaki iş emirleri, sistem tarafından otomatik olarak şefin "Kalite Denetim" kuyruğuna düşürülür. Şef bu işleri inceleyerek "Çözümü Onayla" veya "Yetersiz - İşe Dön" (durum tekrar `in_progress` olur) kararlarından birini verir. **QA SLA Süresi ve Otomatik Kesinleştirme:** Şefin QA kuyruğundaki bir işi incelemesi için **maksimum 5 iş günü (Business Days)** süresi vardır. Bu süre zarfında şef tarafından herhangi bir onay veya işe döndürme işlemi yapılmazsa, sistem arka plan servisi işi otomatik olarak "Çözümü Onayla" şeklinde kesinleştirir, işi QA kuyruğundan kaldırır ve `resolved` durumunu korur. **QA İşe Dönüş Grace Period:** Şef işi "Yetersiz - İşe Dön" kararı ile saha personeline geri gönderdiğinde, yapay SLA aşımlarını önlemek adına sisteme otomatik olarak ek 2 saatlik (veya kalan sürenin minimum 4 saate yuvarlanmasıyla) "QA Düzeltme Grace Period" eklenir, SLA sayacı dondurulduğu yerden devam eder.
+**Senkronizasyon Uyuşmazlık Havuzu (Dispute Pool):** Saha çalışanının çevrimdışıyken tamamladığı ancak o esnada sistemde çakışan (başkasına atanan veya auto-handover ile iade edilen) işler veritabanında `dispute_logs` tablosunda saklanır. **Çevrimdışı Handover İstisnası:** Saha çalışanının yerel cihazındaki çevrimdışı iş bitirme zaman damgası (MMKV/SQLite local timestamp), sunucunun otomatik vardiya kapatma (auto-handover) zaman damgasından daha önce ise sistem bunu çakışma hatasıyla reddetmek yerine uyuşmazlık havuzuna (`dispute_logs`) "Hak Ediş Teyidi Bekliyor" notuyla aktarır. Uyuşmazlık havuzundaki kayıtlar şefin veya müdürün "Çakışma Çözümü" ekranına düşer. Amir, çakışan iki kaydı (mobil personelin kanıtı ile yeni atanan işin durumunu) zaman çizelgesiyle inceler; yerinde yapılan incelemeye göre personelin emeğini ("Hak Edişi Onayla") onaylayabilir veya "Geçersiz Bildirim" olarak reddedebilir. Onaylanan uyuşmazlıklar personelin performans puanı ve hak ediş hanesine artı olarak yazılır.
+Dahili, entegrasyon ve periyodik kaynaklı iş emirleri `dispatched_to_department` durumundan başlar; moderatör onayı gerekmez. |
+| **A6. Çok Müdürlüklü Rapor Kuralı** | Bir rapor birden fazla müdürlüğü ilgilendiriyorsa moderatör birincil müdürlüğü seçer; diğer ilgili müdürlüklere sistem otomatik bildirim gönderir. İş emri yalnızca birincil müdürlük üzerinden yönetilir. |
+| **A7. İş Emri Kaynak Tipleri** | Tüm iş emirleri dört kaynaktan biri olarak işaretlenir: `citizen_report` (vatandaş raporu), `manual_internal` (müdür veya şef tarafından oluşturulan dahili iş emri), `integration` (dış sistem/yazılımdan API ile gelen iş emri), `scheduled` (periyodik/rutin bakım takviminden sistem tarafından otomatik üretilen iş emri). Kaynak tipi analitik raporlarda ayrı ayrı görüntülenir. Varsayılan `is_public_visible` değerleri: `citizen_report` için varsayılan `true` (modere edildikten sonra public); `manual_internal` için varsayılan `false` (gizli); `integration` (IoT) için entegrasyon bazında konfigüre edilebilir (`default_public: true|false` alanı zorunludur - IoT entegrasyon formunda `default_public` checkbox'u aktif ise yeni iş `is_public_visible = true` ile oluşturulur; aksi halde `false` ile oluşturulur ve moderatör onayı olmadan public görünmez); `scheduled` için varsayılan `false` (gizli, amir onayıyla gösterilebilir). **API Request Şeması:** `/integrations/iot/telemetry` endpoint'ine gelen POST isteğinde `default_public` alanı otomatik olarak sistem tarafından okunur ve yeni work_order kaydına yansıtılır. **Moderatör Yetkisi:** IoT kaynaklı iş emirlerinde de `is_public_visible` alanı moderatör veya admin tarafından standart toggle ile değiştirilebilir; `default_public` yalnızca iş emrinin oluşturulma anındaki başlangıç değerini belirler. |
+| **A8. Yetki Devri ve Rol Temizliği (Cleanup)** | Bir yöneticinin (`muni_admin`, `muni_department_manager`, `muni_team_chief`) veya saha çalışanının (`muni_worker`) rolü değiştiğinde ya da pasife alındığında; sistem o kullanıcı üzerindeki tüm aktif iş emirlerini otomatik olarak şu kurala göre havuza gönderir: Müdür pasife alınırsa → işler `muni_admin`'in atanmamış havuzuna; Şef pasife alınırsa → işler **şefin bağlı olduğu müdürlüğün** müdürünün atanmamış havuzuna iade edilir (onay bekleyen `pending_chief_approval` işlerinin statüsü değişmez, onay yetkisi müdüre geçer). Saha personeli (`muni_worker`) pasife alındığında veya vardiyası kapandığında/işi yarıda bıraktığında; müdür bypass atamasıyla gelen işler `dispatched_to_department` **(müdür havuzu)** olarak iade edilir ve `is_manager_bypassed = true` flag'i korunur; şef bu işleme dahil edilmez, müdür yeniden atama yaparak iş bittiğinde onay yetkisi yine doğrudan müdüre yönlendirilir. Saha personeli (`muni_worker`) pasife alındığında ise üzerindeki tüm aktif (`in_progress`) ve yeni atanan (`assigned_to_worker`) iş emirleri otomatik olarak `assigned_to_team` (şef havuzu) durumuna çekilerek şefe iade edilir ve bildirim gönderilir; `pending_chief_approval` durumundakiler ise atanan personel alanı pasifleşmiş olarak şef onay kuyruğunda kalır. Bu işlem denetim loguna `ROLE_CHANGE_CLEANUP` olarak kaydedilir. |
+| **A9. Mükerrer Rapor Konsolidasyonu** | Aynı konumda (50m yarıçap) ve aynı kategoride son 24 saat içinde açılmış başka bir aktif iş emri varsa, moderatör yeni gelen raporu "Mükerrer" olarak işaretleyip mevcut iş emriyle ilişkilendirebilir. Bu durumda yeni rapor `resolved` olduğunda, ilişkili olduğu "Ana İş Emri"nin durumunu ve fotoğraflarını miras alır. Ek olarak, önleyici mükerrer kontrolü sayesinde vatandaş rapor oluşturma haritasında pin bıraktığı an 50-100m çapındaki aktif sorunlar taranır. Yakın rapor uyarısı verildiğinde vatandaş "+1 Beni de Etkiliyor" desteği vererek mükerrer kayıt oluşturmadan doğrudan ana soruna dahil olabilir. |
+
+---
+
+## Modül B: Kullanıcı Rolleri ve Yetki Alanları
+
+| Rol | Arayüz | Görev ve Yetki Tanımı |
+| :--- | :--- | :--- |
+| **citizen** | Web + Mobil | Opsiyonel hesap oluşturma veya anonim kullanım. Ana sayfa (`/`) doğrudan tam public haritadır. Vatandaş harita üzerinde serbestçe gezinir, rapor oluşturma, takip, duyurular, fikirler gibi tüm akışları harita üzerinde **modal / drawer** ile yönetir. +1 desteği ve fikir oylaması için **E-posta onaylı** hesap gerekir (anonim kullanıcılar +1 desteği veremez ve fikir oylamasına katılamaz). Fikir **oluşturmak** için ayrıca **TC Kimlik doğrulaması** (`is_identity_verified = true`) zorunludur. Anonim kullanıcılar takip kodu ile sorgular ve raporu `reopened` yapabilir (max 2 kez). |
+| **muni_moderator** (Belediye Moderatörü) | Belediye Paneli (Web) | **Vatandaş raporlarının birincil inceleme ve yönlendirme noktasıdır.** Gelen vatandaş raporlarını inceleme, birincil müdürlüğü belirleme (manuel veya sistem önerisiyle), çok müdürlüklü durumlarda ikincil bildirim müdürlüklerini seçme, yetkili olduğu durumlarda re-dispatch yapma, öncelik atama, dahili not ekleme. **Manuel iş emri oluşturma yetkisi sınırlıdır:** Sadece "vatandaş raporu olarak açılamayan sistemsel/acil takip gerektiren" durumlarda (örnek: planlı yol çalışması, acil koordinasyon ihtiyacı) ve her seferinde zorunlu gerekçe + `manual_internal` kaynak tipiyle oluşturabilir. Oluşturulan iş otomatik olarak ilgili müdürlüğün `dispatched_to_department` havuzuna düşer (moderatör kendi işini moderasyondan geçiremez). Tüm manuel oluşturma işlemleri `MANUAL_WORK_ORDER_BY_MODERATOR` tipiyle detaylı audit loga yazılır. Bu yetki kötüye kullanım riski nedeniyle muni_admin tarafından devre dışı bırakılabilir. |
+| **muni_department_manager** (Müdürlük Yetkilisi / Müdür) | Belediye Paneli (Web) | Yalnızca kendi müdürlüğüne havale edilmiş işleri görür. İkincil bildirim olarak gelen işleri bilgi amaçlı görür, üzerinde atama yapamaz. İşi uygun ekip şefine atar; dilerse şefi atlayarak doğrudan kendi müdürlüğü altındaki bir personele de atayabilir. **Kritik Kural:** Müdür doğrudan atama yaptığında, iş tamamlandığında onay bekleyen kişi olarak şef yerine doğrudan **Müdür** belirlenir. Kendi altındaki şef, ekip ve personeli yönetir, istatistiklerini izler. Manuel iş emri oluşturabilir. Re-dispatch yetkisine sahiptir; her re-dispatch denetim loguna kaydedilir. |
+| **muni_team_chief** (Ekip Şefi) | Belediye Paneli (Web) + Mobil | Müdürden gelen iş emirlerini kendi ekibindeki personele atar. Manuel iş emri oluşturabilir; oluşturulan iş emri kendi müdürlüğüne `dispatched_to_department` durumunda düşer ve müdür onaysız açılır. Şef manuel iş emri oluştururken doğrudan personel atarsa durum `assigned_to_worker` olur. Kendi ekibinin günlük iş planını ve vardiya takvimini görür, yönetir. Ekip personelinin fotoğraflı iş tamamlama kanıtlarını panelden inceler; onaylar (`resolved`) veya eksik bulursa `in_progress`'e döndürür. Yalnızca kendi müdürlüğüne ve ekibine ait işleri görür. |
+| **muni_worker** (Saha Personeli) | Belediye Paneli + Mobil | Kendisine atanan işleri mobil cihazda görür; işi üstlenir (`in_progress`), tamamlar, zorunlu fotoğraf ekler (konum + zaman damgalı), not yazar. İşi tamamladığında durum `pending_chief_approval`'a geçer; şef onaylayana kadar iş bu durumda kalır. **Vardiya ve Görev Devri:** Personel vardiyasını sonlandırdığında (`Vardiyayı Kapat`), üzerindeki tüm aktif (`in_progress`) iş emirleri otomatik olarak personelden alınır, durum `assigned_to_team` (Atanmamış) olarak güncellenir ve şefin havuzuna "Handover (Devir)" notuyla iade edilir. Ancak tamamlanıp fotoğrafı yüklenmiş olan `pending_chief_approval` (Şef Onayı Bekliyor) durumundaki işler devir işleminden muaftır ve personelin üzerinde kalmaya devam eder. Yalnızca kendi müdürlüğüne ve ekibine ait işleri görür. |
+| **muni_admin** (Belediye Sistem Yöneticisi) | Belediye Paneli (Web) | **Belediye genelinde uçtan uca tüm süreçleri izleme, denetleme ve müdahale yetkisine sahiptir.** Belediye ayarları, müdürlük tanımlama, ekip/personel oluşturma, rol atama, akıllı yönlendirme kuralları, SLA tanımları, duyuru yayınlama, periyodik iş takvimi yönetimi, detaylı analitik raporlar, KVKK veri yönetimi. Halka açık harita genel ayarlarını (aktif/pasif, varsayılan görünürlük, çözülenlerin kalma süresi, koordinat fuzzing miktarı) yönetme yetkisine sahiptir. Re-dispatch yetkisine sahiptir ve tüm alt rollerin yetkilerini kapsar. |
+| **central_moderator** (Merkezi Moderatör) | Central Panel (Web) | **Operasyonel izleme ve erken uyarı rolüdür.** Bireysel vatandaş verisi, iş emri detayı veya kişisel bilgiye **asla erişemez**. Belediye bazında agregate metrikleri (SLA uyum oranı, aktif iş yükü, son 7/30 günlük trend), kritik SLA aşımına sahip belediyelerin listesi, heartbeat kesinti uyarıları ve sistem sağlık grid'ini görebilir. Belediyelerden gelen destek taleplerini inceleyip yanıtlayabilir ve öncelikli olarak central_admin'e eskalasyon yapabilir. Global kategorilerde "öneri" düzeyinde düzenleme önerebilir (onay central_admin'dedir). Afet modu sırasında sadece izleme yetkisi vardır (tetikleme yetkisi yoktur). |
+| **central_admin** (Merkezi Yönetici) | Central Panel (Web) | Tüm belediyeleri yönetme (Merkezi Lokasyon Hiyerarşisindeki dinamik il/ilçe seçimiyle belediye ekleme, aktif/pasif, yıllık abonelik ve lisans), global kategori/lokasyon yönetimi (Türkiye geneli 81 il ve 973 ilçenin komple seed veritabanı dahil), sistem sağlığı izleme, afet modu tetikleme, global raporlar. |
+| **system** (Arka Plan Servisleri) | Sunucu Tarafı | Otomatik bildirimler (SMS, e-posta, push), durum güncellemelerinde vatandaşa bilgi verme, SLA aşımında ilgili yöneticilere uyarı, rota optimizasyonu hesaplama, periyodik iş emirlerini takvime göre otomatik üretme, entegrasyon webhook'larını işleme, belediye backend'lerinin heartbeat kontrolü, abonelik bitiş uyarıları. |
+
+### Hiyerarşi ve Veri İzolasyonu
+
+Sistem mimarisi, Türkiye’deki belediyelerin operasyonel şemasına (Müdürlük → Şeflik → Saha Personeli) tam uyumlu olarak tasarlanmıştır. Bu yapı içerisinde **Veri İzolasyonu** katı kurallarla uygulanır:
+
+*   **Müdür (`muni_department_manager`):** Yalnızca kendi müdürlüğüne havale edilmiş işleri görebilir. Diğer müdürlüklerin iş emirlerine ve detaylarına erişemez.
+*   **Ekip Şefi (`muni_team_chief`):** Yalnızca kendi müdürlüğü altındaki kendi ekibine atanmış iş emirlerini görür. Diğer ekiplerin günlük iş planlarını göremez.
+*   **Saha Personeli (`muni_worker`):** Yalnızca kendi mobil cihazına atanan ve üstlendiği aktif işleri görebilir. Ekipteki diğer personelin görev listesine erişemez.
+*   **Belediye Admini (`muni_admin`):** Belediye genelindeki tüm izolasyon kurallarının üzerinde, tam görme ve denetleme yetkisine sahiptir.
+
+```
+central_admin
+├── central_moderator
+└── muni_admin (Tam Yetkili - Tüm Belediye)
+    ├── muni_moderator (Tüm Havuz)
+    └── muni_department_manager (Departman İzolasyonu)
+        └── muni_team_chief (Ekip İzolasyonu)
+            └── muni_worker (Görev İzolasyonu)
+```
+
+---
+
+## Modül C: Ürün Özellikleri
+
+### C1. Vatandaş Tarafı (Web + Mobil)
+
+#### Kimlik ve Hesap Yönetimi
+
+- **Opsiyonel Kayıt:** Vatandaş e-posta adresiyle hesap oluşturabilir ya da kayıt olmadan anonim rapor gönderebilir. **Maliyet ve DDoS Koruması:** SMS OTP gönderim maliyetlerini ve bot saldırılarını önlemek amacıyla, vatandaş kaydı ve profil doğrulama süreçleri **tamamen E-posta OTP (E-posta Doğrulaması)** standardına dayalıdır. Telefon numarası ile kayıt veya SMS OTP gönderimi kesinlikle bulunmaz. Bot spam'lerini engellemek için tüm e-posta OTP isteklerinde sliding-window rate limit ve CAPTCHA zorunludur.
+- **TC Kimlik Doğrulama (Fikir Oluşturma İçin Zorunlu):** Vatandaş **fikir oluşturmak** için TC Kimlik No girmek zorundadır; **oy vermek için TC Kimlik gerekmez**, E-posta onayı yeterlidir. NVI (Nüfus ve Vatandaşlık İşleri) sistemine tek seferlik doğrulama yapılır. Doğrulanmış TC Kimlik, fikir oluşturma sırasında benzersiz kişi belirleme ve mükerrer fikir önleme amacıyla kullanılır. **Displays Adı Ayrımı (Nick-Name Lockout Koruması):** Vatandaşın üyelikte kullandığı displays adı (takma ad / nickname - örn: "Ahmet Can") ile MERNIS doğrulama formundaki resmi bilgiler (TCKN, resmi Ad, resmi Soyad, Doğum Yılı) birbirinden tamamen bağımsızdır. MERNIS sorgulaması resmi kimlik bilgileriyle yapılır; doğrulama başarılı olduğunda kullanıcının displays adı değişmeksizin profili `is_identity_verified = true` olarak işaretlenir. Bu sayede isim uyuşmazlığından kaynaklı katılım kilitlenmeleri önlenir.
+- **Hesaplı Kullanıcı Avantajları:** Tüm raporların tek dashboard'dan takibi, rapor geçmişi, bildirim tercihleri kaydetme, oy geçmişi görüntüleme.
+- **Anonim Kullanım:** Takip kodu ile rapor durumu, hangi müdürlükte/ekipte olduğu ve tamamlanma fotoğrafı sorgulanabilir. Kayıt gerektirmez. Anonim kullanıcılar da takip kodunu kullanarak çözülen rapora geri bildirim verebilir ve "Sorun Devam Ediyor" ile raporu `reopened` durumuna çekebilir.
+- **Hesap Silme (KVKK):** Kullanıcı hesabını ve kişisel verilerini talep üzerine silebilir. Raporlar anonimleştirilerek sistemde saklanmaya devam eder.
+
+#### Raporlama
+
+- **Harita Tabanlı Raporlama:** Leaflet haritasına tıklayarak konum seçme; il / ilçe / mahalle / sokak adres hiyerarşisi ile adresin otomatik dolması.
+- **Kategori Seçimi:** Yol hasarı, çöp, su arızası, park bakım, aydınlatma vb. (belediyenin tanımladığı kategoriler ve global kategoriler).
+- **Fotoğraf Ekleme:** Base64 veya multipart upload ile en fazla 5 fotoğraf.
+- **KVKK Onayı:** Rapor göndermeden önce zorunlu açık rıza metni ve onay.
+- **Takip Kodu:** `KENT-[plaka]-XXXXXXXX` formatında (örn: KENT-34-A1B2C3D4) benzersiz kod; anasayfada bu kodla raporun son durumu sorgulanabilir. Vatandaşın kodu kaybetme ihtimaline karşı "Kodu Cihazıma PDF/Resim Olarak İndir" seçeneği sunulur.
+- **Spam ve Suistimal Koruması (Anonim Raporlar):**
+  - **CAPTCHA:** Her anonim rapor gönderiminde Google reCAPTCHA v3 doğrulaması zorunludur.
+  - **Hız Sınırlaması (Rate Limiting):** Aynı IP üzerinden dakikada maksimum 2, günde maksimum 10 anonim rapor kabul edilir.
+  - **Coğrafi Sınır (Geofencing):** Belediye tarafından tanımlanan coğrafi sınırlar (sınır poligonu) dışındaki koordinatlardan gelen raporlar moderatör onayına düşmeden "Kapsam Dışı" olarak reddedilir.
+
+#### Geri Bildirim ve Katılım
+
+- **Geri Bildirim ve Puanlama:** Rapor `resolved` olduğunda vatandaş (hesaplı veya anonim) 1–5 yıldız arası puan verebilir ve "Sorun Devam Ediyor" butonuyla raporu `reopened` durumuna çekebilir. Anonim kullanıcı bu işlemi takip koduyla gerçekleştirir.
+- **Fikir Önerisi ve Oylama:** Şehir iyileştirme önerileri oluşturma, diğer vatandaşların +1 / -1 oylaması. **Oy vermek** için **E-posta Onaylı** hesap yeterlidir. Fikir **oluşturmak** için ek olarak **TC Kimlik Doğrulaması** (`is_identity_verified = true`) zorunludur. **Kritik Maliyet Notu:** E-posta doğrulaması hesap kaydı veya ilk onay sırasında tek seferlik asenkron OTP ile yapılır; vatandaşın yaptığı her oy verme işlemi için yeni bir e-posta gönderilmez, yetkilendirme mevcut JWT oturumu üzerinden yürütülür.
+- **Duyuru Takibi:** Belediyenin bilgi, uyarı, acil duyurularını mahalle bazında listeleme.
+
+#### Ek Özellikler
+
+- **Acil Durum / Panik Butonu:** Afet anında anlık konum paylaşımı. 112 alternatifi değildir; yasal uyarı metni zorunludur. **Kritik İstisna:** Panik butonu (Acil Durum Bildirimi) API istekleri, vatandaşın belediye sınırları dışında olabileceği (tahliye, kaçış vb.) senaryosu gereği **Geofencing (sınır doğrulama) kurallarından tamamen muaftır.**
+- **Şeffaf Şehir İstatistikleri:** Ana sayfa (`/`) üzerindeki public harita üzerinden vatandaşlara sunulan şeffaf istatistikler, `GET /v1/public/statistics` API ucundan beslenen bir widget aracılığıyla dinamik olarak gösterilecektir. Bu widget; **Aktif Çözülen Sorun Sayısı** (toplam çözülen raporlar), **Saha Çalışması Sürenler** (sahada müdahale edilen aktif işler), **Vatandaş Desteği (+1)** (vatandaşların toplam "+1 Beni de Etkiliyor" oyları) ve **Ortalama Çözüm Süresi** (hedef SLA sürelerine uyum oranı ve ortalama kapatma hızı) metriklerini şeffaf ve anlık olarak harita ile entegre bir şekilde sunacaktır.
+- **Engelsiz Erişim:** Ana sayfa (`/`) ve üzerindeki public harita + modal'lar WCAG AA/AAA uyumlu olacak şekilde tasarlanacaktır (klavye navigasyonu, focus yönetimi, screen reader desteği).
+- **Geri Dönüşüm Haritası:** Cam, kâğıt, pil vb. atık türlerine göre en yakın toplama noktalarını gösterme ve navigasyon başlatma.
+- **Afet Toplanma Alanları (Afet Modu):** Afet durumunda en yakın resmi toplanma alanlarının haritada gösterilmesi ve tahliye rotası oluşturulması. Normal modda pasif olup, Afet Modu'nda (Central tetiklemeli) vatandaş haritasında otomatik bir katman (layer) olarak belirir.
+- **Anlık Bildirim Tercihleri:** E-posta, SMS veya mobil push bildirimi. Hesaplı kullanıcılar terciheri dashboard'dan yönetir; anonim kullanıcılar rapor oluştururken tercihlerini belirtir.
+
+---
+
+## Modül D: Kapsam Dışı (Out of Scope)
+
+| Madde | Açıklama |
+| :--- | :--- |
+| **Ödeme Sistemleri** | Vergi, ceza veya su faturası ödemeleri sistem kapsamı dışındadır. |
+| **Personel İK Süreçleri** | İşe alım, maaş yönetimi ve resmi özlük işleri kapsanmaz. |
+| **Gelişmiş Envanter** | Belediye demirbaşlarının (araç, bina vb.) detaylı teknik takibi yapılmaz. |
+| **Doğrudan Mesajlaşma** | Vatandaş ile belediye personeli arasında uçtan uca (P2P) sohbet özelliği yoktur; iletişim yalnızca durum güncellemeleri ve yorumlar üzerindendir. |
+
+---
+
+## KENTİM Sürüm Yol Haritası
+
+Bu bölüm, KENTİM platformunun **MVP** ve **V1** sürümleri arasındaki özellik ayrımını tanımlar. Hiçbir özellik silinmemiştir; yalnızca hangi sürümde yer alacağı netleştirilmiştir.
+
+### MVP Sürümü (Gerçekçi Minimum Kapsam)
+
+**MVP Tanımı:**  
+Vatandaşın sorunu harita üzerinden bildirebildiği, belediyenin bu sorunu temel hiyerarşiyle (Moderatör → Müdür → Şef → Personel) işleyebildiği ve vatandaşa temel geri bildirim döngüsünün kapandığı **minimum çalışır ürün**.
+
+#### MVP’de Kesinlikle Olması Gerekenler (Core MVP)
+
+**Vatandaş Tarafı (Public Web):**
+- Ana sayfa = Tam ekran Public Sorun Haritası (BBOX bazlı dinamik yükleme + basit clustering)
+- Haritadan konum seçip rapor oluşturma (modal)
+- Rapor takip (takip kodu ile)
+- "+1 Beni de Etkiliyor" desteği (JWT ile)
+- Temel fikir oluşturma + oylama (E-posta onaylı hesap + TC Kimlik doğrulaması)
+- Panik butonu (geofence muaf, temel konum paylaşımı)
+- Temel statik içerikler (modal üzerinden)
+
+**Belediye Tarafı (Temel Akış):**
+- Moderatör: Raporları inceleme, müdürlüğe havale, public visibility toggle
+- Müdür: İş atama (şef + direkt personele), manuel iş emri oluşturma
+- Şef: Personele atama, fotoğraf onayı / reddi
+- Saha Personeli (Mobil): Kendine atanan işleri görme, işi başlatma, konum + zaman damgalı fotoğraf ile tamamlama, vardiya aç/kapat
+- Temel bildirimler (E-posta + Push) — sadece kritik olaylar için
+
+**Yönetim (Minimum):**
+- Temel Belediye Admin: Kullanıcı/ekip/müdürlük yönetimi, temel kategori yönetimi
+- Temel Central: Belediye onboarding, lisans takibi, sistem sağlık izleme (sadece izleme)
+
+**Teknik Minimum:**
+- Tenant izolasyonu (RLS)
+- Temel audit log (JSONB old/new)
+- 50m geofence (sade versiyon)
+- Public harita (fuzzing + masking)
+
+#### MVP’de Kesinlikle Olmaması Gerekenler (V1’e Atıldı)
+
+- QA Döngüsü + Circuit Breaker
+- Çevrimdışı Dispute Pool + Hak ediş çözümü
+- IoT Entegrasyonu + Custom V8 Parser
+- Geofence Boundary Versioning
+- Dinamik Özel Rapor Oluşturucu (Custom Report Builder)
+- Akıllı Yönlendirme Kuralları
+- AI Moderasyon / IVR
+- Gelişmiş Central raporlama ve Executive Reports
+- Public Web Yol Haritası yönetimi ve gösterimi (V1)
+- Gelişmiş Public Harita (Vector Tile, ısı haritası vb.)
+
+**Not:** Yukarıdaki liste, "yazılım ekibi neyi yapmak zorunda?" sorusuna net cevap verecek şekilde tasarlanmıştır. MVP’de olmayan hiçbir özellik, geliştirme sırasında "acaba yapsak mı?" tartışmasına açılmamalıdır.
+
+### V1 Sürümü (Gelişmiş Özellikler)
+
+V1 sürümünde operasyonel derinlik, otomasyon ve analitik yetenekler artırılır.
+
+#### V1 - Faz 1: Operasyonel Güçlendirme
+| Özellik | Açıklama |
+|---------|----------|
+| QA Döngüsü + Circuit Breaker | Vatandaş düşük puan verdiğinde şefin kalite denetimi yapması ve 3+ fotoğraf reddinde müdüre eskalasyon |
+| Çevrimdışı Dispute Pool | Saha personelinin çevrimdışı tamamladığı işlerde çakışma çözümü ve hak ediş koruması |
+| Geofence Boundary Versioning | Belediye sınırları değişse bile iş emrinin oluşturulduğu andaki sınır sürümünün kullanılması |
+| Gelişmiş Geofence Bypass | EXIF + gerekçe ile şef onayıyla konum düzeltme |
+
+#### V1 - Faz 2: Akıllı Sistemler ve Entegrasyon
+| Özellik | Açıklama |
+|---------|----------|
+| IoT Entegrasyonu + V8 Sandbox | Custom payload mapping ve belediye admin'inin kendi JS parser yazabilmesi (tam kapasite) |
+| AI Fotoğraf Moderasyonu | Gelen fotoğrafların otomatik kategorize edilmesi ve uygunsuz içerik tespiti |
+| Sesli Yanıt Sistemi (IVR) | Çağrı merkezi entegrasyonu ile telefon şikayetlerinin sisteme otomatik aktarımı |
+| Akıllı Yönlendirme Kuralları | Kategori + konum bazlı otomatik müdürlük yönlendirmesi (büyükşehir-ilçe çakışmaları dahil) |
+
+#### V1 - Faz 3: İleri Analitik ve Raporlama
+| Özellik | Açıklama |
+|---------|----------|
+| Dinamik Özel Rapor Oluşturucu (Custom Report Builder) | Drag-and-drop ile belediye yöneticilerinin kendi raporlarını oluşturması |
+| Executive Presentation Reports | Central SaaS için yönetim kurulu sunumlarına hazır PDF/XLSX rapor motoru |
+| Gelişmiş Central Analitik | Belediye karşılaştırma, trend analizi, tahmin modelleri |
+| Read-Replica + ETL Pipeline | Raporlama yükünün operasyonel veritabanından ayrılması |
+
+#### V1 - Faz 4: Mimari ve Operasyonel İyileştirmeler (Opsiyonel)
+| Özellik | Açıklama |
+|---------|----------|
+| Hibrit Kuyruk Mimarisi | Kritik kuyruklar (panic, dispute) için PostgreSQL + managed queue (SQS/RabbitMQ) hibrit yapısı |
+| Vector Tile + Pre-aggregate Public Harita | Yüksek ölçekli public harita performansı için |
+| Gelişmiş Parser Script Yönetimi | V8 Sandbox scriptleri için versiyonlama, inceleme ve rollback mekanizmaları |
+
+> **Not:** Yukarıdaki V1 özellikleri, mevcut dokümantasyonda "MVP Sonrası", "Faz 2" veya "Gelecek Planı" olarak geçen tüm maddeleri kapsamaktadır. Hiçbir özellik kaybolmamıştır.
+
+---
+
+### Public Web Yol Haritası (Vatandaş Arayüzü)
+
+Public Web (kentim.com.tr) tarafı için özel olarak tanımlanmış sürüm yol haritası aşağıdadır.
+
+#### Public Web - MVP Sürümü
+- Tam ekran interaktif Public Sorun Haritası (Leaflet + BBOX dinamik yükleme)
+- Harita üzerinden rapor oluşturma (modal)
+- Rapor takip (takip kodu ile)
+- "+1 Beni de Etkiliyor" desteği (JWT ile)
+- Temel fikir oluşturma ve oylama (E-posta onaylı hesap + TC Kimlik doğrulaması)
+- Duyuru takibi
+- Geri Dönüşüm Haritası (temel)
+- Panik / Acil Durum Butonu (geofence muaf)
+- Afet modunda toplanma alanları katmanı
+- Statik içerikler (Hakkımızda, KVKK, Gizlilik vb.) modal üzerinden (merkezi yönetilen)
+- Temel erişilebilirlik (WCAG AA hedefi)
+
+#### Public Web - V1 Sürümü
+| Özellik | Açıklama |
+|---------|----------|
+| Gelişmiş Public Harita | Vector Tile desteği, ısı haritası katmanları, daha zengin filtreleme ve zaman bazlı oynatma |
+| AI Destekli Öneri | Vatandaş konum seçtiğinde yakın benzer raporları AI ile daha akıllı önerme |
+| Gelişmiş Katılım | Fikirlere yorum yapabilme, fikir takibi, belediye yanıtlarına abone olma |
+| Kişiselleştirilmiş Dashboard | Giriş yapmış vatandaş için daha zengin kişisel rapor + destek + fikir geçmişi |
+| Gelişmiş Afet Modu | Tahliye rotası optimizasyonu, yakınlardaki resmi yardım noktaları, aile ile konum paylaşımı |
+| Topluluk İstatistikleri Widget'ı | Daha detaylı ve interaktif şeffaflık paneli |
+| Erişilebilirlik Tamamlanması | Tam WCAG AAA uyumu + ekran okuyucu optimizasyonları |
+
+> **Yönetim Notu (Çözüm):**  
+> Bu Public Web Yol Haritası **sadece Merkez Panel (Central Admin)** üzerinden yönetilebilir.  
+> - Belediye Paneli bu içeriğe erişemez ve değiştiremez.  
+> - Central Admin, MVP ve V1 yol haritalarını ayrı ayrı düzenleyebilir (yeni ekran: `/public-web-roadmap`).  
+> - İçerik `central_static_contents` tablosu üzerinden `public_web_roadmap_mvp` ve `public_web_roadmap_v1` key’leri ile yönetilir.  
+> - Vatandaş arayüzünde `/?modal=roadmap` ile gösterilebilir.  
+> 
+> **Detaylı Geliştirme Rehberi:**  
+> - Ekran tanımı + Acceptance Criteria + İş Kuralları → `yapı.md` → 3.11  
+> - API Kontratları → `api-referans.md` → Central Panel bölümü  
+> - Migration + Teknik Altyapı → `mimari.md` → Merkezi Statik İçerik Yönetimi
+
+---
+
+## Modül F: Tasarım Kararları ve Netleşen Maddeler
+
+Aşağıdaki tasarım kararları, KENTİM platformunun mimari bütünlüğü ve mevcut kod tabanındaki fiili implementasyonlar esas alınarak netleştirilmiş ve karara bağlanmıştır.
+
+| # | Konu | Durum / Karar Detayı |
+| :--- | :--- | :--- |
+| **F1** | Abonelik bittiğinde belediyenin panel erişimi kapanacak mı? | **Kısıtlı Salt-Okunur Erişim (Netleşti):** Hayır, panel erişimi kapatılmaz. Sistem genelinde yeni veri girişi kısıtlanırken, mevcut açık işlerin kapatılması ve geçmiş kayıtların incelenmesi için paneller kalıcı bir uyarı notuyla (banner) açık kalır. |
+| **F2** | Saha personeli GPS takibi için açık rıza ve yasal yükümlülük detayları | **Yasal Uyarı ve İzin (Netleşti):** Veritabanı altyapısı (`staff_locations`) hazırdır. Saha personeli mobil uygulama üzerinden GPS paylaşımını açık rıza metnini onaylayarak kabul eder. |
+| **F3** | Afet modu sinyali sonrası hangi belediye aksiyonları otomatik tetiklenmeli? | **Global Bildirim & Katman Aktivasyonu (Netleşti):** Central Gateway üzerinden gönderilen sinyalle tüm belediyelerin vatandaş arayüzünde "Acil Yardım / Panik Butonu" öne çıkarılır ve haritada "Afet Toplanma Alanları" katmanı (layer) otomatik olarak aktifleşerek kullanıcıya en yakın 3 güvenli nokta gösterilir. |
+| **F4** | İkincil müdürlük bildirimleri hangi kanaldan gitmeli — sistem içi mi, e-posta mı? | **Sistem İçi Log & Liste (Netleşti):** İkincil müdürlük atamaları veritabanında (`secondary_department_ids`) saklanır. Sistem içi işlem logları ve müdür panelindeki bilgi sekmesi üzerinden takip edilir. |
+| **F5** | Anonim kullanıcıdan bildirim için iletişim bilgisi alınması KVKK kapsamında nasıl değerlendirilecek? | **KVKK Onay Formu (Netleşti):** Anonim rapor gönderimi sırasında vatandaştan KVKK Açık Rıza metninin zorunlu olarak onaylanması ve isteğe bağlı SMS/e-posta izni alınması kararlaştırılmıştır. |
+| **F6** | `assigned_to_team` veya `in_progress` aşamasındaki iş emirlerinde re-dispatch için hangi yetki gereklidir? | **Doğrudan Re-dispatch & Loglama (Netleşti):** Müdür, muni_admin ve üst yetkililer iş akışının herhangi bir aşamasında doğrudan re-dispatch yapabilir; ek onay süreci gerekmez. Her re-dispatch işlemi denetim loguna (`REPORT_REDISPATCHED`) kaydedilir. |
+| **F6.1** | Şef kendi manuel oluşturduğu iş emrinde onay yetkisi kime aittir? | **Şef Kendi İşinde Onay Kuralı (Netleşti):** Şef (`muni_team_chief`), kendi oluşturduğu manuel iş emrine doğrudan personel atadığında (şef bypass yok), personel işi tamamlayıp `pending_chief_approval` durumuna getirdiğinde onay yetkisi **şefin kendisine** kalır. Müdür bypass kuralı (onayın müdüre düşmesi) yalnızca müdürün şefi atlayıp doğrudan atama yaptığı durumlarda geçerlidir. **Ek Senaryo — Şef İşi + Müdür Ataması:** Şef işi `dispatched_to_department` bırakır ve müdür bu işe doğrudan personel atarsa (şefi bypass ederek), iş tamamlandığında onay yetkisi standart müdür bypass kuralı gereği **müdüre** döner. İşi şefin oluşturmuş olması bu kuralı değiştirmez; belirleyici olan **atama eylemini kimin gerçekleştirdiğidir.** |
+| **F7** | `rejected` durumunu kim tetikleyebilir — yalnızca moderatör mü, müdür de mi? | **Yetki Kontrolü (Netleşti):** `reports:moderate:reject` yetkisine sahip moderatör (`muni_moderator`) ve sistem yöneticileri (`muni_admin`) gerekçeli olarak raporu reddedebilir. |
+| **F8** | Dış sistem entegrasyonu için API standardı ne olacak — REST webhook mi, event queue mi? | **REST API & Webhook (Netleşti):** Dış sistemlerle hızlı ve güvenli entegrasyon için Fastify uyumlu REST Webhook ve API anahtarı (`integration` kaynak tipi) standardı uygulanmaktadır. |
+| **F9** | Periyodik iş üretimi başarısız olursa (sistem hatası) bildirim kime gidecek — muni_admin mi, ilgili müdür mü? | **Sistem Denetim Günlüğü (Netleşti):** Başarısızlık durumunda hata kayıtları doğrudan sistem denetim günlüğüne (`audit_logs`) kaydedilir ve belediye sistem yöneticisi (`muni_admin`) panelinde görünür. |
+| **F10** | Fotoğraf zorunluluk kuralı kategoriye göre mi belirlenmeli, müdürlüğe göre mi, yoksa her ikisi de mi? | **Kategori Bazlı (Netleşti):** Her iş ve rapor kategorisinin kendine ait fotoğraf zorunluluk kuralı belediye yöneticisi (`muni_admin`) tarafından esnek olarak tanımlanır. |
+| **F11** | Şefin personel fotoğrafını reddetme sayısında üst sınır olacak mı — tekrarlı ret durumunda eskalasyon müdüre gidecek mi? | **Eskalasyon Devre Kesici (Netleşti):** Şefin toplam ret geçmişinde sayı sınırı yoktur. Ancak art arda 3 ret circuit breaker'ı tetikler ve iş in_progress yerine pending_manager_review'a düşer. |
+| **F12** | Periyodik iş şablonunda varsayılan şef/ekip tanımlanmamışsa iş emri müdüre mi düşecek, yoksa sistem uyarısı mı üretecek? | **Müdür Havuzu (Netleşti):** Şablonda ekip atanmamışsa, otomatik üretilen iş emri doğrudan ilgili müdürlüğün atanmamış havuzuna (`dispatched_to_department` durumunda) düşer ve müdür tarafından manuel atanır. |
+| **F13** | Central ↔ Belediye veri iletişimi hangi protokol üzerinden, hangi sıklıkta gerçekleşir? | **REST / HTTPS Push (Netleşti):** Belediye backend'leri 15 dakikalık aralıklarla anonimleştirilmiş istatistikleri central API'ye push eder. Heartbeat 1 dakikada bir kontrol edilir. Geçici kesintilerde veriler kuyruklanır ve bağlantı yeniden kurulduğunda toplu iletilir. |
+| **F14** | Fikir Reddi Bildirimi | **Tasarım Kararı:** Fikir reddinde vatandaşa bildirim gönderilmeyecektir. |
+| **F15** | Public Harita Varsayılan Politikası | **Tasarım Kararı:** Public harita varsayılan politikası belediye ayarına bırakılır; merkezi varsayılan "Otomatik Görünür" olarak belirlenmiştir (moderation aşamasından itibaren görünür). Belediye `muni_admin` bu varsayılanı değiştirebilir. |
+
+---
+
+## Modül G: Sistem Bütünlüğü ve Veri Yaşam Döngüsü
+
+### G1. Veri Saklama ve Arşivleme Politikası (Media & Data Retention)
+
+- **Aktif Veri:** Çözülmemiş (`pending`, `in_progress` vb.) tüm iş emirlerine ait görseller tam çözünürlükte saklanır.
+- **Arşivleme:** İş emri `resolved` veya `rejected` olduktan 6 ay sonra görseller optimize edilerek (boyut küçültme) saklanmaya devam eder.
+- **Otomatik Silme (Görsel):** Kapatılan iş emirlerine ait fotoğraflar, kapatılma tarihinden 1 yıl sonra sistemden otomatik olarak silinir. Bu silme sürecinde arka planda şu adımlar garanti edilir: Silme işleminden sonra `public_work_orders_view`'daki `photo_urls` alanı güncellenir (silinen fotoğraf çıkartılır); ilgili tenant'ın `public_map_cache` tablosundaki tüm önbellek satırları anında invalidate edilir; harita istemcisine gönderilecek popup'ta fotoğraf yoksa placeholder gösterilir.
+- **Soğuk Depolama (Metin):** İş emrine ait metin kayıtları, denetim logları ve vatandaş geri bildirimleri ilk 3 yıl aktif veritabanında saklanır. 3 yılı aşan kayıtlar, performans ve maliyet yönetimi amacıyla "Soğuk Depolama" (Cold Storage / S3) birimlerine taşınır ve istatistiksel amaçlarla arşivlenir.
+
+### G2. Eşzamanlılık ve Kayıt Kilitleme (Concurrency)
+
+- **İyimser Kilitleme (Optimistic Locking):** Tüm kritik tablolar (iş emirleri, raporlar) `version` sütununa sahiptir. Aynı kayıt üzerinde iki farklı kullanıcının (örn. iki moderatörün aynı raporu havale etmeye çalışması) işlem yapması durumunda, ikinci gelen istek "Kayıt Güncel Değil" hatasıyla reddedilir ve sayfanın yenilenmesi istenir.
+- **İşlem Önceliği:** Bir personel "Yarıda Bırak" işlemi yaparken tam o anda şef "Onayla" yaparsa, veritabanı seviyesindeki kilit mekanizması ilk gelen isteği geçerli kılar; diğer işlem için kullanıcıya işlemin zaten başka bir kullanıcı tarafından tamamlandığı bilgisi döner.
+- **`support_count` Yüksek-Trafik Row-Locking Önlemi:** "+1 Beni de Etkiliyor" oylaması yoğun trafik altında `work_orders` tablosunda row-locking darboğazına neden olabilir. Bu riski ortadan kaldırmak için `support_count` sayıcı gerçek zamanlı DB trigger yerine **PostgreSQL LISTEN/NOTIFY tabanlı debounced asenkron worker** ile güncellenir. Her "+1" oyu önce `support_count_queue` unlogged tablosuna `INSERT` edilir, `pg_notify('support_count_channel', work_order_id)` ile worker tetiklenir ve worker toplu `bulk UPDATE` ile veritabanına yansıtır. Detaylı tasarım için bkz. `mimari.md` — Asenkron `support_count` Debouncer Mimarisi.
+
+
+---
+
+## Modül H: Bildirim Matrisi (Notification Matrix)
+
+Sistemdeki tüm bildirimler `system` servisi tarafından yönetilir. Bildirim kanalları: **Push (Mobil Uygulama), SMS ve E-posta.**
+
+| Tetikleyici Olay | Alıcı | Kanal | İçerik Özeti |
+| :--- | :--- | :--- | :--- |
+| Yeni Vatandaş Raporu | Vatandaş | SMS/E-posta | Takip kodu ve alındı bilgisi. |
+| Rapor Müdürlüğe Havale Edildi | Müdür | Push/Panel | Yeni iş emri havale bildirimi. |
+| İş Şefe/Personele Atandı | Şef/Personel | Push | "Size yeni bir iş atandı" bildirimi. |
+| İş Tamamlandı (Fotoğraf Yüklendi) | Şef | Push | "Onayınızı bekleyen iş tamamlandı." |
+| İş Onayla (`resolved`) | Vatandaş | SMS/E-posta/Push | "Sorununuz giderildi" + Fotoğraflı kanıt linki. |
+| Ana iş emri resolved olduğunda bağlı tüm mükerrer raporlar | Vatandaş (Mükerrer) | SMS/E-posta/Push | "Sorununuz giderildi" bildirimi gönderilir. |
+| Fotoğraf Reddedildi | Personel | Push | "Fotoğraf yetersiz, lütfen tekrar yükleyin." |
+| SLA Kritik (%80 süre doldu) | Müdür/Şef | Push/Panel | "İş emri SLA aşımına yaklaşıyor." |
+| SLA Aşıldı | Admin/Müdür | E-posta/Push | "SLA aşıldı, eskalasyon başlatıldı." |
+| Re-opened (Vatandaş Tarafından) | Moderatör | Push/Panel | "Rapor yeniden açıldı, tekrar incelenmesi gerekiyor." |
+| Müdür İncelemesi (Circuit Breaker) | Müdür | Push/Panel | "Eskalasyon: Sürekli fotoğraf reddi nedeniyle iş emri incelemenize düştü." |
+| Re-dispatch Ping-Pong (3. re-dispatch'te) | Admin | Push/Panel | "Anlaşmazlık: İş emri admin incelemesine düştü." |
+| Raporu "+1" ile Destekleyenler | Vatandaş (Destekçi) | SMS/E-posta/Push | "Desteklediğiniz [Takip Kodu] nolu sorun çözüldü." |
+| Yeni "+1" Desteği Alındığında | Moderatör / Şef | Push/Panel | "Yönettiğiniz iş emrine yeni vatandaş desteği eklendi." |
+| Personel İşi Yarıda Bıraktı | Şef | Push | "Görev yarıda bırakıldı, personel üzerinden alındı." |
+| Abonelik Bitiş (Son 30/7/1 gün) | Admin | E-posta/Push | "Abonelik süreniz dolmak üzere, lütfen yenileyin." |
+| Geofence Bypass Talebi Onaylandı | Personel | Push | "Geofence bypass talebiniz onaylandı, iş tamamlanma aşamasına geçti." |
+| Geofence Bypass Talebi Reddedildi | Personel | Push | "Geofence bypass talebiniz reddedildi, lütfen iş noktasına yaklaşarak tekrar deneyin." |
+
+---
+
+## Modül I: Mobil Uygulama ve Saha Operasyonu (muni_worker / muni_team_chief)
+
+Mobil uygulama (React Native / Flutter), saha personelinin kısıtlı bant genişliği ve çevrimdışı çalışma ihtiyacına göre tasarlanmıştır.
+
+### I1. Çevrimdışı Çalışma (Offline-First)
+- **Offline Queue:** İnternet yokken yapılan "İşi Başlat", "Fotoğraf Yükle" ve "Not Ekle" işlemleri yerel cihazda kuyruğa alınır.
+- **Auto-Sync:** İnternet geri geldiğinde (arka planda) tüm kuyruk Idempotency kurallarına göre sunucuya basılır.
+- **Çevrimdışı Çakışma Yönetimi:** Personel çevrimdışıyken tamamladığı iş, o esnada başkasına atanmışsa veri doğrudan silemez; sunucudaki **"Senkronizasyon Uyuşmazlık Havuzu"**'na kaydedilir ve şefin ekranına "Manuel Çakışma Çözümü" uyarısıyla düşer. Şef doğruluğu teyit ederse işi geçmişe dönük onaylayabilir.
+- **Pre-fetch:** Personel sabah uygulamayı açtığında kendisine atanan işlerin detayları ve konum verileri yerel belleğe (SQLite/MMKV) indirilir.
+
+### I2. Konum Takibi ve Geofencing
+- **Background GPS:** Saha personeli "Vardiyayı Başlat" dediğinde, pil tasarruflu arka plan konum takibi başlar.
+- **Geofence Check:** Personel, iş emrinin koordinatına 50 metreden daha uzaksa "İşi Bitir" butonuna basamaz (istisnalar admin tarafından tanımlanabilir).
+
+---
+
+## Modül J: Hata Yönetimi ve Operasyonel Dayanıklılık
+
+| Senaryo | Sistem Davranışı | Kullanıcı Deneyimi |
+| :--- | :--- | :--- |
+| Geofencing Reddi | API isteği reddedilir (422 Unprocessable Entity). | "Seçtiğiniz konum belediyemiz sınırları dışındadır." uyarısı. |
+| OTP Servis Hatası | 3 saniye içinde yanıt alınmazsa fallback (ikincil servis) tetiklenir. | Kullanıcı gecikmeyi hissetmez; "Kod gönderildi" mesajı alır. |
+| Geçersiz Webhook Verisi | Hatalı istek `integration_logs` tablosuna `FAILED` olarak kaydedilir. | Dış sistem 400 hatası alır; admin panelinde "Entegrasyon Hatası" görünür. |
+| Veritabanı Conflict (409) | Versiyon uzyuşmazlığı algılanır. | "Bu kayıt başka biri tarafından güncellendi, lütfen sayfayı yenileyin." |
+
+| **Entegrasyon & IoT** | Fastify Webhook ile sensör verisi alma, hazır JS parser scriptleri ile standart şemaya dönüştürme, otomatik iş emri tetikleme ve Sensör Spam Cool-Down. GUI tabanlı drag-and-drop IoT Payload Mapper editörü, karmaşık telemetri verileri için asenkron makine öğrenmesi arıza tahmini, **afet modu asenkron panik sinyali kuyruk debouncer mimarisi (PostgreSQL LISTEN/NOTIFY + unlogged tablo)**. |
+
+---
+
+*MVP Sürümü — KENTİM Teknik Spesifikasyon Belgesi*
+
+---
+
+## Proje Kapsam Sınırları, MVP Mimarisi ve Erişilebilirlik Standartları (Güncellendi)
+
+Bu belge, KENTİM platformunun tüm teknik, mantıksal ve operasyonel çözümlerini **MVP (Minimum Uygulanabilir Ürün)** kapsamında tek bir bütünsel sürüm olarak tanımlar:
+
+### 1. MVP Proje Kapsamı ve Fonksiyonel Modül Dağılımı
+
+Belediye ve vatandaş deneyimini en üst düzeyde sunmak amacıyla tüm gelişmiş özellikler doğrudan MVP kapsamında aktif ve zorunludur:
+
+| Fonksiyonel Alan | Core MVP Kapsamı (Zorunlu ve Tamamı Dahildir) |
+| :--- | :--- |
+| **Vatandaş Etkileşimi** | **Leaflet (Leaflet Map)** tabanlı tam ekran interaktif sorun bildirme, Rapor Takip modalı, E-posta onaylı fikir önerisi oylama (sosyal katılım modülü), Geri dönüşüm noktaları haritası ve navigasyon entegrasyonu, Anonim geri bildirim/reopen (Standart SLA'in %50'si ile), E-posta OTP ile tek seferlik onaylı kayıt, **kronik sorunlar zinciri (`parent_reopened_work_order_id`)**. |
+| **Harita ve Performans** | **Leaflet interaktif harita modülü** üzerinden BBOX (Bounding Box) dinamik veri yükleme, unlogged `public_map_cache` tablosu (30s TTL), asenkron `support_count` debounced worker. `Leaflet.markercluster` gelişmiş kümeleme animasyonları, ilçe bazlı otomatik kriz analiz ısı haritası katmanı. Harita ve listeleme arayüzlerinde bellek yorulmalarını engellemek için **sayfalama (pagination - sayfa/limit/cursor bazlı)** kullanımı zorunludur. |
+| **İş Akışları & SLA** | Standart Hiyerarşik Dağıtım (Müdür → Şef → Çalışan), Çalışma saati bazlı SLA, Kriz/Acil durumlarda 7/24 kesintisiz SLA sayacı, QA Düzeltme SLA Grace Period. OSRM ile günlük şef sürükle-bırak rota optimizasyonu, otomatik SLA eskalasyonu sonrası dış kurum (örn: 112) webhook entegrasyonları. |
+| **Saha ve Mobil** | Çevrimdışı (Offline-First) görev listesi, 50m geofence fotoğraf kanıt kontrolü, vardiya devri (handover), şef fotoğraf onayı, Geofence Bypass ve Auto-Handover. Senkronizasyon Uyuşmazlık Havuzu (`dispute_logs`) görsel arayüzü, saha personeli canlı GPS rotası geçmiş analitiği, **PostGIS geofence sürüm kilidi (`boundary_version_id` ve `municipal_boundary_versions` ilişkisi)**. **Çevrimdışı Handover İstisnası:** Personelin yerel çevrimdışı iş bitirme zaman damgası sunucunun otomatik vardiya kapatma (handover) zaman damgasından önce ise uyuşmazlık havuzuna (`dispute_logs`) hak ediş teyidi olarak yönlendirilir ve personelin emeği korunur. |
+| **Entegrasyon & IoT** | Fastify Webhook ile sensör verisi alma, hazır JS parser scriptleri ile standart şemaya dönüştürme, otomatik iş emri tetikleme ve Sensör Spam Cool-Down. GUI tabanlı drag-and-drop IoT Payload Mapper editörü, karmaşık telemetri verileri için asenkron makine öğrenmesi arıza tahmini, **afet modu asenkron panik sinyali kuyruk debouncer mimarisi (PostgreSQL LISTEN/NOTIFY)**. |
+| **Yasal Uyumluluk** | Kişisel verilerin view seviyesinde maskelenmesi (`approximate_coordinates`), vatandaş hesap silme akışı. `audit_logs` tablosundaki old_value/new_value alanlarını asenkron regex (indeksli citizen_id, 500'lük paket, 100ms gecikmeli) ile temizleyen tam GDPR arayüzü. |
+| **Raporlama ve Analitik** | Standart analitik sekmeleri, performans ve SLA raporları, PDF/XLSX dışa aktarma. **Belediye Dinamik Özel Rapor Oluşturucu (Custom Report Builder) ve periyodik e-posta zamanlayıcı, Merkez SaaS Yönetici Sunum Raporları (Executive Presentation-Ready Reports) PDF/XLSX motoru.** Listelerde **veri sayfalama (pagination)** zorunluluğu. |
+
+### 2. Vatandaş Arayüzü Erişilebilirlik (WCAG AA/AAA) Standartları
+
+KENTİM vatandaş arayüzünün (tam ekran public harita + modal/drawer yapısı) engelsiz erişime uyumlu olması için şu kurallar uygulanır:
+- **Focus Trap (Odak Tuzağı):** Harita üzerinde bir modal veya drawer açıldığında, klavye odağı (`Tab` tuşu) yalnızca bu modal içindeki elemanlar arasında dönebilir. Haritanın arka plandaki diğer pinlerine veya butonlarına odaklanılması engellenir.
+- **Klavye Kontrolleri:** `Esc` tuşu açık olan en üstteki modal veya drawer'ı anında kapatır ve odağı modalı açan ana butona iade eder. Harita pinleri klavyedeki ok tuşlarıyla gezilebilir ve `Enter` ile detay penceresi açılabilir.
+- **WAI-ARIA Yapısı:** Tüm modal pencerelerinde `role="dialog"`, `aria-modal="true"` ve `aria-labelledby="modal-title"` öznitelikleri zorunludur. Haritadaki pinlerin ekran okuyucu alternatif metin şeması `"Kategori: [Kategori], Durum: [Durum], Destekçi: [Destek Sayısı]"` şeklinde dinamik oluşturulur.
+
+### 3. Mobil Jest ve Drawer Çakışma Yönetimi
+
+Mobil cihazlardaki dokunma (touch/swipe) çakışmalarını önlemek amacıyla şu standartlar geçerlidir:
+- **Etkileşim Kilidi (Gesture Lock):** Harita üzerinde bir bottom sheet (drawer) modalı açıldığında, haritanın serbest kaydırılması (`dragging`) ve zoom yapılması geçici olarak kilitlenir. Böylece bottom sheet yukarı kaydırılırken haritanın da beraberinde kayması önlenir.
+- **Snap-Point Mekanizması:** Bottom sheet çekmecesi 3 aşamalı yükseklik sınırına (snap-points) sahiptir:
+  - `%10` (Minimum: sadece başlık ve durum rozeti görünür, harita alanı maksimumdur).
+  - `%50` (Orta: rapor açıklaması ve ilk fotoğraf görünür).
+  - `%95` (Maksimum: tüm detaylar, zaman çizelgesi ve yorum yazma alanı görünür).
+- **Kaydırma Yakalama (Scroll Capturing):** Drawer içeriği en üst sınıra (`%95`) ulaşmadan drawer içindeki dikey kaydırma (`overflow-y: auto`) çalışmaz; tüm yukarı sürükleme hareketleri drawer'ı büyütür. Drawer en tepeye ulaştığında dikey kaydırma aktifleşir.
+
+### 4. Standartlaştırılmış Analitik (Analytics) Yapısı
+
+Modal tabanlı vatandaş navigasyonunun doğru ölçülmesi için her modal geçişinde API veya istemci katmanında şu event şemasıyla tracking yapılır:
+- `modal_open`: Tetiklendiği an payload olarak `modal_type` (değerler: `report-new`, `track`, `announcement`, `idea`, `profile`, `about`, `faq`), `tracking_code` (varsa) ve `source` (tıklanan buton konumu) iletilir.
+- `modal_close`: Modal kapatıldığında tetiklenir, payload olarak sadece kapatılan `modal_type` bilgisini içerir.
+- `support_vote_added` / `idea_vote_submitted`: Vatandaş oylamalarında oy yönü ve ilgili rapor/fikir UUID bilgisi analitik sunucusuna push edilir.
+
+**Sonuç:** KENTİM platformu, iş akışları, güvenlik ve KVKK açısından yüksek olgunlukta tasarlanmıştır. Operasyonel başarı için D1-D5 (mimari.md) maddelerinde tanımlanan migration disiplini, secret rotasyonu, restore drill'leri ve LISTEN/NOTIFY kapasite testleri zorunludur. Bu standartlar olmadan teknik borç riski devam eder.
+
+
+## EK: Public (Halka Açık) Harita Geçişi — Özet Değişiklikler
+
+Bu ek bölüm, projenin "public (halka açık) harita tabanlı" görünürlüğe geçişiyle ilgili yüksek seviyeli proje tanımı ve vatandaş-özgü davranış değişikliklerini tanımlar.
+
+- **Proje Tanımı güncellemesi:** Tüm aktif ve tamamlanmış raporlar (varsayılan: son 6 ay), vatandaş kimliği maskelenerek halka açık bir harita üzerinde yayınlanır. Vatandaşlar harita üzerinden diğer raporları görebilir, bir rapora "+1 Beni de Etkiliyor" desteği verebilir ve yeni rapor açmadan önce aynı alandaki mevcut sorunları inceleyebilir.
+- **İş Emri Durum Makinesi:** `is_public_visible` boolean alanı ve `public_hidden_reason` (enum) eklenecek; `pending` ve `rejected` durumları public haritada görünmeyecek; `moderation` ve sonrası çoğu durum public haritada görünür olacak (detaylar modüllerde ve iş akışlarında belirtilir).
+- **Mükerrer Önleme:** Ana sayfadaki harita üzerinde konum seçildiğinde, 50–100m yarıçapındaki public raporlar API'den sorgulanır; eşleşme varsa kullanıcıya bilgi kartı ve "+1" seçeneği sunulur (modal içinde).
+- **KVKK & Maskeleme:** Public API katmanı yalnızca maskelenmiş/projeksiyonlanmış alanları döndürür; hassas alanlar (telefon, e-posta, citizen_id vb.) veritabanı view seviyesinde dışlanır.
+
+Detaylı değişiklikler ve teknik gereksinimler modüller ve mimari belgelerinde ayrı başlıklar altında yer almaktadır.
+
+### EK - Public Harita ve Modal Modeli (MVP Kapsamı)
+
+1) Kaynak Tipi Bazlı Public Görünürlük (Modül A7)
+- Varsayılan `is_public_visible` değerleri (değiştirilebilir `muni_admin` ayarı) aynen korunur.
+
+2) Şeffaf Şehir İstatistikleri
+- Ana sayfadaki (`/`) public harita üzerinden vatandaşlara sunulan şeffaf istatistikler, `GET /v1/public/statistics` API ucundan beslenen bir widget aracılığıyla dinamik olarak gösterilecektir. Bu widget; **Aktif Çözülen Sorun Sayısı** (toplam çözülen raporlar), **Saha Çalışması Sürenler** (sahada müdahale edilen aktif işler), **Vatandaş Desteği (+1)** (vatandaşların toplam "+1 Beni de Etkiliyor" oyları) ve **Ortalama Çözüm Süresi** (hedef SLA sürelerine uyum oranı ve ortalama kapatma hızı) metriklerini şeffaf ve anlık olarak harita ile entegre bir şekilde sunacaktır.
+
+3) Erişilebilirlik (WCAG)
+- Ana sayfa (`/`) ve üzerindeki public harita + tüm modal'lar WCAG AA/AAA uyumlu olacak şekilde tasarlanacaktır (klavye navigasyonu, focus yönetimi, screen reader desteği).
+
+4) Fotoğraf Silme ve Public View Tutarlılığı (Modül G1)
+- Fotoğrafların otomatik silinme sürecinde arka planda şu adımlar garanti edilmelidir:
+  - `public_work_orders_view`'daki `photo_urls` güncellenir.
+  - İlgili tenant'ın `public_map_cache` tablosu transactional delete ile temizlenir.
+  - Harita istemcisine placeholder gösterilir.
+
+**Not:** Modal + Deep Linking stratejisi `yapı.md`'de "Modal + Deep Linking Stratejisi (Resmi Karar)" başlığı altında belgelenmiştir. Query parameter tabanlı yaklaşım (`?modal=...`) kabul edilmiştir.
+
+---
+