{"openapi":"3.1.0","info":{"title":"Apartman & Site Yönetim REST API","version":"1.0.0","description":"Cloudflare Workers (Hono.js + D1 Drizzle ORM + R2 + Web Crypto JWT) tabanlı uçtan uca Apartman ve Site Yönetim API dokümantasyonu."},"servers":[{"url":"https://apartman.melihcanaz.tr","description":"Aktif API Sunucusu"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"POST /api/v1/auth/login veya /bootstrap ile alınan JWT Access Token"}}},"paths":{"/health":{"get":{"operationId":"system-health","tags":["0. Sistem & Zamanlanmış Görevler"],"summary":"Sistem, D1 veritabanı ve R2 sağlık kontrolü","description":"Worker çalışma durumunu, D1 tablo sayısını, sorgu gecikmesini ve R2 bağlantısını döner.\n\n**Yetkili Roller:** `PUBLIC`","responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/internal/cron/run-scheduled":{"post":{"operationId":"system-cron-trigger","tags":["0. Sistem & Zamanlanmış Görevler"],"summary":"Zamanlanmış görevleri (Aidat, Gecikme Faizi, Rutin Görevler) manuel tetikle","description":"Geliştirme/test ortamında veya SUPER_ADMIN yetkisiyle aylık otomatik aidat tahakkuku, gecikme tazminatı ve periyodik temizlik/bakım görev üretimini verilen tarih için çalıştırır.\n\n**Yetkili Roller:** `SUPER_ADMIN`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"referenceDate":"2026-11-16T03:00:00.000Z"}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/auth/bootstrap":{"post":{"operationId":"auth-bootstrap","tags":["1. Kimlik Doğrulama & Oturum (Auth)"],"summary":"Sistem ilk kurulumu (İlk Yönetim Şirketi + İlk PLATFORM_ADMIN / SUPER_ADMIN)","description":"Veritabanında henüz hiç kullanıcı yokken ilk yönetim şirketini ve tam yetkili yönetici hesabını oluşturur; Access ve Refresh Token döner.\n\n**Yetkili Roller:** `PUBLIC (Tek Seferlik)`","requestBody":{"required":true,"content":{"application/json":{"example":{"organizationName":"Boğaziçi Tesis Yönetim A.Ş.","organizationSlug":"bogazici-yonetim","taxOffice":"Beşiktaş","taxNumber":"1234567890","fullName":"Can Az","email":"admin@bogaziciyonetim.com","phone":"+905551112233","password":"StrongPassword123!"}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/auth/login":{"post":{"operationId":"auth-login","tags":["1. Kimlik Doğrulama & Oturum (Auth)"],"summary":"E-posta ve parola ile giriş (JWT Access + Refresh Token)","description":"5 başarısız denemede hesabı 15 dakika kilitler. Dakikada 15 istek Rate Limit korumalıdır.\n\n**Yetkili Roller:** `PUBLIC`","requestBody":{"required":true,"content":{"application/json":{"example":{"email":"admin@bogaziciyonetim.com","password":"StrongPassword123!"}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/auth/refresh":{"post":{"operationId":"auth-refresh","tags":["1. Kimlik Doğrulama & Oturum (Auth)"],"summary":"Refresh Token ile oturum yenileme (Token Rotation & Reuse Detection)","description":"Kullanılan refresh token iptal edilir ve yenisi verilir. İptal edilmiş bir token tekrar gönderilirse o oturum ailesindeki tüm tokenlar güvenlik amacıyla iptal edilir.\n\n**Yetkili Roller:** `PUBLIC`","requestBody":{"required":true,"content":{"application/json":{"example":{"refreshToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/auth/logout":{"post":{"operationId":"auth-logout","tags":["1. Kimlik Doğrulama & Oturum (Auth)"],"summary":"Mevcut oturumu kapat (Refresh Token iptali)","description":"Gönderilen refresh token kaydını veritabanında iptal eder.\n\n**Yetkili Roller:** `PUBLIC`","requestBody":{"required":true,"content":{"application/json":{"example":{"refreshToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/auth/logout-all":{"post":{"operationId":"auth-logout-all","tags":["1. Kimlik Doğrulama & Oturum (Auth)"],"summary":"Tüm cihazlardaki oturumları sonlandır","description":"Oturum açmış kullanıcının tüm aktif refresh tokenlarını iptal eder.\n\n**Yetkili Roller:** `ANY_AUTHENTICATED`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/auth/me":{"get":{"operationId":"auth-me-get","tags":["1. Kimlik Doğrulama & Oturum (Auth)"],"summary":"Oturum açmış kullanıcının profili, şirketleri, binaları ve daireleri","description":"Kullanıcının temel bilgilerini, SUPER_ADMIN olduğu organizasyonları, BUILDING_MANAGER/STAFF olduğu binaları ve OWNER/TENANT olduğu daireleri döner.\n\n**Yetkili Roller:** `ANY_AUTHENTICATED`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"patch":{"operationId":"auth-me-patch","tags":["1. Kimlik Doğrulama & Oturum (Auth)"],"summary":"Kendi profil bilgilerini güncelle (Ad Soyad, Telefon, Dil)","description":"Oturum açmış kullanıcının kendi profil alanlarını günceller.\n\n**Yetkili Roller:** `ANY_AUTHENTICATED`","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"fullName":"Can Az","phone":"+905559998877","locale":"tr"}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/auth/change-password":{"post":{"operationId":"auth-change-password","tags":["1. Kimlik Doğrulama & Oturum (Auth)"],"summary":"Parola değiştir","description":"Mevcut parolayı doğrulayarak yeni parolayı kaydeder ve eski oturumları sonlandırır.\n\n**Yetkili Roller:** `ANY_AUTHENTICATED`","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"currentPassword":"StrongPassword123!","newPassword":"NewStrongPassword456!"}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/auth/forgot-password":{"post":{"operationId":"auth-forgot-password","tags":["1. Kimlik Doğrulama & Oturum (Auth)"],"summary":"Şifremi unuttum — 15 dk geçerli tek kullanımlık sıfırlama tokenı üretir","description":"Kullanıcının mevcut parola özetine bağlı 15 dakikalık sıfırlama tokenı üretir. Geliştirme ortamında test kolaylığı için resetToken yanıt içinde döner.\n\n**Yetkili Roller:** `PUBLIC`","requestBody":{"required":true,"content":{"application/json":{"example":{"email":"admin@bogaziciyonetim.com"}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/auth/reset-password":{"post":{"operationId":"auth-reset-password","tags":["1. Kimlik Doğrulama & Oturum (Auth)"],"summary":"Sıfırlama tokenı ile yeni parola belirle","description":"Tek kullanımlık sıfırlama tokenını doğrular ve yeni parolayı kaydeder.\n\n**Yetkili Roller:** `PUBLIC`","requestBody":{"required":true,"content":{"application/json":{"example":{"resetToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","newPassword":"ResetPassword789!"}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/organizations":{"get":{"operationId":"orgs-list","tags":["2. Yönetim Şirketleri (Organizations)"],"summary":"Yetkili olunan yönetim şirketlerini listele","description":"PLATFORM_ADMIN tüm şirketleri, SUPER_ADMIN üyesi olduğu şirketleri görür.\n\n**Yetkili Roller:** `PLATFORM_ADMIN`, `SUPER_ADMIN`","security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"description":"Sayfa numarası (varsayılan: 1)","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Sayfa başına kayıt (varsayılan: 20)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"post":{"operationId":"orgs-create","tags":["2. Yönetim Şirketleri (Organizations)"],"summary":"Yeni yönetim şirketi oluştur","description":"Yeni bir yönetim şirketi (tenant) oluşturur ve oluşturan kişiyi SUPER_ADMIN olarak atar.\n\n**Yetkili Roller:** `PLATFORM_ADMIN`, `SUPER_ADMIN`","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"name":"Marmara Site Yönetimi Ltd. Şti.","slug":"marmara-site-yonetimi","taxOffice":"Kadıköy","taxNumber":"9876543210","email":"info@marmarayonetim.com","phone":"+902163334455"}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/organizations/{orgId}":{"get":{"operationId":"orgs-detail","tags":["2. Yönetim Şirketleri (Organizations)"],"summary":"Yönetim şirketi detayı","description":"Şirket bilgilerini, bina ve üye sayılarını döner.\n\n**Yetkili Roller:** `PLATFORM_ADMIN`, `SUPER_ADMIN`","security":[{"bearerAuth":[]}],"parameters":[{"name":"orgId","in":"path","required":true,"description":"Organizasyon UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"patch":{"operationId":"orgs-update","tags":["2. Yönetim Şirketleri (Organizations)"],"summary":"Yönetim şirketi bilgilerini güncelle","description":"Şirket unvanı, vergi bilgileri ve iletişim alanlarını günceller.\n\n**Yetkili Roller:** `PLATFORM_ADMIN`, `SUPER_ADMIN`","security":[{"bearerAuth":[]}],"parameters":[{"name":"orgId","in":"path","required":true,"description":"Organizasyon UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"name":"Marmara Profesyonel Site Yönetimi A.Ş.","phone":"+902164445566"}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/organizations/{orgId}/members":{"get":{"operationId":"orgs-members-list","tags":["2. Yönetim Şirketleri (Organizations)"],"summary":"Yönetim şirketi yöneticilerini (SUPER_ADMIN) listele","description":"Şirkete atanmış tüm aktif/pasif SUPER_ADMIN üyelerini döner.\n\n**Yetkili Roller:** `PLATFORM_ADMIN`, `SUPER_ADMIN`","security":[{"bearerAuth":[]}],"parameters":[{"name":"orgId","in":"path","required":true,"description":"Organizasyon UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"post":{"operationId":"orgs-members-add","tags":["2. Yönetim Şirketleri (Organizations)"],"summary":"Yönetim şirketine yeni SUPER_ADMIN ekle","description":"Mevcut userId ile veya newUser nesnesiyle yeni kullanıcı açarak şirkete SUPER_ADMIN atar.\n\n**Yetkili Roller:** `PLATFORM_ADMIN`, `SUPER_ADMIN`","security":[{"bearerAuth":[]}],"parameters":[{"name":"orgId","in":"path","required":true,"description":"Organizasyon UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"newUser":{"email":"ortak@bogaziciyonetim.com","fullName":"Selin Demir","phone":"+905321112233","password":"PartnerPassword123!"}}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/organizations/{orgId}/members/{memberId}":{"delete":{"operationId":"orgs-members-remove","tags":["2. Yönetim Şirketleri (Organizations)"],"summary":"Yönetim şirketi üyesini pasife al","description":"Şirketteki son aktif SUPER_ADMIN silinemez (korumalıdır).\n\n**Yetkili Roller:** `PLATFORM_ADMIN`, `SUPER_ADMIN`","security":[{"bearerAuth":[]}],"parameters":[{"name":"orgId","in":"path","required":true,"description":"Organizasyon UUID","schema":{"type":"string"}},{"name":"memberId","in":"path","required":true,"description":"Üyelik UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/users":{"get":{"operationId":"users-list","tags":["3. Kullanıcı Yönetimi (Users)"],"summary":"Kullanıcıları ara ve listele","description":"Ad soyad, e-posta, telefon veya 11 haneli TC Kimlik No (HMAC-SHA256 kör indeks) ile kullanıcı arar.\n\n**Yetkili Roller:** `PLATFORM_ADMIN`, `SUPER_ADMIN`","security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","required":false,"description":"Ad, e-posta veya telefon araması","schema":{"type":"string"}},{"name":"nationalId","in":"query","required":false,"description":"11 haneli TC Kimlik No ile tam eşleşme","schema":{"type":"string"}},{"name":"buildingId","in":"query","required":false,"description":"Belirli binadaki kullanıcıları filtrele","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"post":{"operationId":"users-create","tags":["3. Kullanıcı Yönetimi (Users)"],"summary":"Yeni kullanıcı oluştur (AES-256-GCM TCKN şifreleme destekli)","description":"TC Kimlik No gönderilirse resmi 11 hane algoritmasıyla doğrulanır, AES-256-GCM ile şifrelenerek saklanır ve HMAC-SHA256 ile indekslenir.\n\n**Yetkili Roller:** `PLATFORM_ADMIN`, `SUPER_ADMIN`","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"email":"ahmet.yilmaz@example.com","fullName":"Ahmet Yılmaz","phone":"+905324445566","password":"ResidentPassword123!","nationalId":"10000000146"}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/users/{userId}":{"get":{"operationId":"users-detail","tags":["3. Kullanıcı Yönetimi (Users)"],"summary":"Kullanıcı detayı (`?revealNationalId=true` ile TCKN çözme)","description":"TCKN varsayılan olarak maskeli (`*******0146`) döner; yetkili yönetici `?revealNationalId=true` gönderirse AES-256-GCM ile çözülür.\n\n**Yetkili Roller:** `PLATFORM_ADMIN`, `SUPER_ADMIN`, `SELF`","security":[{"bearerAuth":[]}],"parameters":[{"name":"userId","in":"path","required":true,"description":"Kullanıcı UUID","schema":{"type":"string"}},{"name":"revealNationalId","in":"query","required":false,"description":"TC Kimlik No şifresini çöz","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"patch":{"operationId":"users-update","tags":["3. Kullanıcı Yönetimi (Users)"],"summary":"Kullanıcı bilgilerini güncelle","description":"Ad soyad, telefon, TCKN veya aktiflik durumunu günceller.\n\n**Yetkili Roller:** `PLATFORM_ADMIN`, `SUPER_ADMIN`, `SELF`","security":[{"bearerAuth":[]}],"parameters":[{"name":"userId","in":"path","required":true,"description":"Kullanıcı UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"fullName":"Ahmet Yılmaz","phone":"+905324445599"}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings":{"get":{"operationId":"buildings-list","tags":["4. Binalar, Bloklar, Görevliler & Dashboard"],"summary":"Erişim yetkisi olunan binaları listele","description":"Kullanıcının yönetici, görevli veya daire sakini olduğu tüm binaları sayfalı olarak listeler.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"query","required":false,"description":"Yönetim şirketi UUID filtresi","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Bina adı, il veya ilçe araması","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"post":{"operationId":"buildings-create","tags":["4. Binalar, Bloklar, Görevliler & Dashboard"],"summary":"Yeni bina/site oluştur (Otomatik blok ve kasa açılış fişi)","description":"Bina oluşturur, initialBlocks verilmezse otomatik \"Ana Blok\" açar ve openingBalance > 0 ise kasa defterine OPENING_BALANCE hareketi yazar.\n\n**Yetkili Roller:** `SUPER_ADMIN`","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"organizationId":"00000000-0000-7000-8000-000000000001","name":"Çamlıca Prestij Konutları","address":"Kısıklı Mah. Çamlıca Cad. No: 42","city":"İstanbul","district":"Üsküdar","taxOffice":"Üsküdar","taxNumber":"1122334455","decisionBookNo":"2026/01","iban":"TR330006100519786457841326","bankName":"Garanti BBVA","openingBalance":5000000,"duesDay":1,"duesDueDays":10,"duesCalculationMethod":"FIXED","defaultMonthlyDues":150000,"autoAccrualEnabled":true,"lateFeeRateBps":500,"lateFeeGraceDays":5,"lateFeeEnabled":true,"initialBlocks":[{"name":"A Blok","floorCount":10,"sortOrder":1},{"name":"B Blok","floorCount":10,"sortOrder":2}]}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}":{"get":{"operationId":"buildings-detail","tags":["4. Binalar, Bloklar, Görevliler & Dashboard"],"summary":"Bina detayı, bloklar ve kullanıcının binadaki yetki özeti","description":"Bina ayarlarını, blok listesini, daire/sakin sayılarını ve myAccess yetki nesnesini döner.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"patch":{"operationId":"buildings-update","tags":["4. Binalar, Bloklar, Görevliler & Dashboard"],"summary":"Bina ayarlarını (aidat günü, gecikme oranı, IBAN vb.) güncelle","description":"Bina bilgilerini günceller ve audit_logs tablosuna kayıt düşer.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"defaultMonthlyDues":175000,"lateFeeRateBps":500,"iban":"TR330006100519786457841326"}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/dashboard":{"get":{"operationId":"buildings-dashboard","tags":["4. Binalar, Bloklar, Görevliler & Dashboard"],"summary":"Frontend Ana Sayfa (Dashboard) özeti — Tek çağrıda tüm bina istatistikleri","description":"Daire doluluk oranları, kasa bakiyesi, ödenmemiş/gecikmiş aidat toplamı, onay bekleyen ödemeler, açık görevler, acil arızalar, son 5 duyuru ve okunmamış bildirim sayısını tek sorguda döner.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/blocks":{"get":{"operationId":"buildings-blocks-list","tags":["4. Binalar, Bloklar, Görevliler & Dashboard"],"summary":"Binadaki blokları ve daire sayılarını listele","description":"Binaya ait blokları daire sayılarıyla birlikte döner.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"post":{"operationId":"buildings-blocks-create","tags":["4. Binalar, Bloklar, Görevliler & Dashboard"],"summary":"Binaya yeni blok ekle","description":"Yeni blok (örn. C Blok) ekler.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"name":"C Blok","floorCount":8,"sortOrder":3}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/blocks/{blockId}":{"patch":{"operationId":"buildings-blocks-update","tags":["4. Binalar, Bloklar, Görevliler & Dashboard"],"summary":"Blok bilgilerini güncelle","description":"Blok adını, kat sayısını veya sıralamasını günceller.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"blockId","in":"path","required":true,"description":"Blok UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"name":"C Blok (Güney)","floorCount":9}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"delete":{"operationId":"buildings-blocks-delete","tags":["4. Binalar, Bloklar, Görevliler & Dashboard"],"summary":"Boş bloğu sil","description":"İçinde bağımsız bölüm (daire) bulunmayan bloğu siler.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"blockId","in":"path","required":true,"description":"Blok UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/staff":{"get":{"operationId":"buildings-staff-list","tags":["4. Binalar, Bloklar, Görevliler & Dashboard"],"summary":"Bina yöneticilerini (BUILDING_MANAGER) ve görevlileri (STAFF) listele","description":"Binada görevli tüm personel ve yöneticileri listeler.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"post":{"operationId":"buildings-staff-assign","tags":["4. Binalar, Bloklar, Görevliler & Dashboard"],"summary":"Binaya yönetici (BUILDING_MANAGER) veya personel (STAFF) ata","description":"Mevcut userId ile veya newUser nesnesiyle yeni kullanıcı açarak binaya atama yapar.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"role":"STAFF","title":"Apartman Görevlisi & Teknik Bakım","newUser":{"email":"gorevli@camlicaprestij.com","fullName":"Mustafa Kaya","phone":"+905336667788","password":"StaffPassword123!"}}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/staff/{staffId}":{"patch":{"operationId":"buildings-staff-update","tags":["4. Binalar, Bloklar, Görevliler & Dashboard"],"summary":"Görevli unvanını veya çalışma durumunu güncelle","description":"Bina görevli kaydını günceller.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"staffId","in":"path","required":true,"description":"Görevli atama UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"title":"Baş Görevli","isActive":true}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"delete":{"operationId":"buildings-staff-remove","tags":["4. Binalar, Bloklar, Görevliler & Dashboard"],"summary":"Bina görevlisinin görevini sonlandır","description":"Görevli atamasını pasife alır ve çıkış tarihini kaydeder.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"staffId","in":"path","required":true,"description":"Görevli atama UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/audit-logs":{"get":{"operationId":"buildings-audit-logs","tags":["4. Binalar, Bloklar, Görevliler & Dashboard"],"summary":"Bina denetim kayıtlarını (Audit Logs) listele","description":"Binada yapılan kritik işlemlerin kim tarafından ne zaman yapıldığını sayfalı listeler.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"action","in":"query","required":false,"description":"İşlem kodu filtresi (örn: building.update)","schema":{"type":"string"}},{"name":"entityType","in":"query","required":false,"description":"Varlık tipi (örn: payment, expense)","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/units":{"get":{"operationId":"units-list","tags":["5. Bağımsız Bölümler / Daireler (Units)"],"summary":"Binadaki daireleri (aktif ev sahibi ve kiracı özetiyle) listele","description":"Yönetici ve görevliler tüm daireleri; sakinler (RESIDENT) yalnızca kendi dairelerini görür.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"blockId","in":"query","required":false,"description":"Blok UUID filtresi","schema":{"type":"string"}},{"name":"occupancyStatus","in":"query","required":false,"description":"OCCUPIED | VACANT","schema":{"type":"string"}},{"name":"unitType","in":"query","required":false,"description":"1+1 | 2+1 | 3+1 | 4+1 | SHOP | OFFICE","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"post":{"operationId":"units-create","tags":["5. Bağımsız Bölümler / Daireler (Units)"],"summary":"Tekil daire / bağımsız bölüm oluştur","description":"Blok, kat, kapı numarası, daire tipi, m² ve arsa payı ile yeni daire ekler.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"blockId":"00000000-0000-7000-8000-000000000002","floor":3,"doorNumber":"12","unitType":"3+1","areaSqm":140,"landShare":120,"occupancyStatus":"VACANT"}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/units/bulk":{"post":{"operationId":"units-bulk-create","tags":["5. Bağımsız Bölümler / Daireler (Units)"],"summary":"Tek seferde toplu daire oluştur (100 daireye kadar atomik)","description":"Site kurulumunda tüm daireleri tek istekte atomik olarak oluşturur.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"units":[{"blockId":"00000000-0000-7000-8000-000000000002","floor":1,"doorNumber":"1","unitType":"2+1","areaSqm":100,"landShare":100},{"blockId":"00000000-0000-7000-8000-000000000002","floor":1,"doorNumber":"2","unitType":"3+1","areaSqm":150,"landShare":150}]}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/units/{unitId}":{"get":{"operationId":"units-detail","tags":["5. Bağımsız Bölümler / Daireler (Units)"],"summary":"Daire detayı ve geçmişten bugüne tüm sakin (malik/kiracı) tarihçesi","description":"Daire bilgilerini ve o dairede oturmuş/oturan tüm malik ve kiracı kayıtlarını döner.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT (Kendi Dairesi)`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"unitId","in":"path","required":true,"description":"Daire UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"patch":{"operationId":"units-update","tags":["5. Bağımsız Bölümler / Daireler (Units)"],"summary":"Daire bilgilerini güncelle","description":"Metrekare, arsa payı, özel aidat tutarı veya doluluk durumunu günceller.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"unitId","in":"path","required":true,"description":"Daire UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"areaSqm":145,"monthlyDuesOverride":180000}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/residents":{"get":{"operationId":"residents-building-list","tags":["6. Sakinler: Ev Sahibi & Kiracı Yönetimi"],"summary":"Binadaki tüm malik ve kiracıları listele","description":"Aktif veya taşınmış (`activeOnly=false`) tüm ev sahipleri ve kiracıları listeler.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"residentType","in":"query","required":false,"description":"OWNER | TENANT","schema":{"type":"string"}},{"name":"activeOnly","in":"query","required":false,"description":"Yalnızca aktif oturanlar (varsayılan: true)","schema":{"type":"boolean"}},{"name":"q","in":"query","required":false,"description":"Ad soyad, e-posta, telefon veya kapı no araması","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/units/{unitId}/residents":{"get":{"operationId":"residents-unit-list","tags":["6. Sakinler: Ev Sahibi & Kiracı Yönetimi"],"summary":"Belirli bir dairenin malik ve kiracı geçmişini listele","description":"Dairedeki aktif ve geçmiş ev sahibi/kiracı kayıtlarını giriş-çıkış tarihleriyle döner.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT (Kendi Dairesi)`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"unitId","in":"path","required":true,"description":"Daire UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"post":{"operationId":"residents-assign","tags":["6. Sakinler: Ev Sahibi & Kiracı Yönetimi"],"summary":"Daireye Ev Sahibi (OWNER) veya Kiracı (TENANT) ata / devret","description":"replaceExisting: true gönderildiğinde mevcut kiracının/malikin çıkış tarihini otomatik kapatır ve yeni sakini başlatır; böylece eski kiracının borcu ile yeni kiracının borcu birbirine karışmaz.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"unitId","in":"path","required":true,"description":"Daire UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"residentType":"TENANT","moveInDate":"2026-11-01","isPrimaryContact":true,"replaceExisting":true,"newUser":{"email":"kiraci@example.com","fullName":"Zeynep Kaya","phone":"+905441112233","password":"TenantPassword123!","nationalId":"10000000146"}}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/residents/{residencyId}":{"patch":{"operationId":"residents-update","tags":["6. Sakinler: Ev Sahibi & Kiracı Yönetimi"],"summary":"Sakinlik kaydını (hisse oranı, giriş tarihi, notlar) güncelle","description":"Sakin eşleştirme kaydının detaylarını günceller.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"residencyId","in":"path","required":true,"description":"Sakinlik (unit_residents) UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"shareRatioBps":10000,"isPrimaryContact":true,"notes":"Kira sözleşmesi yenilendi"}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/residents/{residencyId}/move-out":{"post":{"operationId":"residents-move-out","tags":["6. Sakinler: Ev Sahibi & Kiracı Yönetimi"],"summary":"Kiracı veya malik çıkış (taşınma) işlemi","description":"moveOutDate kaydederek aktif sakinliği sonlandırır. Dairede başka aktif sakin kalmadıysa daire durumunu otomatik VACANT yapar.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"residencyId","in":"path","required":true,"description":"Sakinlik UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"moveOutDate":"2026-11-15","notes":"Anahtar teslim alındı"}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/accruals/batches":{"get":{"operationId":"finance-batches-list","tags":["7. Finans: Aidat, Tahsilat, Gider & Cari Ekstre"],"summary":"Toplu borçlandırma (aidat/demirbaş/yakıt) partilerini listele","description":"Binada yapılan tüm toplu tahakkuk partilerini listeler.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"post":{"operationId":"finance-batches-create","tags":["7. Finans: Aidat, Tahsilat, Gider & Cari Ekstre"],"summary":"Toplu Aidat / Ek Bütçe / Demirbaş / Yakıt borçlandırması oluştur","description":"EQUAL (eşit), BY_AREA (m²), BY_LAND_SHARE (arsa payı) veya FIXED_PER_UNIT yöntemleriyle ve OWNER | TENANT | OCCUPANT muhatap seçimiyle kuruş farkı bırakmadan toplu tahakkuk oluşturur.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"title":"2026 Kasım Ayı Genel Aidatı","period":"2026-11","type":"MONTHLY_DUES","calculationMethod":"FIXED_PER_UNIT","chargeTo":"OCCUPANT","totalAmount":150000,"dueDate":"2026-11-10","includeVacantUnits":true}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/accruals":{"get":{"operationId":"finance-accruals-list","tags":["7. Finans: Aidat, Tahsilat, Gider & Cari Ekstre"],"summary":"Borç tahakkuk kalemlerini listele","description":"Yöneticiler tüm dairelerin borçlarını; sakinler yalnızca kendi dairelerinin/kendilerine ait borçları görür.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"unitId","in":"query","required":false,"description":"Daire UUID filtresi","schema":{"type":"string"}},{"name":"debtorUserId","in":"query","required":false,"description":"Borçlu kullanıcı UUID filtresi","schema":{"type":"string"}},{"name":"period","in":"query","required":false,"description":"Dönem (YYYY-MM)","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"UNPAID | PARTIALLY_PAID | PAID | CANCELLED","schema":{"type":"string"}},{"name":"overdueOnly","in":"query","required":false,"description":"Yalnızca vadesi geçmiş borçlar","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"post":{"operationId":"finance-accruals-create","tags":["7. Finans: Aidat, Tahsilat, Gider & Cari Ekstre"],"summary":"Tekil daire borçlandırması oluştur","description":"Belirli bir daireye özel borç kalemi ekler.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"unitId":"00000000-0000-7000-8000-000000000003","type":"OTHER","chargeTo":"OCCUPANT","period":"2026-11","title":"Kırılan Otopark Kumandası Bedeli","amount":45000,"dueDate":"2026-11-20"}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/accruals/{accrualId}/cancel":{"post":{"operationId":"finance-accruals-cancel","tags":["7. Finans: Aidat, Tahsilat, Gider & Cari Ekstre"],"summary":"Tahakkuk kalemini iptal et","description":"Henüz ödeme mahsup edilmemiş (paidAmount === 0) borç kalemini iptal eder.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"accrualId","in":"path","required":true,"description":"Tahakkuk UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/payments":{"get":{"operationId":"finance-payments-list","tags":["7. Finans: Aidat, Tahsilat, Gider & Cari Ekstre"],"summary":"Tahsilat ve ödeme bildirimlerini listele","description":"PENDING, APPROVED ve REJECTED tüm ödemeleri filtreli listeler.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"PENDING | APPROVED | REJECTED","schema":{"type":"string"}},{"name":"unitId","in":"query","required":false,"description":"Daire UUID filtresi","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"post":{"operationId":"finance-payments-create","tags":["7. Finans: Aidat, Tahsilat, Gider & Cari Ekstre"],"summary":"Ödeme bildirimi (Sakin dekont yükleme) veya Doğrudan Tahsilat (Yönetici)","description":"Sakin kendi dairesi için R2 dekontu (receiptFileId) ile PENDING ödeme bildirir. Yönetici autoApprove: true ile anında onaylı tahsilat girebilir.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"unitId":"00000000-0000-7000-8000-000000000003","amount":150000,"method":"BANK_TRANSFER","referenceNo":"EFT-20261113-001","receiptFileId":"00000000-0000-7000-8000-000000000099","autoApprove":false}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/payments/{paymentId}":{"get":{"operationId":"finance-payments-detail","tags":["7. Finans: Aidat, Tahsilat, Gider & Cari Ekstre"],"summary":"Ödeme detayı ve mahsup edilen borç kalemleri (payment_allocations)","description":"Ödemenin hangi aidat/borç kalemlerine ne kadar mahsup edildiğini gösterir.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"paymentId","in":"path","required":true,"description":"Ödeme UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/payments/{paymentId}/review":{"post":{"operationId":"finance-payments-review","tags":["7. Finans: Aidat, Tahsilat, Gider & Cari Ekstre"],"summary":"Ödeme onaylama (FIFO parçalı mahsup + kasaya işleme) veya reddetme","description":"APPROVED seçildiğinde ödeme tutarını en eski vadeli açık borçlardan başlayarak (FIFO) parçalı/tam mahsup eder, kasa defterine IN kaydı atar ve bina kasasını artırır.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"paymentId","in":"path","required":true,"description":"Ödeme UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"decision":"APPROVED"}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/expense-categories":{"get":{"operationId":"finance-expense-categories-list","tags":["7. Finans: Aidat, Tahsilat, Gider & Cari Ekstre"],"summary":"Gider kategorilerini listele (11 sistem kategorisi + binaya özel)","description":"Elektrik, Su, Doğalgaz, Asansör Bakımı, Personel Maaşı vb. gider kategorilerini döner.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"post":{"operationId":"finance-expense-categories-create","tags":["7. Finans: Aidat, Tahsilat, Gider & Cari Ekstre"],"summary":"Binaya özel yeni gider kategorisi ekle","description":"Binaya özel gider kalemi tanımlar.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"code":"POOL_MAINTENANCE","name":"Havuz Kimyasal & Bakım Gideri","description":"Sezonluk havuz bakım harcamaları"}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/expenses":{"get":{"operationId":"finance-expenses-list","tags":["7. Finans: Aidat, Tahsilat, Gider & Cari Ekstre"],"summary":"Bina giderlerini listele","description":"Tarih aralığı ve kategori filtreli bina gider listesi.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"post":{"operationId":"finance-expenses-create","tags":["7. Finans: Aidat, Tahsilat, Gider & Cari Ekstre"],"summary":"Yeni bina gideri kaydet (Fatura R2 dosyası + Kasadan otomatik düşme)","description":"Gideri kaydeder, cash_transactions tablosuna OUT hareketi yazar ve bina kasa bakiyesini atomik olarak düşürür.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"categoryId":"cat_electricity","title":"Kasım 2026 Ortak Alan Elektrik Faturası","vendorName":"CK Boğaziçi Elektrik","invoiceNo":"ELK-2026-11902","amount":120000,"expenseDate":"2026-11-12","paymentMethod":"BANK_TRANSFER"}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/expenses/{expenseId}/cancel":{"post":{"operationId":"finance-expenses-cancel","tags":["7. Finans: Aidat, Tahsilat, Gider & Cari Ekstre"],"summary":"Gider kaydını iptal et (Kasaya otomatik iade / EXPENSE_REVERSAL)","description":"Gideri iptal eder ve kasa defterine ters kayıt atarak tutarı kasaya iade eder.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"expenseId","in":"path","required":true,"description":"Gider UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/units/{unitId}/statement":{"get":{"operationId":"finance-unit-statement","tags":["7. Finans: Aidat, Tahsilat, Gider & Cari Ekstre"],"summary":"Daire ve Kişi Bazlı Cari Hesap Ekstresi (Yürüyen Bakiyeli)","description":"Dairenin tüm borç ve ödemelerini kronolojik yürüyen bakiyeyle (runningBalance) döner. ?debtorUserId=... parametresiyle eski kiracı, yeni kiracı ve ev sahibi ekstreleri ayrı ayrı alınabilir.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `RESIDENT (Kendi Dairesi)`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"unitId","in":"path","required":true,"description":"Daire UUID","schema":{"type":"string"}},{"name":"debtorUserId","in":"query","required":false,"description":"Belirli bir malik/kiracı için filtrele","schema":{"type":"string"}},{"name":"fromDate","in":"query","required":false,"description":"Başlangıç tarihi (YYYY-MM-DD)","schema":{"type":"string"}},{"name":"toDate","in":"query","required":false,"description":"Bitiş tarihi (YYYY-MM-DD)","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/finance/summary":{"get":{"operationId":"finance-building-summary","tags":["7. Finans: Aidat, Tahsilat, Gider & Cari Ekstre"],"summary":"Bina Geneli Gelir-Gider Bilançosu & Kasa Mutabakatı","description":"Açılış bakiyesi, toplam tahsilat, toplam gider, güncel kasa bakiyesi, toplam alacak, vadesi geçmiş alacak ve kategori bazlı gider dağılımını döner.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/files":{"get":{"operationId":"files-list","tags":["8. Cloudflare R2 Dosya Yükleme & İndirme"],"summary":"Binaya yüklenmiş R2 dosyalarını listele","description":"Dekont, gider faturası, görev kanıt fotoğrafı ve arıza görsellerini listeler.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"PAYMENT_RECEIPT | EXPENSE_INVOICE | TASK_PROOF | TICKET_ATTACHMENT | ANNOUNCEMENT_ATTACHMENT | BUILDING_DOCUMENT","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/files/direct":{"post":{"operationId":"files-direct-upload","tags":["8. Cloudflare R2 Dosya Yükleme & İndirme"],"summary":"Cloudflare R2 Direct Upload (multipart/form-data)","description":"Dosyayı doğrudan Worker üzerinden R2 Bucket içerisine yazar. Alanlar: file (Binary), category, isPublic.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"example":{"category":"PAYMENT_RECEIPT","isPublic":"false","file":"<Binary File (image/jpeg, image/png, image/webp, application/pdf)>"}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/files/presigned":{"post":{"operationId":"files-presigned-url","tags":["8. Cloudflare R2 Dosya Yükleme & İndirme"],"summary":"Cloudflare R2 S3 Presigned PUT URL oluştur (aws4fetch)","description":"İstemcinin dosyayı doğrudan R2 S3 API uç noktasına yüklemesi için imzalı URL (veya S3 anahtarları tanımlı değilse Direct Fallback bilgisi) döner.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"category":"TASK_PROOF","originalName":"merdiven-temizlik.jpg","mimeType":"image/jpeg","sizeBytes":245000,"isPublic":false}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/files/{fileId}/confirm":{"post":{"operationId":"files-confirm","tags":["8. Cloudflare R2 Dosya Yükleme & İndirme"],"summary":"Presigned URL ile yüklenen dosyayı doğrula ve aktifleştir","description":"R2 üzerinde BUCKET.head() ile dosyanın varlığını kontrol eder ve durumunu UPLOADED yapar.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"fileId","in":"path","required":true,"description":"Dosya UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/files/{fileId}/download":{"get":{"operationId":"files-download","tags":["8. Cloudflare R2 Dosya Yükleme & İndirme"],"summary":"R2 dosyasını indir / görüntüle","description":"Yetki kontrolü sonrası dosyayı Cloudflare R2 üzerinden stream olarak sunar.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"fileId","in":"path","required":true,"description":"Dosya UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/task-templates":{"get":{"operationId":"tasks-templates-list","tags":["9. Operasyon, Temizlik & Bakım Görevleri"],"summary":"Periyodik görev şablonlarını (Günlük/Haftalık/Aylık) listele","description":"Cron tarafından otomatik üretilen rutin temizlik/bakım şablonlarını listeler.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"post":{"operationId":"tasks-templates-create","tags":["9. Operasyon, Temizlik & Bakım Görevleri"],"summary":"Yeni periyodik temizlik/bakım şablonu oluştur","description":"DAILY, WEEKLY veya MONTHLY periyotlu rutin görev şablonu oluşturur.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"title":"Günlük Merdiven & Asansör Kabini Temizliği","description":"Tüm kat sahanlıkları ve asansör aynalarının silinmesi","category":"CLEANING","frequency":"DAILY","requiresPhotoProof":true}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/task-templates/{templateId}":{"patch":{"operationId":"tasks-templates-update","tags":["9. Operasyon, Temizlik & Bakım Görevleri"],"summary":"Periyodik görev şablonunu güncelle","description":"Şablonun görevlisini, kanıt fotoğrafı zorunluluğunu veya aktifliğini günceller.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"templateId","in":"path","required":true,"description":"Şablon UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"requiresPhotoProof":true,"isActive":true}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/tasks":{"get":{"operationId":"tasks-list","tags":["9. Operasyon, Temizlik & Bakım Görevleri"],"summary":"Görevleri listele","description":"Durum (PENDING, IN_PROGRESS, COMPLETED, CANCELLED), kategori ve görevli filtreli liste.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"PENDING | IN_PROGRESS | COMPLETED | CANCELLED","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"CLEANING |GARBAGE |BOILER |GARDEN |ELEVATOR","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"post":{"operationId":"tasks-create","tags":["9. Operasyon, Temizlik & Bakım Görevleri"],"summary":"Görevliye yeni görev ata","description":"Görev oluşturur ve atanan STAFF personeline otomatik bildirim gönderir.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"title":"Kazan Dairesi Hidrofor Basınç Kontrolü","description":"Manometre değerinin kontrol edilip fotoğrafının yüklenmesi","category":"BOILER","priority":"HIGH","dueDate":"2026-11-15","requiresPhotoProof":true}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/tasks/{taskId}":{"get":{"operationId":"tasks-detail","tags":["9. Operasyon, Temizlik & Bakım Görevleri"],"summary":"Görev detayı ve yüklenen R2 kanıt fotoğrafları","description":"Görevin tüm bilgilerini ve task_proofs tablosundaki R2 fotoğraflarını döner.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"taskId","in":"path","required":true,"description":"Görev UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/tasks/{taskId}/status":{"patch":{"operationId":"tasks-status-update","tags":["9. Operasyon, Temizlik & Bakım Görevleri"],"summary":"Görev durumunu güncelle (Zorunlu R2 kanıt fotoğrafı doğrulamalı)","description":"requiresPhotoProof: true olan görev COMPLETED yapılırken proofFileIds içinde en az 1 adet TASK_PROOF R2 dosyası zorunludur; aksi halde 422 PROOF_PHOTO_REQUIRED döner.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"taskId","in":"path","required":true,"description":"Görev UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"status":"COMPLETED","completionNote":"Hidrofor basıncı 4.2 bar olarak ölçüldü ve fotoğraflandı.","proofFileIds":["00000000-0000-7000-8000-000000000088"]}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/tickets":{"get":{"operationId":"tickets-list","tags":["10. Arıza / Talep (Ticket) Yönetimi"],"summary":"Arıza ve talepleri listele","description":"Öncelik (LOW, MEDIUM, HIGH, URGENT) ve durum filtreli arıza kayıtları.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"OPEN | IN_PROGRESS | WAITING_PARTS | RESOLVED | CLOSED","schema":{"type":"string"}},{"name":"priority","in":"query","required":false,"description":"LOW | MEDIUM | HIGH | URGENT","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"post":{"operationId":"tickets-create","tags":["10. Arıza / Talep (Ticket) Yönetimi"],"summary":"Yeni arıza / talep (Ticket) oluştur (Fotoğraf ekleme destekli)","description":"Sakin kendi dairesi veya ortak alan için arıza kaydı açar; bina yöneticilerine otomatik bildirim gider.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"title":"3. Kat Koridor Sensörlü Lamba Yanmıyor","description":"Asansör önündeki aydınlatma sensörü devreye girmiyor.","category":"ELECTRICAL","priority":"HIGH","attachmentFileIds":[]}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/tickets/{ticketId}":{"get":{"operationId":"tickets-detail","tags":["10. Arıza / Talep (Ticket) Yönetimi"],"summary":"Arıza detayı, fotoğraflar, yorumlar ve durum güncelleme tarihçesi (ticket_events)","description":"Arızanın tüm yaşam döngüsünü döner. isInternal: true olan personel iç notları sakinlerden otomatik gizlenir.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"ticketId","in":"path","required":true,"description":"Arıza UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/tickets/{ticketId}/assign":{"post":{"operationId":"tickets-assign","tags":["10. Arıza / Talep (Ticket) Yönetimi"],"summary":"Arızayı bina görevlisine (STAFF) ata","description":"Görevliye atama yapar, durumu IN_PROGRESS yapar ve görevliye bildirim gönderir.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"ticketId","in":"path","required":true,"description":"Arıza UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"assignedStaffId":"00000000-0000-7000-8000-000000000055","note":"Lütfen bugün kontrol edip sensörü değiştirin."}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/tickets/{ticketId}/status":{"patch":{"operationId":"tickets-status-update","tags":["10. Arıza / Talep (Ticket) Yönetimi"],"summary":"Arıza durumunu güncelle (RESOLVED, WAITING_PARTS, CLOSED vb.)","description":"Durum değişikliğini ticket_events geçmişine yazar ve talep sahibi sakine bildirim gönderir.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"ticketId","in":"path","required":true,"description":"Arıza UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"status":"RESOLVED","resolutionNote":"Koridor sensörlü LED armatür yenisiyle değiştirildi."}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/tickets/{ticketId}/comments":{"post":{"operationId":"tickets-comments-create","tags":["10. Arıza / Talep (Ticket) Yönetimi"],"summary":"Arıza kaydına yorum, iç not (`isInternal`) veya fotoğraf ekle","description":"Yorum veya personel arası iç not ekler.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"ticketId","in":"path","required":true,"description":"Arıza UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"body":"Yedek parça sipariş edildi, yarın sabah montajı yapılacak.","isInternal":false}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/announcements":{"get":{"operationId":"announcements-list","tags":["11. Duyuru & Bildirim Sistemi"],"summary":"Duyuruları listele (Hedef kitle izolasyonlu: ALL, OWNERS, TENANTS, STAFF)","description":"Kullanıcının binadaki rolüne göre yalnızca görmeye yetkili olduğu duyuruları ve okundu bilgisini (isRead) döner.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}},"post":{"operationId":"announcements-create","tags":["11. Duyuru & Bildirim Sistemi"],"summary":"Yeni duyuru yayınla (Tüm sakinlere veya sadece Ev Sahiplerine / Kiracılara)","description":"sendNotification: true ise seçilen hedef kitledeki (ALL | OWNERS | TENANTS | STAFF) kullanıcılara otomatik bildirim üretir.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"title":"2026 Yılı Olağan Genel Kurul Toplantı Çağrısı","content":"Kat Malikleri Kurulu toplantımız 25 Kasım Pazar saat 14:00’te toplantı salonunda yapılacaktır.","audience":"OWNERS","isPinned":true,"sendNotification":true}}}},"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/announcements/{announcementId}":{"get":{"operationId":"announcements-detail","tags":["11. Duyuru & Bildirim Sistemi"],"summary":"Duyuru detayı ve ekli R2 dosyaları","description":"Hedef kitle yetkisi doğrulanarak duyuru detayını döner.\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"announcementId","in":"path","required":true,"description":"Duyuru UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/buildings/{buildingId}/announcements/{announcementId}/read":{"post":{"operationId":"announcements-mark-read","tags":["11. Duyuru & Bildirim Sistemi"],"summary":"Duyuruyu okundu olarak işaretle","description":"announcement_reads tablosuna okundu kaydı düşer (idempotent).\n\n**Yetkili Roller:** `SUPER_ADMIN`, `BUILDING_MANAGER`, `STAFF`, `RESIDENT`","security":[{"bearerAuth":[]}],"parameters":[{"name":"buildingId","in":"path","required":true,"description":"Bina UUID","schema":{"type":"string"}},{"name":"announcementId","in":"path","required":true,"description":"Duyuru UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/notifications":{"get":{"operationId":"notifications-list","tags":["11. Duyuru & Bildirim Sistemi"],"summary":"Kullanıcının bildirimlerini ve okunmamış bildirim sayısını listele","description":"Aidat, ödeme onayı/reddi, görev ataması, arıza güncellemesi ve duyuru bildirimlerini döner.\n\n**Yetkili Roller:** `ANY_AUTHENTICATED`","security":[{"bearerAuth":[]}],"parameters":[{"name":"unreadOnly","in":"query","required":false,"description":"Yalnızca okunmamış bildirimler","schema":{"type":"boolean"}},{"name":"buildingId","in":"query","required":false,"description":"Bina UUID filtresi","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/notifications/{notificationId}/read":{"post":{"operationId":"notifications-mark-read","tags":["11. Duyuru & Bildirim Sistemi"],"summary":"Tek bildirimi okundu olarak işaretle","description":"Bildirimin readAt zaman damgasını günceller.\n\n**Yetkili Roller:** `ANY_AUTHENTICATED`","security":[{"bearerAuth":[]}],"parameters":[{"name":"notificationId","in":"path","required":true,"description":"Bildirim UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}},"/api/v1/notifications/read-all":{"post":{"operationId":"notifications-read-all","tags":["11. Duyuru & Bildirim Sistemi"],"summary":"Tüm bildirimleri okundu olarak işaretle","description":"Kullanıcının tüm okunmamış bildirimlerini tek seferde okundu yapar.\n\n**Yetkili Roller:** `ANY_AUTHENTICATED`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Standart Başarılı Yanıt Zarfı","content":{"application/json":{"example":{"success":true,"data":{},"error":null}}}}}}}}}