agent-enderun 1.0.3 → 1.0.4

package/docs/api-referans.md

@@ -0,0 +1,1137 @@
+# KENTİM — API / Endpoint Referans Belgesi (MVP Sürümü)
+
+> Bu belge, KENTİM platformunun MVP sürümüne ait tüm sayfa, işlem, iş akışı ve rollerden türetilmiş API referansıdır.
+
+**Base URL:** `https://api.kentim.com.tr` (tüm endpoint'ler `/v1` ön eki ile çağrılır)
+
+---
+
+## Genel Kurallar
+
+- **Auth:**
+  - JWT Bearer (vatandaş hesaplı + tüm belediye rolleri)
+  - Anonim (public endpoint'ler)
+  - API Key (IoT cihazları)
+  - HMAC-SHA256 (sistem heartbeat ve command loopback)
+- **Tenant İzolasyonu:** `x-tenant-id` header (proxy otomatik ekler) veya JWT içinden çözülür.
+- **Idempotency:** Tüm `POST` ve `PATCH` isteklerinde `x-idempotency-key: <UUIDv4>` zorunludur.
+- **Optimistic Locking:** Güncellemelerde `If-Match` veya `x-version` header kullanılır.
+- **UUIDv4:** Sistemdeki tüm kimlikler UUIDv4 formatındadır.
+- **Rate Limiting:**
+  - Public: IP başına 60 istek/dakika
+  - Anonim rapor: IP başına 2 rapor/dakika, 10 rapor/gün
+  - Vatandaş: 100 istek/15 dakika
+  - Belediye paneli: Kullanıcı başına 1000 istek/15 dakika
+- **Rate Limit Header'ları (Tüm Yanıtlarda):**
+  - `X-RateLimit-Limit`
+  - `X-RateLimit-Remaining`
+  - `X-RateLimit-Reset`
+
+---
+
+## Standart Yanıt Formatı ve Kuralları
+
+Tüm endpoint'ler aşağıdaki yapıyı kullanır:
+
+**Başarılı Yanıt (200/201):**
+```json
+{
+  "data": { ... },
+  "meta": {
+    "page": 1,
+    "limit": 20,
+    "total": 1240,
+    "has_more": true
+  }
+}
+```
+
+**Hata Yanıtı (4xx/5xx):**
+```json
+{
+  "error": {
+    "code": "WORK_ORDER_NOT_FOUND",
+    "message": "İş emri bulunamadı",
+    "details": "..." // opsiyonel
+  }
+}
+```
+
+**Desteklenen Query Parametreleri (Tüm Liste Endpoint'lerinde):**
+- `page`, `limit` (varsayılan 20, max 100)
+- `sort`, `order`
+- `search` (full-text)
+
+---
+
+## Hata Kodları Kataloğu
+
+| HTTP | Kod | Açıklama | Kullanıldığı Yerler |
+|------|-----|----------|---------------------|
+| 400 | INVALID_INPUT | Geçersiz parametre | Tüm formlar |
+| 401 | UNAUTHORIZED | Token geçersiz veya eksik | Tüm korumalı endpoint'ler |
+| 403 | FORBIDDEN | Yetki yok | RBAC ihlali |
+| 404 | NOT_FOUND | Kayıt bulunamadı | Tüm :id endpoint'leri |
+| 409 | CONFLICT | Versiyon çakışması | Optimistic locking |
+| 409 | DUPLICATE | Mükerrer işlem | Idempotency |
+| 409 | DISPUTE_EXISTS | Çevrimdışı çakışma havuzu uyuşmazlığı | Çevrimdışı senkronizasyon uyuşmazlığı |
+| 422 | UNPROCESSABLE | İş kuralı ihlali (geofence, SLA vb.) | Rapor, iş emri |
+| 422 | INTEGRATION_PARSER_CRASH | Custom parser sandbox çalışma hatası | IoT telemetri parser çökmesi |
+| 429 | RATE_LIMITED | Hız sınırı aşıldı | Tüm public ve vatandaş |
+| 422 | REOPEN_LIMIT_REACHED | Yeniden açma limiti (max 2) aşıldı | Reopen endpoint'leri |
+| 403 | REDISPATCH_INVALID_STATE | Moderator/müdür izinsiz aşamada re-dispatch denedi | Re-dispatch validasyonu (geçersiz durumdaki re-dispatch isteklerinde) |
+| 402 | PAYMENT_REQUIRED | Abonelik süresi doldu | Grace period dışında yazma işlemleri |
+| 403 | MUNICIPALITY_NOT_APPROVED | Belediyeniz henüz merkez tarafından onaylanmamıştır veya aboneliği askıdadır | Belediye Giriş Kilidi (SaaS Lockout) |
+
+---
+
+## 🟦 Vatandaş Web (Map-First + Modal Model)
+
+**Not:** Vatandaş arayüzünde ayrı `/map`, `/report/new`, `/announcements` gibi tam sayfalar kaldırılmıştır.  
+Ana sayfa (`/`) doğrudan public haritadır. Tüm diğer akışlar (rapor oluşturma, takip, duyurular, fikirler vb.) bu harita üzerinde **modal / drawer** olarak açılır.
+
+API endpoint’leri büyük ölçüde aynı kalır; sadece UI katmanında sayfa yerine modal kullanılır.
+
+| Akış | İşlem | Endpoint | Method | Yetkili Rol | Not |
+|------|-------|----------|--------|-------------|-----|
+| Ana Sayfa (`/`) Public Harita | Pinleri yükle | `GET /public/reports?municipality_id=&city_slug=&bbox=&status=&category=` | GET | Anonim | `municipality_id` veya `city_slug` zorunlu. `bbox` formatı: `minLon,minLat,maxLon,maxLat`. Fuzzing + KVKK maskeleme + zoom bazlı granülarite. |
+| Ana Sayfa | Pin detay + popup | `GET /public/reports/:public_id` | GET | Anonim | + yakın raporlar + support_count |
+| Ana Sayfa | "+1 Beni de Etkiliyor" | `POST /public/reports/:public_id/support` | POST | citizen (JWT) | `resolved` hariç |
+| Ana Sayfa | Desteği geri al | `DELETE /public/reports/:public_id/support` | DELETE | citizen (JWT) | `resolved` sonrası mümkün değil |
+| Rapor Oluşturma (Modal) | Yakın rapor kontrolü | `GET /public/reports/nearby?lat=&lng=&radius=100` | GET | Anonim | Harita üzerinde konum seçildiğinde dairesel mükerrer kontrolü |
+| Rapor Oluşturma (Modal) | Rapor gönder | `POST /reports` | POST | Anonim / citizen | reCAPTCHA + rate limit + opsiyonel `parent_reopened_work_order_id` |
+| Rapor Takip (Modal) | Durum sorgula | `GET /reports/track/:trackingCode` | GET | Anonim | Format: `KENT-[plaka]-[rastgele_alfanumerik_8_hane]` |
+| Rapor Takip (Modal) | Geri bildirim | `POST /reports/:id/feedback` | POST | Anonim (x-tracking-code) / citizen | Sadece `resolved` durumunda |
+| Rapor Takip (Modal) | Yeniden aç (Hesaplı/Token) | `PATCH /reports/:id/reopen` | PATCH | citizen | Max 2 kez; "neden" zorunlu |
+| Rapor Takip (Modal) | Yeniden aç (Anonim/Takip Kodlu) | `POST /public/reports/reopen` | POST | Anonim | Body: `{ tracking_code, reason, captcha_token }` (Max 2 kez; captcha + rate limit korumasıyla). **Rate Limit:** IP başına 3 istek/saat, tracking_code başına günde 5 deneme. DB seviyesinde `reopen_count >= 2` kontrolü: aşılırsa `422 REOPEN_LIMIT_REACHED` döner. |
+| Duyurular (Modal) | Liste | `GET /announcements?district=&type=&page=` | GET | Anonim | UI: `/?modal=announcements` |
+| Duyurular (Modal) | Detay | `GET /announcements/:id` | GET | Anonim | UI: `/?modal=announcement&id=:id` |
+| Fikirler (Modal) | Liste | `GET /ideas?sort=&status=&category=&page=` | GET | Anonim | UI: `/?modal=ideas` |
+| Fikirler (Modal) | Detay | `GET /ideas/:id` | GET | Anonim | UI: `/?modal=idea&id=:id` |
+| Fikirler (Modal) | Oy (+1/-1) | `POST /ideas/:id/vote` | POST | citizen (JWT + E-posta onaylı hesap) | **TC Kimlik doğrulaması oy için gerekmez;** yalnızca e-posta onayı yeterli. JWT'de `email_verified: true` claim'i doğrulanır. |
+| Fikirler (Modal) | Oluştur | `POST /ideas` | POST | citizen (JWT + T.C. Kimlik doğrulanmış + E-posta onaylı hesap) | JWT'de `is_identity_verified: true` claim'i ve e-posta onayı doğrulanır. UI: `/?modal=idea-new`. Moderasyon bekler. |
+| Geri Dönüşüm | Noktalar | `GET /recycling-points?type=&lat=&lng=` | GET | Anonim | Ana harita katmanı veya modal |
+| Panik Butonu | Konum gönder | `POST /emergency/panic` | POST | Anonim | Geofencing muaf |
+| Dashboard (Modal) | Raporlarım | `GET /citizen/reports?status=&page=` | GET | citizen (JWT) | UI: `/?modal=dashboard&tab=reports` |
+| Dashboard (Modal) | Oy geçmişim | `GET /citizen/votes` | GET | citizen (JWT) | UI: `/?modal=dashboard&tab=votes` |
+| Dashboard (Modal) | Desteklediklerim | `GET /citizen/support-votes` | GET | citizen (JWT) | UI: `/?modal=dashboard&tab=supported` |
+| Profil (Modal) | Güncelle | `PATCH /citizen/profile` | PATCH | citizen (JWT) | E-posta OTP doğrulamalı (SMS kullanılmaz). UI: `/?modal=profile` |
+| Profil (Modal) | Hesap sil | `DELETE /citizen/account` | DELETE | citizen (JWT) | İstek `202 Accepted` ile yanıtlanır ve bir `task_id` döner. İşlem durumu `GET /citizen/tasks/:task_id` ile sorgulanabilir. |
+| Profil (Modal) | Asenkron işlem durumu | `GET /citizen/tasks/:task_id` | GET | citizen (JWT) | Hesap silme gibi uzun süren asenkron işlemlerin durumunu sorgular. Yanıt şeması: `{ "data": { "task_id": "uuid", "status": "pending\|processing\|completed\|failed", "created_at": "ISO8601", "completed_at": "ISO8601 \| null", "error": "string \| null" } }` |
+| Profil (Modal) | Bildirim tercihleri | `PATCH /citizen/notification-preferences` | PATCH | citizen (JWT) | — |
+| Ana Sayfa | İstatistik widget | `GET /public/statistics` | GET | Anonim | Dönen veri yapısı için detaylı JSON şeması döküman sonundadır |
+| Afet modu | Tahliye rotası | `GET /evacuation-routes?lat=&lng=` | GET | Anonim | Yalnızca afet modunda aktif; normal modda boş liste döner |
+| Auth | Kayıt / Giriş / OTP / Şifre sıfırlama | `POST /auth/*` | POST | — | KVKK onayı zorunlu. OTP: 3 yanlış denemede 15 dk kilitlenir. |
+| Auth | TC Kimlik Doğrulama | `POST /auth/tc-kimlik/verify` | POST | citizen (JWT) | **Fikir oluşturmak** için zorunlu resmi doğrulama (oy vermek için gerekmez). Displays adı korunur. **İstek Gövdesi:** `{ "tckn": "string(11)", "ad": "string", "soyad": "string", "dogum_yili": "number" }`. **Başarılı Yanıt (200):** `{ "data": { "is_identity_verified": true, "verified_at": "ISO8601" } }`. **Hata (422):** `{ "error": { "code": "IDENTITY_VERIFICATION_FAILED", "message": "Kimlik doğrulanamadı" } }`. NVI timeout: 10 sn; başarısızlıkta max 2 otomatik retry sonra `503` döner. |
+| Auth | Token yenile | `POST /auth/refresh` | POST | citizen (JWT) | **Refresh Token Rotation:** Her yenileme işleminde eski refresh token geçersiz kılınır ve yeni bir refresh token üretilir (tek kullanımlık rotasyon). "Beni hatırla" ile 30 güne uzayan token çalındığında ikinci kullanımda otomatik geçersiz olur. |
+| Auth | Çıkış / Oturumlar | `/auth/logout`, `/sessions` | ... | citizen (JWT) | — |
+| Auth | Tüm oturumlardan çık | `DELETE /sessions/all` | DELETE | citizen (JWT) | Tüm aktif cihaz oturumlarını sonlandırır; tüm refresh token'lar geçersiz kılınır. |
+
+
+**Statik ve Bilgilendirici İçerikler (Modal Üzerinden)**
+| Akış | İşlem | Endpoint | Method | Yetkili Rol | Not |
+|------|-------|----------|--------|-------------|-----|
+| Statik İçerik | İçerik getir | `GET /public/static-contents/:key` | GET | Anonim | `:key` = `about`, `faq`, `privacy`, `kvkk`, `terms`, `contact`. UI: `/?modal=[key]` |
+
+**Not:** Bu içerikler artık `central_static_contents` tablosundan dinamik olarak çekilir ve merkezi SaaS panelinden yönetilir. API, `:key` parametresine göre ilgili içeriği döndürür.
+
+---
+
+## 🟨 Belediye Paneli
+
+### Moderatör
+
+| İşlem | Endpoint | Method | Yetkili Rol | Kısıt / Not |
+|-------|----------|--------|-------------|-------------|
+| Kuyruk listesi | `GET /work-orders?status=moderation,pending,reopened,chronic_archived&is_public_visible=true|false&...` | GET | muni_moderator, muni_admin | Kendi tenant |
+| Rapor detay | `GET /work-orders/:id` | GET | muni_moderator, muni_admin | — |
+| Müdürlüğe yönlendir | `PATCH /work-orders/:id/dispatch` | PATCH | muni_moderator, muni_admin | — |
+| Reddet | `PATCH /work-orders/:id/reject` | PATCH | muni_moderator, muni_admin | Gerekçe zorunlu |
+| Mükerrer işaretle | `PATCH /work-orders/:id/mark-duplicate` | PATCH | muni_moderator, muni_admin | Ana iş emri bağlantısı |
+| Re-dispatch | `PATCH /work-orders/:id/redispatch` | PATCH | muni_moderator, muni_admin | **Sadece dispatched_to_department aşamasında**; moderatör kullanırsa sayaç artmaz, hatalı aşamada `403` döner |
+| Public görünürlük değiştir | `PATCH /work-orders/:id/public-visibility` | PATCH | muni_moderator, muni_admin | Gerekçe zorunlu |
+| Fotoğraf görünürlük | `PATCH /work-orders/:id/photos/:photo_id/visibility` | PATCH | muni_moderator, muni_admin | — |
+| Dahili not ekle | `POST /work-orders/:id/notes` | POST | muni_moderator, muni_admin | 15 dakika içinde düzenlenebilir |
+| Manuel iş emri oluştur | `POST /work-orders` | POST | muni_moderator, muni_admin | `manual_internal` kaynak tipi. **Moderatör için:** Sadece sistemsel/acil takip ihtiyacı durumunda + zorunlu gerekçe + detaylı audit log. Kötüye kullanım riski nedeniyle muni_admin tarafından devre dışı bırakılabilir. |
+
+### Müdür
+
+| İşlem | Endpoint | Method | Yetkili Rol | Not |
+|-------|----------|--------|-------------|-----|
+| İş listesi (birincil) | `GET /work-orders?department_id=me&is_public_visible=true|false&...` | GET | muni_department_manager, muni_admin | — |
+| İş listesi (ikincil bildirimler) | `GET /work-orders?secondary_department_id=me` | GET | muni_department_manager, muni_admin | Salt-okunur |
+| Detay | `GET /work-orders/:id` | GET | muni_department_manager, muni_admin | Kendi müdürlüğü |
+| Şefe ata | `PATCH /work-orders/:id/assign-team` | PATCH | muni_department_manager, muni_admin | — |
+| Personele doğrudan ata | `PATCH /work-orders/:id/assign-worker` | PATCH | muni_department_manager, muni_admin | Onay yetkisi müdüre döner |
+| Force approve (şef onayı bypass) | `PATCH /work-orders/:id/force-approve` | PATCH | muni_department_manager, muni_admin | `pending_chief_approval` durumundayken doğrudan `resolved` yapar (şef bypass edilir). |
+| Zorla kapat | `PATCH /work-orders/:id/force-resolve` | PATCH | muni_department_manager, muni_admin | `pending_manager_review` → `resolved`. **Kullanım farkı:** Bu endpoint "yönetici bypass" işlemidir; şefin onayını beklemeden, herhangi bir `pending_manager_review` işi zorla çözüldüğü yapılır. Circuit breaker devreye girdikten sonra müdürün bu kanalı kullanması en yaygın senaryo olmakla birlikte, geçerli bir neden varsa (acil kapanış gibi) diğer durullarda da kullanılabilir. |
+| Personel değiştir | `PATCH /work-orders/:id/reassign-worker` | PATCH | muni_department_manager, muni_admin | Ret sayacı sıfırlanır, `is_manager_bypassed` sıfırlanır (false yapılır), iş şefin ekibinin atanmamış havuzuna (`assigned_to_team`) gönderilir. |
+| Manuel onayla | `PATCH /work-orders/:id/manual-approval` | PATCH | muni_department_manager, muni_admin | `pending_manager_review` → `resolved`. **Kullanım farkı:** Bu endpoint "eksik belgeyi kabul ederek onay" işlemidir; özellikle QA döngüsü sonrasında veya saha personelinin tamamlama kanıtları eksik kalmışken müdürün sorumluluğunu üstlenip el ile onay verdiğini ifade eder. Denetim loguyla birlikte **"Eksik kanıt kabulü"** işareti yazılır. Sonuç `force_resolve` ile aynıdır (`resolved`) ancak denetim izinden ayırt edilebilir. |
+| İptal et | `PATCH /work-orders/:id/reject` | PATCH | muni_department_manager, muni_admin | Gerekçe zorunlu |
+| Re-dispatch | `PATCH /work-orders/:id/redispatch` | PATCH | muni_department_manager, muni_admin | Sayaç artar (ping-pong koruması) |
+| Dahili not ekle | `POST /work-orders/:id/notes` | POST | muni_department_manager, muni_admin | — |
+| Manuel iş emri oluştur | `POST /work-orders` | POST | muni_department_manager, muni_admin | — |
+| Periyodik şablonlar (kendi müdürlüğü) | `GET/POST/PATCH /schedule/templates?department_id=me` | GET/POST/PATCH | muni_department_manager, muni_admin | Sadece kendi müdürlüğü |
+| Periyodik şablon manuel tetikle | `POST /schedule/templates/:id/trigger` | POST | muni_department_manager, muni_admin | Şablonu anında manuel olarak çalıştırır ve iş emrini üretir |
+| Periyodik şablon çalışma geçmişi | `GET /schedule/templates/:id/runs` | GET | muni_department_manager, muni_admin | Şablonun geçmiş otomatik/manuel çalışma geçmişi ve loglarını döner |
+
+### Ekip Şefi
+
+| İşlem | Endpoint | Method | Yetkili Rol | Not |
+|-------|----------|--------|-------------|-----|
+| İş listesi | `GET /work-orders?team_id=me&status=` | GET | muni_team_chief, muni_admin | Kendi ekibi |
+| Detay | `GET /work-orders/:id` | GET | muni_team_chief, muni_admin | — |
+| Personele ata | `PATCH /work-orders/:id/assign-worker` | PATCH | muni_team_chief, muni_admin | Kendi ekibi personeli |
+| Fotoğraf onayla | `PATCH /work-orders/:id/approve-photos` | PATCH | muni_team_chief, muni_admin | `resolved` |
+| Geofence bypass onayla/reddet | `PATCH /work-orders/:id/geofence-bypass` | PATCH | muni_team_chief, muni_admin | Sapma onaylanırsa koordinat EXIF ile güncellenir |
+| Fotoğraf reddet | `PATCH /work-orders/:id/reject-photos` | PATCH | muni_team_chief, muni_admin | 3+ ret → circuit breaker |
+| QA onay | `PATCH /work-orders/:id/qa-confirm` | PATCH | muni_team_chief, muni_admin | — |
+| QA işe döndür | `PATCH /work-orders/:id/qa-reopen` | PATCH | muni_team_chief, muni_admin | — |
+| Dahili not ekle | `POST /work-orders/:id/notes` | POST | muni_team_chief, muni_admin | 15 dakika içinde düzenlenebilir |
+| Manuel iş emri | `POST /work-orders` | POST | muni_team_chief, muni_admin | Müdürlük havuzuna düşer. **Not:** Şefin kendi oluşturduğu işe doğrudan personel ataması durumunda onay yetkisi şefe kalır (bkz. proje.md F6.1). |
+| Günlük plan | `GET /daily-plan?team_id=me&date=` | GET | muni_team_chief, muni_admin | — |
+| Plan sırası kaydet | `PATCH /daily-plan/reorder` | PATCH | muni_team_chief, muni_admin | — |
+| Rota optimizasyonu | `POST /route-optimize` | POST | muni_team_chief, muni_admin | OSRM |
+| Ekip performans istatistikleri | `GET /analytics?team_id=me&tab=personnel` | GET | muni_team_chief, muni_admin | — |
+| Uyuşmazlık listesi | `GET /chief/disputes?status=&page=` | GET | muni_team_chief, muni_admin | Çevrimdışı senkronizasyon uyuşmazlıkları listesi |
+| Uyuşmazlık detay | `GET /chief/disputes/:id` | GET | muni_team_chief, muni_admin | `dispute_logs` ve ilgili iş detayları |
+| Uyuşmazlık onayla/reddet | `PATCH /chief/disputes/:id/approve` veya `/reject` | PATCH | muni_team_chief, muni_admin | Çift hak ediş varsa `approved_override` otomatik olarak tetiklenir |
+
+### Saha Personeli
+
+| İşlem | Endpoint | Method | Yetkili Rol | Not |
+|-------|----------|--------|-------------|-----|
+| Görev listesi | `GET /worker/tasks?status=` | GET | muni_worker, muni_admin | Kendine atanan işler |
+| Detay | `GET /worker/tasks/:id` | GET | muni_worker, muni_admin | — |
+| İşi başlat | `PATCH /worker/tasks/:id/start` | PATCH | muni_worker, muni_admin | `in_progress` |
+| Fotoğraf yükle | `POST /worker/tasks/:id/photos` | POST | muni_worker, muni_admin | GPS + exif damgalı; 50m geofence kontrolü |
+| İşi tamamla | `PATCH /worker/tasks/:id/complete` | PATCH | muni_worker, muni_admin | 50m geofence zorunlu |
+| Geofence bypass talebi | `POST /worker/tasks/:id/geofence-bypass` | POST | muni_worker, muni_admin | EXIF fotoğraf ve gerekçeyle talep oluşturma |
+| Yarıda bırak | `PATCH /worker/tasks/:id/abandon` | PATCH | muni_worker, muni_admin | Normal atamada şef havuzuna (`assigned_to_team`) döner. Müdür bypass atamasında ise doğrudan müdür havuzuna (`dispatched_to_department`) iade edilir ve `is_manager_bypassed = true` flag'i korunur. |
+| Not ekle | `POST /worker/tasks/:id/notes` | POST | muni_worker, muni_admin | — |
+| Vardiya başlat | `POST /worker/shift/start` | POST | muni_worker, muni_admin | Background GPS aktifleşir |
+| Vardiya kapat | `POST /worker/shift/close` | POST | muni_worker, muni_admin | `in_progress` işler şefe devredilir |
+| GPS konum güncelle | `POST /worker/location` | POST | muni_worker, muni_admin | Arka plan, vardiya açıkken çalışır. Vardiya kapalıyken gönderilen güncellemelerde sunucu `204 No Content` döner ve işlem yapmaz. |
+
+### Belediye Admin (Tüm alt rollerin yetkileri + ek yetkiler)
+
+> **Yetki Notu:** muni_admin, kendi belediyesindeki tüm rollerin (moderatör, müdür, şef, personel) yetkilerini kapsar. Aşağıda sadece **ek yetkileri** listelenmiştir. RBAC middleware her kaynakta hem rol hem de veri izolasyonu (kendi müdürlük/ekip kısıtları) kontrolü yapar.
+
+| İşlem | Endpoint | Method | Yetkili Rol | Not |
+|-------|----------|--------|-------------|-----|
+| Admin dashboard | `GET /admin/dashboard` | GET | muni_admin | — |
+| Public harita metrikleri | `GET /admin/public-map-stats` | GET | muni_admin | — |
+| En çok desteklenen işler | `GET /admin/top-supported-work-orders` | GET | muni_admin | — |
+| Müdürlük işlemleri | `GET/POST/PATCH /departments` | GET/POST/PATCH | muni_admin | — |
+| Müdürlük pasif et | `PATCH /departments/:id/deactivate` | PATCH | muni_admin | — |
+| Ekip işlemleri | `GET/POST/PATCH /teams` | GET/POST/PATCH | muni_admin | — |
+| Personel davet et | `POST /users/invite` | POST | muni_admin | — |
+| Personel pasif et | `PATCH /users/:id/deactivate` | PATCH | muni_admin | — |
+| Personel profil güncelle | `PATCH /users/:id` | PATCH | muni_admin | — |
+| Kategori işlemleri | `GET/POST/PATCH/DELETE /categories` | GET/POST/PATCH/DELETE | muni_admin | Aktif iş yoksa silinebilir. Silme işlemi denetim loguna kaydedilir. |
+| Yönlendirme kuralları listesi | `GET /routing-rules` | GET | muni_admin | Kategori bazlı: her kategori için birincil müdürlük + ikincil bildirim müdürlükleri listesi |
+| Yönlendirme kuralı güncelle | `PUT /routing-rules/:category_id` | PUT | muni_admin | Body: `{ "primary_department_id": "uuid", "secondary_department_ids": ["uuid", ...] }` |
+| Yönlendirme kuralları toplu güncelle | `POST /routing-rules/bulk` | POST | muni_admin | CSV yükleme (kategori_kodu, primary_dept_code, secondary_dept_codes). Değişiklikler toplu audit log ile kaydedilir. |
+| Yönlendirme kuralı sil | `DELETE /routing-rules/:category_id` | DELETE | muni_admin | Kategori varsayılan sisteme döner (eğer varsa). |
+| Periyodik şablon listesi | `GET /schedule/templates?department_id=` | GET | muni_admin, muni_department_manager | muni_department_manager sadece kendi müdürlüğünü görebilir |
+| Periyodik şablon oluştur | `POST /schedule/templates` | POST | muni_admin, muni_department_manager | Body: şablon adı, kategori, öncelik, cron/ tekrar sıklığı, varsayılan ekip, başlangıç/bitiş tarihi, `default_public` |
+| Periyodik şablon güncelle | `PATCH /schedule/templates/:id` | PATCH | muni_admin, muni_department_manager | Kendi müdürlüğüne ait şablonları güncelleyebilir |
+| Periyodik şablon pasif et | `PATCH /schedule/templates/:id/deactivate` | PATCH | muni_admin, muni_department_manager | Gelecek tetiklemeler durur, geçmiş işler korunur |
+| Şablon manuel tetikle | `POST /schedule/templates/:id/trigger` | POST | muni_admin, muni_department_manager | Anında iş emri üretir (çakışma kontrolü ile) |
+| Şablon çalışma geçmişi | `GET /schedule/templates/:id/runs` | GET | muni_admin, muni_department_manager | Bu şablondan üretilmiş iş emirlerinin listesi ve durumu |
+| Entegrasyon listesi | `GET /integrations` | GET | muni_admin | Hedef müdürlük, tür, durum, son istek bilgileriyle birlikte |
+| Entegrasyon oluştur / güncelle | `POST /integrations` ve `PATCH /integrations/:id` | POST/PATCH | muni_admin | Body: `name`, `department_id`, `type` (`generic_webhook` | `custom_iot_sensor`), `mapping_rules` (JSON), `parser_script` (JS - sadece custom için), `default_public` (boolean - zorunlu), `description`, `is_active` |
+| Entegrasyon sil / pasif et | `PATCH /integrations/:id/deactivate` | PATCH | muni_admin | Fiziksel silme yasaktır. Pasif yapıldığında telemetri reddedilir. |
+| IoT cihaz envanteri | `GET /integrations/devices` | GET | muni_admin | Cihaz listesi + doluluk, batarya, sağlık durumu + harita pinleri için veri |
+| Cihaz bakım moduna alma | `PATCH /integrations/devices/:device_id/maintenance` | PATCH | muni_admin | Cool-down / spam koruması için manuel bakım modu |
+| Cihazı arşivle | `PATCH /integrations/devices/:device_id/archive` | PATCH | muni_admin | Cihaz fiziksel olarak kaldırıldığında kullanılır |
+| Entegrasyon hata logları | `GET /integrations/logs?integration_id=&event_type=` | GET | muni_admin | `integration_logs` tablosu (FAILED, OUT_OF_BOUNDS, PARSER_CRASH vb.) |
+| Telemetri logları | `GET /integrations/:id/telemetry-logs` | GET | muni_admin | Cihaza özel ham + parse edilmiş telemetri geçmişi |
+| Sensör spam koruması & cooldown | `PATCH /integrations/sensors/:id/maintenance` | PATCH | muni_admin | Otomatik veya manuel "suspicious" moduna alma |
+| Duyuru işlemleri | `GET/POST/PATCH/DELETE /announcements` | GET/POST/PATCH/DELETE | muni_admin | **Not:** Duyuruları görüntüleme (GET): tüm belediye rolleri; oluşturma/düzenleme/silme: yalnızca muni_admin. |
+| Fikir yönetimi | `GET/PATCH/POST /ideas/manage` | GET/PATCH/POST | muni_admin | Fikir listeleme, düzenleme, yanıtlama |
+| Fikir reddi | `PATCH /ideas/manage/:id/reject` | PATCH | muni_admin | Gerekçe zorunlu; vatandaşa bildirim gönderilmez (F14 kararı). |
+| Analitik (tüm tenant) | `GET /analytics?tab=&from=&to=&department_id=&is_public_visible=true|false` | GET | muni_admin | Performans, SLA, destek sayıları bazlı raporlar (Read Replica üzerinden) |
+| Denetim logları | `GET /audit-logs?...` | GET | muni_admin | JSONB diff viewer destekli, CSV dışa aktarım desteklenir |
+| KVKK talepleri listele | `GET /gdpr/requests` | GET | muni_admin | status filtresi desteklenir |
+| KVKK talebini işlemeye başla | `PATCH /gdpr/requests/:id/process` | PATCH | muni_admin | İndeksli `citizen_id` kolonu üzerinden asenkron regex maskelemeyi başlatır |
+| KVKK talebini tamamla | `PATCH /gdpr/requests/:id/complete` | PATCH | muni_admin | Talep durumunu `completed` ve `anonymized_at` olarak günceller |
+| Belediye ayarları | `GET/PATCH /settings` | ... | muni_admin | Public harita, geofence, SLA |
+| Statik noktalar | `GET/POST/PATCH/DELETE /static-points` | ... | muni_admin | Geri dönüşüm + tahliye |
+| Kriz masası | `GET /emergency/panic-signals` | GET | muni_admin | — |
+| Panik sinyal toplu kapat | `PATCH /emergency/panic-signals/bulk-close` | PATCH | muni_admin | — |
+| Anlaşmazlık kuyruğu | `GET /admin/disputes` | GET | muni_admin | — |
+| Kesin atama | `PATCH /work-orders/:id/force-assign` | PATCH | muni_admin | Sadece disputes kuyruğundan. İş emrine `is_force_assigned = true` flag'i yazılır; bu flag aktifken müdürler re-dispatch yapamaz, yalnızca `muni_admin` müdâhale edebilir. Re-dispatch sayıcı sıfırlanır. |
+| 2FA ayarları | `GET/POST/DELETE /auth/2fa` | GET/POST/DELETE | muni_admin | TOTP kurulum, doğrulama ve devre dışı bırakma (zorunlu tutulabilir) |
+
+---
+
+## 🟥 Central Panel
+
+| İşlem | Endpoint | Method | Yetkili Rol | Not |
+|-------|----------|--------|-------------|-----|
+| Dashboard | `GET /central/dashboard` | GET | central_admin, central_moderator | central_moderator: sadece aggregate metrik + SLA riskli belediye listesi + heartbeat uyarıları (bireysel veri yok) |
+| Belediye listesi (aggregate) | `GET /central/municipalities?...` | GET | central_admin, central_moderator | central_moderator sadece özet alanları (ad, il, status, sla_compliance, active_work_count) görür |
+| Belediye ekle | `POST /central/municipalities` | POST | central_admin | — |
+| Belediye güncelle / pasif / abonelik / key yenile | `PATCH/POST /central/municipalities/:id/...` | ... | central_admin | — |
+| **IoT API Key Rotasyonu** | `POST /central/municipalities/:id/api-key/rotate` | POST | central_admin | Acil key sızıntısı durumunda: eski key anında geçersiz kılınır, yeni key üretilip şifreli kanal üzerinden belediye adminine iletilir. İşlem `API_KEY_ROTATED` denetim loguyla kaydedilir. |
+| Global kategoriler | `GET/POST/PATCH /central/categories` | ... | central_admin | central_moderator salt-okunur |
+| Lokasyon sorgulama hiyerarşisi | `GET /central/locations/hierarchy` | GET | Anonim / Herkes | Dropdown verileri için coğrafi hiyerarşi sorgulama (il/ilçe dropdown'larını besler) |
+| Lokasyon işlemleri | `GET/POST/PATCH/DELETE /central/locations` | ... | central_admin | — |
+| Lokasyon CSV import | `POST /central/locations/import` | POST | central_admin | — |
+| Lokasyon CSV export | `GET /central/locations/export` | GET | central_admin | — |
+| Sistem sağlığı | `GET /central/system-health` | GET | central_admin, central_moderator | central_moderator sadece izleme + uyarı listesi (test tetikleme yok) |
+| Global raporlar | `GET /central/reports?tab=statistics\|heatmap\|comparison&...` | GET | central_admin, central_moderator | central_moderator sadece görüntüleme + CSV/JSON export (hiçbir filtrede vatandaş/iş detayı dönmez) |
+| Afet modu | `POST/DELETE /central/disaster-mode` | ... | central_admin | Şifre onayı zorunlu |
+| Kullanıcı işlemleri | `GET/POST/PATCH /central/users` | ... | central_admin | — |
+| Denetim logları | `GET /central/audit-logs?...` | GET | central_admin | central_moderator erişemez (güvenlik nedeniyle) |
+| Statik içerik güncelle | `PUT /central/static-contents/:key` | PUT | central_admin | `:key` = `about`, `faq`, etc. |
+| Kendi profil | `GET/PATCH /central/profile/security` | ... | central_admin, central_moderator | — |
+| **Public Web Yol Haritası - MVP içeriğini getir/güncelle** | `GET/PUT /central/public-web-roadmap/mvp` | GET/PUT | central_admin | **Request (PUT):** `{ "title": "string(5-120)", "subtitle": "string(max 200)", "content": "string(min 50, max 20000)", "published_at": "ISO8601 (optional)", "is_active": "boolean" }` <br> **Response:** Güncellenmiş içerik + `updated_at` |
+| **Public Web Yol Haritası - V1 içeriğini getir/güncelle** | `GET/PUT /central/public-web-roadmap/v1` | GET/PUT | central_admin | Aynı şema (MVP ile birebir aynı yapı) |
+| Public Web Yol Haritası yayın durumu değiştir | `PATCH /central/public-web-roadmap/:version/toggle` | PATCH | central_admin | **Request:** `{ "is_active": boolean }` <br> **Business Rule:** Her iki sürüm de pasif yapılamaz (409 Conflict döner) |
+| Public Web Yol Haritası önizleme linki üret | `POST /central/public-web-roadmap/:version/preview` | POST | central_admin | **Response:** `{ "preview_url": "string", "expires_at": "ISO8601" }` (24 saat geçerli tek kullanımlık link) |
+
+---
+
+## 🔧 Sistem İç Entegrasyon (Belediye ↔ Central)
+
+| Yön | İşlem | Endpoint | Method | Auth | Açıklama |
+|-----|-------|----------|--------|------|----------|
+| IoT → Belediye | Telemetri gönder | `POST /integrations/iot/telemetry` | POST | API Key | V8 sandbox parse, RLS tenant izolasyonu |
+| Belediye → Central | Heartbeat gönder | `POST /v1/central/heartbeat` | POST | HMAC-SHA256 | 1 dakikada bir |
+| Belediye → Central | İstatistik push | `POST /central/municipalities/stats` | POST | HMAC-SHA256 | 15 dakikada bir; anonim |
+| Central → Belediye | Afet komutu | `POST /command-loopback` | POST | HMAC-SHA256 | `x-kentim-signature` zorunlu |
+
+---
+
+## 🔔 Bildirim Endpoint'leri
+
+| İşlem | Endpoint | Method | Yetkili Rol |
+|-------|----------|--------|-------------|
+| Bildirim listesi (son 20) | `GET /notifications?page=` | GET | Tüm belediye rolleri |
+| Tek bildirimi okundu yap | `PATCH /notifications/:id/read` | PATCH | Kendi bildirimi |
+| Tümünü okundu yap | `PATCH /notifications/read-all` | PATCH | Kendi bildirimleri |
+
+---
+
+---
+
+## 🔐 Kimlik Doğrulama ve Güvenlik (Genişletilmiş)
+
+| İşlem | Endpoint | Method | Yetkili Rol | Not |
+|-------|----------|--------|-------------|-----|
+| 2FA kurulum (QR kod) | `GET /auth/2fa/setup` | GET | muni_admin, central_admin | — |
+| 2FA doğrula ve aktifleştir | `POST /auth/2fa/verify` | POST | muni_admin, central_admin | TOTP kodu |
+| 2FA kapat | `DELETE /auth/2fa/disable` | DELETE | muni_admin, central_admin | Yedek kod veya şifre ile |
+| Aktif oturumlar listesi | `GET /sessions` | GET | Tüm belediye rolleri | — |
+| Tüm oturumlardan çıkış | `DELETE /sessions/all` | DELETE | Tüm belediye rolleri | Tüm refresh token'lar geçersiz kılınır |
+| Profil / güvenlik (belediye) | `GET /profile/security` | GET | Tüm belediye rolleri | — |
+| Profil / güvenlik güncelle | `PATCH /profile/security` | PATCH | Tüm belediye rolleri | Şifre + 2FA + e-posta |
+
+**Not — 2FA Kapsamı:** 2FA zorunluluğu `muni_admin` ve `central_admin` için zorunludur. Diğer roller (`muni_moderator`, `muni_department_manager`, `muni_team_chief`, `muni_worker`) için isteğe bağlıdır; belediye adminı panel ayarlarından tüm belediye rolleri için 2FA zorunluluğunu aktif edebilir.
+
+
+
+---
+
+## 📡 Gerçek Zamanlı İletişim (WebSocket / SSE)
+
+**Bağlantı ve Kimlik Doğrulama**
+- **Resmi Karar — Handshake-After-Connect Kullanılır:** KENTİM WebSocket istemcilerinde JWT token URL query param'da taşınmaz. Bağlantı kurulduktan hemen sonra ilk WebSocket frame'inde `{ "type": "auth", "token": "<JWT>", "tenant_id": "<TENANT_ID>" }` mesajı gönderilir. Sunucu bu frame'i aldıktan sonra abonelik işlemlerini başlatır; auth frame gönderilmeden yapılan kanal aboneliğ istekleri `4401 Unauthorized` kodu ile kapatılır.
+- **Gerekçe:** JWT'nin URL query param'da taşınması server/proxy loglarına ve tarayıcı geçmişine sızabilir; handshake-after-connect bu riski tam olarak ortadan kaldırır.
+- **Legacy Uyumluluk Notu:** Eski istemciler geçiş süresi boyunca `wss://api.kentim.com.tr/v1/ws?token=<JWT>&tenant_id=<TENANT_ID>` URL param yöntemini kullanabilir; ancak yeni tüm istemci implementasyonlarında handshake-after-connect zorunludur.
+- Protokol: WebSocket (tercih) veya SSE (fallback)
+- Reconnect: Otomatik (exponential backoff)
+- Heartbeat: Her 30 saniyede bir ping/pong
+
+**Abone Olunacak Kanallar (Belediye Paneli)**
+- `work-orders.{tenant_id}` → Tüm iş emri güncellemeleri
+- `notifications.{user_id}` → Kullanıcıya özel bildirimler
+- `panic.{tenant_id}` → Kriz masası panik sinyalleri (sadece muni_admin ve kriz masası rolü)
+
+**Event Örnekleri ve Payload Şemaları**
+
+```json
+// work-orders.{tenant_id}
+{
+  "event": "work-order.updated",
+  "data": {
+    "id": "uuid",
+    "status": "in_progress",
+    "assigned_worker_id": "uuid",
+    "updated_at": "2026-05-24T11:30:00Z"
+  }
+}
+
+// notifications.{user_id}
+{
+  "event": "notification.new",
+  "data": {
+    "id": "uuid",
+    "title": "Yeni iş atandı",
+    "body": "...",
+    "type": "work_order_assigned",
+    "created_at": "..."
+  }
+}
+
+// panic.{tenant_id}
+{
+  "event": "panic.new",
+  "data": {
+    "id": "uuid",
+    "citizen_location": { "lat": 41.0, "lng": 29.0 },
+    "created_at": "..."
+  }
+}
+```
+
+**Central Panel:**
+- Gerçek zamanlı kullanılmaz. 60 saniyede bir polling yapılır (`GET /central/system-health` ve ilgili rapor endpoint'leri).
+
+**Mobile (Saha Personeli):**
+- Push Notification (FCM / APNs) kullanılır.
+- Token kayıt: `POST /devices` (aşağıda).
+
+---
+
+## 📱 Mobile Push Token ve Cihaz Yönetimi
+
+| İşlem | Endpoint | Method | Yetkili Rol | Not |
+|-------|----------|--------|-------------|-----|
+| Cihaz / push token kaydet | `POST /devices` | POST | muni_worker, muni_team_chief, citizen | FCM/APNs token + platform + device_id |
+| Cihazı sil | `DELETE /devices/:device_id` | DELETE | muni_worker, muni_team_chief, citizen | — |
+| Bildirim tercihleri | `PATCH /citizen/notification-preferences` | PATCH | citizen | Web + mobile push |
+
+---
+
+## 📁 Dosya ve Medya Yönetimi
+
+**Fotoğraf Yükleme Kuralları**
+- Endpoint: `POST /worker/tasks/:id/photos`
+- Yöntem: `multipart/form-data` (tercih edilen) veya Base64 (opsiyonel, küçük dosyalar için)
+- Maksimum dosya sayısı: **5 fotoğraf** / iş emri
+- Maksimum dosya boyutu: **5 MB** / dosya
+- Desteklenen formatlar: JPG, PNG, WEBP
+- Zorunlu meta veriler (sunucu tarafında doğrulanır):
+  - GPS koordinatı (EXIF)
+  - Çekim zamanı (EXIF)
+  - 50 metre geofence kontrolü (tamamlama sırasında)
+
+**Yükleme Sonrası Davranış**
+- Fotoğraf yüklendikten sonra `photo_urls` ve `is_public_visible` alanları güncellenir.
+- Her fotoğraf için bağımsız `is_public_visible` kontrolü yapılabilir (moderatör/admin).
+
+**Fotoğraf Silme ve Otomatik Temizlik**
+- Fiziksel silme: İş emri `resolved` veya `rejected` olduktan **1 yıl** sonra otomatik yapılır.
+- **Arka Plan İşlemleri (Çözüldü):**
+  1. `public_work_orders_view` içindeki `photo_urls` güncellenir.
+  2. İlgili tenant'ın `public_map_cache` tablosu temizlenir.
+  3. CDN URL'leri invalidate edilir.
+- **Mevcut Durum:** Yukarıdaki cache invalidation ve CDN temizleme adımları tamamen entegre edilmiştir.
+- Elle silme: Sadece moderatör/admin tarafından yapılabilir (`PATCH /work-orders/:id/photos/:photo_id/visibility` ile gizleme veya sistemsel silme).
+
+**Public Harita Görünürlüğü**
+- Fotoğraf bazında `is_public_visible` kontrolü moderatör ve admin tarafından yapılabilir.
+- Gizleme nedeni zorunludur (KVKK, uygunsuz içerik vb.).
+
+---
+
+## 📤 Export ve Raporlama Endpoint'leri
+
+| İşlem | Endpoint | Method | Yetkili Rol |
+|-------|----------|--------|-------------|
+| Denetim logu CSV export | `GET /audit-logs/export?format=csv&from=&to=` | GET | muni_admin, central_admin |
+| Rapor listesi export | `GET /work-orders/export?format=csv&...` | GET | İlgili roller |
+| Global rapor export | `GET /central/reports/export?format=csv&...` | GET | central_admin |
+
+---
+
+## 🩺 Sistem Sağlığı ve Monitoring
+
+| İşlem | Endpoint | Method | Not |
+|-------|----------|--------|-----|
+| Health check | `GET /health` | GET | Basit liveness |
+| Readiness | `GET /ready` | GET | DB + bağımlılık kontrolü (Central SaaS Polling Hedefi) |
+| Metrics (Prometheus) | `GET /metrics` | GET | Opsiyonel |
+
+### GET /ready (Municipal Backend Readiness Endpoint)
+Central Health Monitor tarafından 1 dakikada bir çağrılan, belediye sunucu servislerinin durumunu bildiren endpoint'tir.
+* **Headers:**
+  - `x-kentim-timestamp`: Milisaniye zaman damgası
+  - `x-kentim-signature`: HMAC-SHA256 Master Key ile üretilen istek imza başlığı
+* **HMAC Replay Koruması:** `x-kentim-timestamp` değerinin sunucu saatinden ±5 dakika içinde olması zorunludur; bu pencere dışındaki istekler `401 Unauthorized` ile reddedilir. Replay saldırılarına karşı ek koruma için `x-kentim-nonce` (UUIDv4) headerı zorunludur; aynı nonce **PostgreSQL `hmac_nonces` tablosunda** 10 dakika TTL ile saklanır ve mükerrer gönderimler reddedilir. (Tablo periyodik temizlik jobıyla 10 dakika önceki kayıtlardan arındırılır.)
+* **Response Body (200 OK):**
+```json
+{
+  "status": "ok",
+  "checked_at": "2026-05-27T15:45:00Z",
+  "services": {
+    "database": "connected",
+    "pg_listener_active": true,
+    "disk_usage_percentage": 42.5
+  }
+}
+```
+
+---
+
+## Özet
+
+- 115+ endpoint tanımlı.
+- Tüm 9 rol için net yetki ve kapsam kuralları tamamlandı.
+- Gerçek zamanlı iletişim (WebSocket/SSE), event payload şemaları, dosya/medya yönetimi (yükleme + otomatik silme), push token, export ve sistem sağlığı bölümleri detaylandırıldı.
+- Belge yaşayan bir dokümandır. Yeni eksiklik bulunduğunda doğrudan bu dosyaya eklenir.
+
+*Belge — KENTİM API / Endpoint Referans Belgesi (Tamamlanmış ve Sürekli Güncellenen)*
+
+---
+
+---
+
+## 📝 Dahili Not Yönetimi Endpoint'leri
+
+| İşlem | Endpoint | Method | Yetkili Rol | Not |
+|-------|----------|--------|-------------|-----|
+| Dahili not ekle | `POST /work-orders/:id/notes` | POST | muni_moderator, muni_department_manager, muni_team_chief, muni_admin | 15 dakika içinde düzenlenebilir |
+| Dahili not düzenle | `PATCH /work-orders/:id/notes/:note_id` | PATCH | Ekleyen kullanıcı (15 dk içinde) | Sadece ilk 15 dakika |
+| Dahili not sil | `DELETE /work-orders/:id/notes/:note_id` | DELETE | Ekleyen kullanıcı (15 dk içinde) | Sadece ilk 15 dakika |
+
+### İstek Gövdesi (Dahili Not)
+```json
+{
+  "content": "string (max 500 karakter)",
+  "internal": true
+}
+```
+
+---
+
+---
+
+> **Not (Dispute Endpoints):** `/admin/disputes/...` ve `/chief/disputes/...` endpoint'leri aynı semantiği paylaşır. Detaylı davranış (Double Payout otomatik `approved_override` geçişi dahil) için bkz. `is_akislari.md` — Senkronizasyon Uyuşmazlık Havuzu bölümü ve `mimari.md` trigger tanımı.
+
+---
+
+## 📱 Mobile Cihaz & Rate Limiting Endpoint'leri
+
+| İşlem | Endpoint | Method | Yetkili Rol | Not |
+|-------|----------|--------|-------------|-----|
+| Device ID doğrulama | `POST /devices/validate` | POST | Anonim | Panik butonu için cihaz doğrulama |
+| Device rate limit durumu | `GET /devices/:device_id/rate-limit-status` | GET | Anonim | `/emergency/panic` için 5 sinyal limiti |
+
+### Device ID Doğrulama İstek Gövdesi
+```json
+{
+  "device_id": "string (UUID format)"
+}
+```
+
+---
+
+## 🔧 IoT Entegrasyon Payload Şeması
+
+### POST /integrations/iot/telemetry Request Body
+*Kısıtlama:* Gönderilen ham JSON gövde boyutu (payload size) **maksimum 10KB** olmalıdır. Aksi takdirde istek `400 Bad Request` ile reddedilir.
+```json
+{
+  "device_id": "uuid",
+  "tenant_id": "resolved from API key",
+  "timestamp": "ISO8601 datetime",
+  "raw_payload": { ... },
+  "integration_config": {
+    "mapping_rules": { ... },
+    "parser_script": "function parse(payload) { ... }",
+    "default_public": true
+  }
+}
+```
+
+### Response Body (Fastify Decoupled Asenkron Kuyruklama Sonrası)
+*Yanıt Kodu:* `202 Accepted`
+```json
+{
+  "data": {
+    "status": "queued",
+    "message": "Telemetri verisi asenkron olarak PostgreSQL unlogged kuyruğuna (`iot_telemetry_queue`) alındı, pg_notify ile V8 sandbox warm isolate worker'lara yönlendirildi.",
+    "device_id": "uuid",
+    "tenant_id": "muni_a"
+  }
+}
+```
+
+#### 402 Grace Period (Abonelik Süresi Aşımı) Davranışı
+- **Tetiklenme Koşulu:** İlgili belediyenin abonelik süresi dolduğunda (`municipalities` tablosundaki `grace_period_ends_at` tarihine kadar olan 7 günlük süre boyunca).
+- **API Davranışı:** Telemetri verisi gönderildiğinde API yine **`202 Accepted`** ile yanıt verir ve veri `integration_logs` tablosuna kaydedilir (`event_type: 'DUPLICATE_SKIPPED'` veya `SUCCESS` olarak).
+- **İş Akışı Kısıtı:** Eşik değerleri (threshold) aşılsa dahi, V8 sandbox parser asenkron olarak yeni bir iş emri (`work_orders`) oluşturulmasını **tetiklemez**. Yeni iş emri tetikleme mantığı grace period boyunca tamamen askıya alınır.
+
+---
+
+## 📡 WebSocket Panic Kanalı Yetki Açıklaması (Netleştirildi)
+
+- `panic.{tenant_id}` kanalı **sadece muni_admin** rolüne görünür (kriz masası yetkisi).
+- **Ekip şefi (muni_team_chief)** bu kanalı doğrudan dinleyemez; ancak `/admin/crisis-map` sayfasında push bildirimleri alır.
+- **Central admin** tüm belediyelerin panic sinyallerini ayrı `panic.all` kanalından veya polling (`/central/reports?tab=heatmap`) ile izleyebilir.
+
+---
+
+## 🛡️ GDPR / KVKK API Endpoint'leri
+
+| İşlem | Endpoint | Method | Yetkili Rol |
+|-------|----------|--------|-------------|
+| KVKK talep listesi | `GET /gdpr/requests?status=pending|processing|completed` | GET | muni_admin |
+| Talep detayı | `GET /gdpr/requests/:id` | GET | muni_admin |
+| Talep işlemeye başla | `PATCH /gdpr/requests/:id/process` | PATCH | muni_admin | İndeksli `citizen_id` kolonu üzerinden asenkron regex maskelemeyi başlatır |
+| Talebi tamamla | `PATCH /gdpr/requests/:id/complete` | PATCH | muni_admin |
+
+### KVKK Talep İşleme Akışı
+1. Admin panelinden talep onaylandığında `/gdpr/requests/:id/process` çağrılır
+2. Sistem anonimleştirme job'ını başlatır (audit_logs maskeleme dahil)
+3. Job tamamlandığında `/gdpr/requests/:id/complete` ile `status=completed` ve `anonymized_at` set edilir
+
+---
+
+## Analitik Takip Endpoint Standartları ve API Olgunluğu (Eksikler Giderildi)
+
+KENTİM platformunun arayüz seviyesindeki modal navigasyonunu, vatandaş oylamalarını ve iş akış metriklerini izlemek amacıyla aşağıdaki analitik event toplama endpoint'i sisteme entegre edilmiştir:
+
+### 1. Analitik Olay Toplayıcı (Analytics Event Collector)
+
+* **Endpoint:** `POST /v1/analytics/events`
+* **Metot:** `POST`
+* **Yetki:** Anonim veya citizen (JWT). JWT varsa token'dan otomatik `citizen_id` eşleştirilir.
+* **Header:** `x-idempotency-key` zorunlu değildir (analitik verilerinde mükerrerlik kritik olmadığı için).
+
+**İstek Gövdesi (Request Body):**
+```json
+{
+  "event": "modal_open | report_submit_success | support_vote_added | idea_vote_submitted | duplicate_check_triggered | qa_loop_triggered",
+  "timestamp": "2026-05-26T20:15:00Z",
+  "payload": {
+    "modal_type": "report-new", // event = modal_open ise
+    "tracking_code": "KENT-34-ABC12", // varsayılan olarak opsiyonel
+    "source": "map_pin_click",
+    "category_id": "uuid", // event = report_submit_success ise
+    "is_anonymous": true,
+    "direction": 1, // event = idea_vote_submitted ise
+    "qa_work_order_id": "uuid" // event = qa_loop_triggered ise
+  }
+}
+```
+
+**Yanıt (202 Accepted):**
+```json
+{
+  "data": {
+    "status": "queued",
+    "message": "Olay işlenmek üzere kuyruğa alındı"
+  }
+}
+```
+*(Not: Analitik istekleri API thread'ini meşgul etmemek için HTTP 202 statüsüyle asenkron olarak **PostgreSQL unlogged tablosu** (`analytics_event_queue`) üzerine `INSERT` + `pg_notify` ile kuyruğa yazılır ve ayrı bir worker process tarafından asenkron işlenir.)*
+
+**Sonuç:** KENTİM API / Endpoint Referans dokümantasyonu, tüm operasyonel, analitik ve hata edge-case endpoint'leriyle beraber %100 oranında tamamlanmıştır. Bilinen hiçbir eksiklik bulunmamaktadır.
+
+---
+
+## V1 Yol Haritası Kapsamındaki API Genişletmeleri (Audit & Locations)
+
+### 1. Coğrafi Hiyerarşi Sorgulama (Lokasyon Sözlüğü)
+Yeni belediye kayıtlarında ve saha organizasyonu formlarında dropdown'ları besleyen dinamik lokasyon servisidir.
+
+* **Endpoint:** `GET /v1/central/locations/hierarchy`
+* **Metot:** `GET`
+* **Yetki:** Anonim / `central_admin` / `muni_admin` (Serbest Erişim)
+* **Query Parametreleri:**
+  - `type` (Opsiyonel): `province` veya `district`
+  - `parent_id` (Opsiyonel): Alt ilçeleri getirmek için üst ilin ID'si (UUIDv4)
+  - `page`, `limit` (Opsiyonel): Varsayılan `limit=100`
+
+#### Başarılı Yanıt Örneği (İlleri Getirme - `GET /v1/central/locations/hierarchy?type=province`):
+```json
+{
+  "data": [
+    {
+      "id": "a2e564ad-43ab-41c1-90a1-24c568ad9cf1",
+      "name": "İstanbul",
+      "parent_id": null,
+      "type": "province",
+      "slug": "istanbul",
+      "created_at": "2026-05-24T12:00:00Z"
+    },
+    {
+      "id": "b8f675bc-54bc-52d2-01a2-35d679be0df2",
+      "name": "İzmir",
+      "parent_id": null,
+      "type": "province",
+      "slug": "izmir",
+      "created_at": "2026-05-24T12:00:00Z"
+    }
+  ],
+  "meta": {
+    "page": 1,
+    "limit": 100,
+    "total": 81,
+    "has_more": false
+  }
+}
+```
+
+#### Başarılı Yanıt Örneği (Seçilen İlin İlçelerini Getirme - `GET /v1/central/locations/hierarchy?parent_id=a2e564ad-43ab-41c1-90a1-24c568ad9cf1`):
+```json
+{
+  "data": [
+    {
+      "id": "c1f886de-65cd-63e3-12b3-46e780cf1ef3",
+      "name": "Kadıköy",
+      "parent_id": "a2e564ad-43ab-41c1-90a1-24c568ad9cf1",
+      "type": "district",
+      "slug": "kadikoy",
+      "created_at": "2026-05-24T12:05:00Z"
+    },
+    {
+      "id": "d2e997ef-76de-74f4-23c4-57f891df2f04",
+      "name": "Beşiktaş",
+      "parent_id": "a2e564ad-43ab-41c1-90a1-24c568ad9cf1",
+      "type": "district",
+      "slug": "besiktas",
+      "created_at": "2026-05-24T12:05:00Z"
+    }
+  ],
+  "meta": {
+    "page": 1,
+    "limit": 100,
+    "total": 39,
+    "has_more": false
+  }
+}
+```
+
+---
+
+### 2. Merkezi Denetim Logları Sorgulama (SaaS Seviyesi)
+SaaS yöneticilerinin global işlemlerini, abonelik ve belediye güncellemelerini JSONB old/new formatında yansıtan log servisidir.
+
+* **Endpoint:** `GET /v1/central/audit-logs`
+* **Metot:** `GET`
+* **Yetki:** `central_admin` (Korumalı JWT Bearer)
+* **Query Parametreleri:**
+  - `event_type` (Opsiyonel): `MUNICIPALITY_REGISTERED`, `LICENSE_SUSPENDED`, `GLOBAL_CONFIG_UPDATED` vb.
+  - `municipality_id` (Opsiyonel): UUID formatında hedef belediye filtresi
+  - `page`, `limit` (Opsiyonel): Varsayılan `limit=25` (Offset bazlı)
+
+#### Başarılı Yanıt Örneği (Lisans Güncelleme Diff Logu):
+```json
+{
+  "data": [
+    {
+      "id": "e814a0a5-f375-4089-9a7c-65cd945c7e01",
+      "central_user_id": "8b9e67ab-43ab-41c1-90a1-24c568ad9cf1",
+      "municipality_id": "7ca64e7c-a49e-4e4b-bb12-9cfa2bde3431",
+      "event_type": "LICENSE_UPDATED",
+      "ip_address": "195.175.25.10",
+      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
+      "payload_old": {
+        "license_status": "active",
+        "license_expires_at": "2026-05-24T23:59:59Z",
+        "grace_period_ends_at": null
+      },
+      "payload_new": {
+        "license_status": "active",
+        "license_expires_at": "2027-05-24T23:59:59Z",
+        "grace_period_ends_at": null
+      },
+      "created_at": "2026-05-25T14:30:00Z"
+    }
+  ],
+  "meta": {
+    "page": 1,
+    "limit": 25,
+    "total": 540,
+    "has_more": true
+  }
+}
+```
+
+---
+
+### 3. Belediye Denetim Logları Sorgulama (Tenant Seviyesi)
+Belediye panelinde yöneticilerin gerçekleştirdiği tüm durum makinesi güncellemelerini, personel atamalarını ve geofence onaylarını JSONB formatında yansıtan log servisidir.
+
+* **Endpoint:** `GET /v1/admin/audit-logs`
+* **Metot:** `GET`
+* **Yetki:** `muni_admin` (Korumalı JWT Bearer + RLS Otomatik Kapsam)
+* **Query Parametreleri:**
+  - `event_type` (Opsiyonel): `WORK_ORDER_STATUS_CHANGED`, `GEOFENCE_BYPASS_APPROVED`, `DISPUTE_RESOLVED` vb.
+  - `citizen_id` (Opsiyonel): UUID formatında vatandaş filtresi (KVKK regex maskeleme denetimleri için kısmi indeks ile optimize)
+  - `work_order_id` (Opsiyonel): UUID formatında iş emri filtresi
+  - `page`, `limit` (Opsiyonel): Varsayılan `limit=25` (Offset bazlı)
+
+#### Başarılı Yanıt Örneği (İş Emri Durum Değişikliği / Şef Onayı Bypass Logu):
+```json
+{
+  "data": [
+    {
+      "id": "7fa2bde3-a49e-4e4b-bb12-9cfa2bde3499",
+      "tenant_id": "muni_a",
+      "user_id": "3b9e67ab-43ab-41c1-90a1-24c568ad9cf9",
+      "citizen_id": "1c7e99ab-62cd-41e1-b0e2-88d568ad9c88",
+      "work_order_id": "4da64e7c-a49e-4e4b-bb12-9cfa2bde3422",
+      "event_type": "MANUAL_APPROVAL_BY_MANAGER",
+      "ip_address": "85.105.42.112",
+      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
+      "payload_old": {
+        "status": "pending_chief_approval",
+        "is_manager_bypassed": false,
+        "resolved_at": null
+      },
+      "payload_new": {
+        "status": "resolved",
+        "is_manager_bypassed": true,
+        "resolved_at": "2026-05-26T16:45:00Z"
+      },
+      "created_at": "2026-05-26T16:45:00Z"
+    }
+  ],
+  "meta": {
+    "page": 1,
+    "limit": 25,
+    "total": 12850,
+    "has_more": true
+  }
+}
+```
+
+---
+
+## V1 Yol Haritası Kapsamındaki API Genişletmeleri (Ek Netleştirmeler)
+
+### 1. Halka Açık Genel İstatistik Şeması (`GET /v1/public/statistics`)
+Ana sayfa haritasında sol alt köşede yer alan şeffaf istatistik panelini (Public Statistics Widget) besleyen uçu temsil eder.
+* **Endpoint:** `GET /v1/public/statistics`
+* **Metot:** `GET`
+* **Yetki:** Anonim / Herkese Açık
+* **Query Parametreleri:**
+  - `municipality_id` (Opsiyonel): Belirli bir belediyeye ait metrikleri çekmek için belediye UUID'si. Gönderilmezse, sistem otomatik olarak kullanıcının coğrafi konumuna (IP veya GPS) göre en yakın belediyenin verilerini döndürmeye çalışır; bulunamazsa `400 Bad Request` hatası döner.
+
+#### Başarılı Yanıt Örneği (`200 OK`):
+```json
+{
+  "data": {
+    "resolved_count": 14205,
+    "in_progress_count": 342,
+    "support_count": 89412,
+    "sla_compliance_rate": 94.2,
+    "average_resolution_time_hours": 28.5
+  },
+  "meta": {
+    "calculated_at": "2026-05-27T15:00:00Z",
+    "ttl_seconds": 300
+  }
+}
+```
+
+### 2. `POST /reports` İstek Gövdesine Kronik Rapor Alanı (`parent_reopened_work_order_id`)
+Vatandaşın aynı sorun için yeniden açma (reopen) limiti (maksimum 2) bittiğinde ve yeni bir rapor oluşturduğunda, bu yeni raporu eski rapor zinciriyle asenkron bağlamak amacıyla kullanılan opsiyonel alandır.
+* **Endpoint:** `POST /reports`
+* **İstek Gövdesi (Request Body) - Örnek:**
+```json
+{
+  "category_id": "uuid",
+  "latitude": 41.0082,
+  "longitude": 28.9784,
+  "description": "Yol üzerinde derin çukur oluşmuş, araçlar için tehlike saçıyor.",
+  "photo_urls": [
+    "https://storage.kentim.com.tr/muni_a/reports/uuid_1.jpg"
+  ],
+  "is_anonymous": false,
+  "parent_reopened_work_order_id": "4da64e7c-a49e-4e4b-bb12-9cfa2bde3422"
+}
+```
+
+### 3. Cihaz / Push Token Kaydetme Yetkisi (`POST /devices` ve `DELETE /devices/:device_id`)
+Vatandaşlar da mobil push bildirimi tercih edebileceğinden, token kaydetme ve cihaz yönetimi `citizen` rolünü de kapsayacak şekilde genişletilmiştir.
+* **Yol:** `POST /devices` ve `DELETE /devices/:device_id`
+* **Yetkili Roller:** `muni_worker`, `muni_team_chief`, `citizen` (JWT yetkilendirmesiyle kiracı ve kullanıcı tespiti otomatik yapılır)
+
+### 4. Admin Kesin Atama (`is_force_assigned = true`) Yetki Sınırları ve Kilit Politikası
+* **Açıklama:** Belediye admini tarafından `PATCH /work-orders/:id/force-assign` endpoint'i üzerinden yapılan "Kesin Atama" (Force Assign) işlemi, iş emrine kalıcı olarak `is_force_assigned = true` flag'ini yazar.
+* **Kilit Kuralı:** Bu flag aktifken:
+  1. **Müdürler (`muni_department_manager`) re-dispatch (işi başka müdürlüğe iade etme/gönderme) yapamaz.**
+  2. Ekiplerin sahada tıkanmaması için müdürler personel atayabilir/değiştirebilir (`reassign_worker`), işi zorla kapatabilir (`force_resolve` veya `manual_approval`) veya işi iptal edebilirler (`reject`).
+  3. Sadece `muni_admin` (Belediye Sistem Yöneticisi) işin atama durumunu ve müdürlük yönlendirmesini ezebilir (override) veya değiştirebilir.
+
+### 5. `GET /evacuation-routes` Afet Modu Bağımlılığı
+* **Açıklama:** Tahliye ve kaçış güzergahlarını listeleyen bu servis yalnızca **Afet Modu aktif olduğunda** anlamlı coğrafi veri döner.
+* **Normal Mod Davranışı:** Afet modu aktif değilken yapılan çağrılarda servis hata fırlatmaz, performans ve kararlılık açısından **boş liste (`{ "data": [] }`)** döndürerek graceful fallback sağlar.
+
+### 6. Takip Kodu Formatı ve Validasyon Kuralları
+* **Format:** `KENT-[plaka]-[rastgele_alfanumerik_8_hane]`
+* **Örnek:** `KENT-34-A78C9E42`
+* **Doğrulama:** `GET /reports/track/:trackingCode` endpoint'inde iletilen kodun formatı Regex (`^KENT-\d{2}-[A-Z0-9]{8}$`) ile doğrulanır. Plaka hanesi (örn: 34), veritabanında sorgulama yapılırken kiracı (tenant) çözümlemesini hızlandırmak ve doğrudan ilgili belediyenin veritabanı şemasına yönlendirme yapmak için reverse proxy/gateway katmanında mikro-indeks olarak kullanılır.
+
+### 7. `GET /public/reports` Nearby ve Radius Parametresi Davranışı
+* **Açıklama:** Vatandaşın haritadan konum seçtiğinde mükerrer rapor kontrolü yapmasını sağlayan mesafe bazlı yakın pinlerin çekilmesi için standart `GET /public/reports/nearby?lat=&lng=&radius=` ucu kullanılır:
+  * **Uç Nokta:** `GET /public/reports/nearby?lat=41.0082&lng=28.9784&radius=100` (Metre cinsinden tam sayı)
+  * Bu endpoint, bbox hesaplama karmaşasını ortadan kaldırarak belirtilen koordinatın dairesel çevresindeki (PostGIS `ST_DWithin` kullanılarak) aktif pinleri döner.
+
+---
+
+### 8. Dinamik Statik İçerik Yönetimi (`/static-contents`)
+
+Merkezi SaaS paneli üzerinden yönetilen statik içeriklerin (`Hakkımızda`, `KVKK`, `Gizlilik` vb.) API şemaları aşağıda detaylandırılmıştır.
+
+**Ek Öneri (V1 Kapsamı):**  
+Public Web Yol Haritası (MVP ve V1 içerikleri) **sadece Merkez Panel (Central Admin)** üzerinden yönetilebilir. Belediye paneli bu içeriğe erişemez. `central_static_contents` tablosuna `public_web_roadmap_mvp` ve `public_web_roadmap_v1` key'leri eklenerek Central Admin tarafından güncellenebilir.
+
+#### `GET /v1/public/static-contents/:key`
+Halka açık olarak statik içeriği anahtarına (`key`) göre getirir.
+
+*   **Başarılı Yanıt Örneği (`200 OK`):**
+    ```json
+    {
+      "data": {
+        "key": "privacy",
+        "title": "Gizlilik Politikası",
+        "content": "<p>Şirketimiz, kullanıcılarımızın kişisel verilerinin gizliliğine son derece önem vermektedir...</p>",
+        "updated_at": "2026-05-20T10:00:00Z"
+      }
+    }
+    ```
+
+#### `PUT /v1/central/static-contents/:key`
+Merkezi adminin (`central_admin`) statik içeriği güncellemesini sağlar.
+
+*   **Yetki:** `central_admin`
+*   **İstek Gövdesi (Request Body):**
+    ```json
+    {
+      "title": "Yeni Gizlilik Politikası",
+      "content": "<h1>Güncellenmiş Metin</h1><p>...</p>"
+    }
+    ```
+*   **Başarılı Yanıt Örneği (`200 OK`):** Güncellenmiş içeriğin tamamı döner (yukarıdaki GET yanıtı gibi).
+
+---
+
+### 9. `POST /reports` Fotoğraf Yükleme Yöntemleri ve Tam Şema
+
+Vatandaşların sorun bildirirken fotoğraf eklemesi için iki yöntem desteklenir:
+
+*   **a) Direct Upload (Multipart/Form-Data):** Form verileri (`category_id`, `description` vb.) ile birlikte maksimum 5 adet görsel dosyası (her biri max 5MB) tek bir `multipart/form-data` isteğinde sunucuya gönderilir. İstemci tarafında en basit yöntem budur.
+*   **b) Pre-signed URL (Gateway-Optimized):** Özellikle mobil ve yavaş ağlarda daha güvenilir olan bu yöntemde:
+    1.  İstemci önce `POST /v1/reports/upload-urls` endpoint'ine dosya adları ve tiplerini içeren bir istek göndererek S3 (veya uyumlu storage) için geçici, güvenli yükleme URL'leri alır.
+    2.  İstemci, aldığı bu URL'lere dosyaları doğrudan (genellikle `PUT` metodu ile) yükler.
+    3.  Yükleme tamamlandıktan sonra, standart `POST /reports` isteğinin gövdesindeki `photo_urls` dizisine bu dosyaların sunucudaki mutlak (absolute) URL'lerini ekleyerek raporu oluşturur.
+
+#### `POST /v1/reports/upload-urls`
+Pre-signed URL almak için kullanılır.
+
+*   **Yetki:** `citizen` / Anonim
+*   **İstek Gövdesi:**
+    ```json
+    {
+      "file_name": "photo.jpg",
+      "content_type": "image/jpeg"
+    }
+    ```
+*   **Başarılı Yanıt (`200 OK`):**
+    ```json
+    {
+      "data": {
+        "upload_url": "https://s3.eu-central-1.amazonaws.com/kentim-uploads/...",
+        "file_url": "https://storage.kentim.com.tr/muni_a/reports/..."
+      }
+    }
+    ```
+
+#### Tam `POST /reports` İstek Gövdesi (JSON)
+```json
+{
+  "category_id": "c1f886de-65cd-63e3-12b3-46e780cf1ef3",
+  "latitude": 41.0082,
+  "longitude": 28.9784,
+  "description": "Yol üzerindeki çukur araçlar için tehlikeli.",
+  "photo_urls": [
+    "https://storage.kentim.com.tr/muni_a/reports/c1f886de-..../photo1.jpg",
+    "https://storage.kentim.com.tr/muni_a/reports/c1f886de-..../photo2.jpg"
+  ],
+  "is_anonymous": true,
+  "parent_reopened_work_order_id": null
+}
+```
+*   **`is_anonymous` Flag:** `true` olarak ayarlandığında, raporu oluşturan vatandaşın adı ve soyadı gibi kimlik bilgileri halka açık arayüzlerde ve rapor detaylarında maskelenerek gizlenir. `false` ise veya alan gönderilmezse, giriş yapmış kullanıcının profilindeki adı raporda görünür.
+
+---
+
+### 10. Fikir Oylama/Oluşturma için MERNIS Entegrasyonu ve JWT Claim
+
+Fikir oylama (`POST /ideas/:id/vote`) ve fikir oluşturma (`POST /ideas`) endpoint'lerinin sahte hesaplarla manipüle edilmesini önlemek amacıyla, bu işlemleri gerçekleştirecek vatandaşların T.C. Kimlik Numaralarını doğrulamış olması zorunludur.
+
+*   **Akış:**
+    1.  Kullanıcı, profil ayarlarından `POST /auth/tc-kimlik/verify` endpoint'ini tetikleyen formu doldurur (TCKN, Ad, Soyad, Doğum Yılı).
+    2.  Başarılı MERNIS doğrulaması sonucunda, kullanıcının aktif JWT token'ı yenilenir ve payload'una `"is_identity_verified": true` claim'i eklenir.
+    3.  API Gateway, `/ideas` ve `/ideas/:id/vote` endpoint'lerine gelen isteklerde bu claim'in varlığını ve `true` olmasını kontrol eder. Claim yoksa veya `false` ise istek `403 Forbidden` hatası ile reddedilir.
+
+---
+
+### 11. Eksik Public Endpoint Yanıt Şemaları
+
+Aşağıda, daha önce detaylı şeması verilmeyen bazı public endpoint'lerin başarılı yanıt (`200 OK`) örnekleri bulunmaktadır.
+
+#### `GET /evacuation-routes`
+Afet anında en yakın toplanma alanlarına giden rotaları listeler.
+```json
+{
+  "data": [
+    {
+      "id": "route-uuid-1",
+      "name": "Acil Toplanma Alanı A'ya Giden Rota",
+      "geojson": {
+        "type": "LineString",
+        "coordinates": [ [28.97, 41.00], [28.98, 41.01], [28.99, 41.02] ]
+      },
+      "estimated_distance_meters": 1200,
+      "estimated_time_minutes": 15
+    }
+  ]
+}
+```
+
+#### `GET /recycling-points`
+Geri dönüşüm noktalarını listeler.
+```json
+{
+  "data": [
+    {
+      "id": "point-uuid-1",
+      "name": "Kadıköy Belediyesi Cam Atık Kumbarası",
+      "type": ["glass", "paper"],
+      "address": "Caferağa, Mühürdar Cd. No:50, 34710 Kadıköy/İstanbul",
+      "location": { "type": "Point", "coordinates": [29.02, 40.99] },
+      "operating_hours": "7/24"
+    }
+  ]
+}
+```
+
+#### `GET /announcements` & `GET /announcements/:id`
+Belediye duyurularını listeler ve detayını verir.
+```json
+{
+  "data": {
+    "id": "announce-uuid-1",
+    "title": "Su Kesintisi Uyarısı",
+    "content": "Altyapı çalışmaları nedeniyle 1 Haziran 2026 tarihinde belirtilen mahallelerde su kesintisi yaşanacaktır.",
+    "type": "warning",
+    "published_at": "2026-05-28T10:00:00Z",
+    "expires_at": "2026-06-02T10:00:00Z",
+    "affected_districts": ["Caferağa", "Osmanağa"]
+  }
+}
+```
+
+#### `GET /ideas` & `GET /ideas/:id`
+Vatandaş fikirlerini listeler ve detayını verir.
+```json
+{
+  "data": {
+    "id": "idea-uuid-1",
+    "title": "Mahallemize Kedi Evi Yapılsın",
+    "description": "Sokak hayvanları için kış aylarında korunabilecekleri bir kedi evi yapılmasını öneriyorum.",
+    "category": "environment",
+    "status": "approved",
+    "vote_summary": { "upvotes": 125, "downvotes": 12, "net": 113 },
+    "author": { "name": "Ayşe Y." },
+    "created_at": "2026-04-15T14:00:00Z",
+    "official_reply": {
+      "content": "Değerli öneriniz için teşekkür ederiz. Konu Park ve Bahçeler Müdürlüğümüz tarafından değerlendirmeye alınmıştır.",
+      "replied_at": "2026-05-10T11:00:00Z"
+    }
+  }
+}
+```
+
+#### `POST /ideas`
+Yeni bir fikir oluşturma istek gövdesi.
+```json
+{
+  "title": "Bisiklet Yolları Artırılsın",
+  "description": "Ulaşımı kolaylaştırmak ve çevreyi korumak adına bisiklet yollarının yaygınlaştırılmasını talep ediyorum.",
+  "category": "transportation",
+  "related_district": "Kadıköy"
+}
+```
+
+#### `POST /ideas/:id/vote`
+Bir fikre oy verme istek gövdesi.
+```json
+{
+  "direction": 1
+}
+```
+*   `direction`: `1` (destekliyorum / upvote), `-1` (karşıyım / downvote).
+
+---
+
+### 12. `GET /public/reports` `status` ve `public_id` Parametre Detayları
+
+#### `status` Parametresi
+`GET /public/reports?status=...` endpoint'inde kullanılabilecek geçerli durum (`status`) değerleri ve anlamları:
+
+*   `moderation`: Rapor oluşturuldu, moderatör incelemesinde.
+*   `dispatched_to_department`: Moderatör tarafından ilgili müdürlüğe havale edildi.
+*   `assigned_to_team`: Müdür tarafından bir ekibe (şefe) atandı.
+*   `assigned_to_worker`: Şef tarafından bir saha personeline atandı.
+*   `in_progress`: Saha personeli işi üstlendi ve çalışma başlattı.
+*   `pending_chief_approval`: Saha personeli işi tamamladı, şefin fotoğraf onayını bekliyor.
+*   `resolved`: Şef tarafından onaylandı ve çözüldü.
+
+**Not:** `pending` (vatandaş tarafından oluşturulmuş ancak henüz sisteme tam düşmemiş taslak) ve `rejected` (reddedilmiş) durumundaki raporlar halka açık haritada gösterilmez ve bu API'den dönülmez.
+
+#### `public_id` Tanımı
+`GET /public/reports/:public_id` endpoint'indeki `:public_id` değeri, ilgili raporla ilişkili olan **iş emrinin (`work_order`)** benzersiz **UUIDv4** kimliğidir. Bu, vatandaşın takip kodundan farklı, sistemsel bir kimliktir.
+
+---
+
+### 13. `GET /citizen/support-votes` Yanıt Şeması
+Vatandaşın "+1 Beni de Etkiliyor" diyerek desteklediği raporları listeleyen endpoint'in örnek yanıt şeması.
+
+*   **Başarılı Yanıt Örneği (`200 OK`):**
+    ```json
+    {
+      "data": [
+        {
+          "work_order": {
+            "public_id": "work-order-uuid-1",
+            "tracking_code": "KENT-34-XYZ123",
+            "title": "Kırık kaldırım taşı",
+            "category": "Yol ve Kaldırım",
+            "status": "in_progress"
+          },
+          "voted_at": "2026-05-15T18:30:00Z"
+        },
+        {
+          "work_order": {
+            "public_id": "work-order-uuid-2",
+            "tracking_code": "KENT-34-ABC456",
+            "title": "Parktaki aydınlatma çalışmıyor",
+            "category": "Park ve Bahçeler",
+            "status": "resolved"
+          },
+          "voted_at": "2026-05-10T11:00:00Z"
+        }
+      ],
+      "meta": {
+        "page": 1,
+        "limit": 20,
+        "total": 2,
+        "has_more": false
+      }
+    }
+    ```
+
+*Belge — KENTİM API / Endpoint Referans Belgesi (Tamamlanmış ve Sürekli Güncellenen)*
+
+