# Yuz Tanima Kisiler Galerisi - Google Photos Tarzi Tasarim

## Ozet

Soyagaci kisiler sayfasinin Google Photos "People & Pets" deneyimine benzer sekilde tamamen yeniden yazilmasi. Cok kullanicili, kullanici bazli etiketleme, paylasimda fallback cozumleme, admin panelinde global yonetim.

## Kararlar

| Karar | Secim |
|-------|-------|
| Kapsam | Tam yeniden yazim (Google Photos klonu) |
| Veri modeli | Hibrit: ortak embedding + kullaniciya ozel etiketler |
| Paylasim davranisi | Goruntuleyenin etiketi > paylasanin etiketi > "Bilinmeyen" |
| Kisi tiklama | Fotograf galerisi (Google Photos) → "Profil Sayfasi" butonu ile gecis |
| Birlestirme onerileri | Inline kartlar (grid ustunde) |
| Admin panel | Global havuz + kullanici bazli gorunum + istatistikler + ayarlar |
| Isleme pipeline | Backend kuyruk sistemi + Socket.IO push |
| API pattern | Mevcut FikoYTIstekKok + DbBaseService (ozel endpoint yok) |
| Mimari yaklasim | Bagimsiz yuz tanima modulu (Yaklasim 2) |

## 1. Veri Modeli & Koleksiyonlar

### yuz_embeddingler (Global havuz)

```
{
  _id,
  resimId,              // GridFS resim referansi
  kaynakTip,            // 'paylasim' | 'soyagaci' | 'profil'
  kaynakId,             // hareketler._id veya soyAgaciKisiler._id
  kaynakSahibiId,       // resmi yukleyen kullanici
  yuzler: [{
    index,              // yuz sirasi (0, 1, 2...)
    bbox: {x, y, w, h}, // % koordinatlar
    embedding: [...],   // 512-dim float array (InsightFace)
    guven,              // tespit guveni (0-1)
    kisiGrupId,         // otomatik gruplanan kume ID'si
  }],
  durum,                // 'kuyrukta' | 'isleniyor' | 'tamamlandi' | 'hata'
  islemTarihi,
  olusturmaTarihi
}
```

### yuz_kisi_gruplari (Global - embedding kumeleri)

```
{
  _id,
  temsilciEmbedding: [...],   // Kumenin merkez embedding'i
  yuzSayisi,                   // Toplam yuz adedi
  ornekResimler: [{resimId, bbox}],  // En iyi 5 ornek
  birlestirmeler: [grupId],    // Birlestirilmis eski gruplar
  olusturmaTarihi
}
```

### yuz_kullanici_etiketleri (Kullaniciya ozel)

```
{
  _id,
  kullaniciId,
  kisiGrupId,            // yuz_kisi_gruplari._id
  isim,                  // Kullanicinin verdigi isim
  soyagaciKisiId?,       // Soyagaci kisisine baglanti (opsiyonel)
  resimUrl?,             // Ozel avatar (yoksa otomatik crop)
  gizli,                 // Kullanici bu grubu gizledi mi
  olusturmaTarihi,
  guncellemeTarihi
}
```

### yuz_birlestirme_onerileri (Kullaniciya ozel)

```
{
  _id,
  kullaniciId,
  grup1Id,
  grup2Id,
  benzerlik,             // Embedding mesafesi (0-1)
  durum,                 // 'beklemede' | 'onaylandi' | 'reddedildi'
  olusturmaTarihi
}
```

### yuz_islem_kuyrugu (Backend kuyruk)

```
{
  _id,
  resimId,
  kaynakTip, kaynakId, kaynakSahibiId,
  oncelik,               // 1-10 (1 en yuksek)
  durum,                 // 'beklemede' | 'isleniyor' | 'tamamlandi' | 'hata'
  hata?,
  baslamaZamani?, bitisZamani?,
  olusturmaTarihi
}
```

### Etiket Cozumleme Mantigi

```
Goruntuleyen (B) bir fotograftaki yuzu goruyor:
1. B'nin bu kisiGrupId icin etiketi var mi? → B'nin ismi
2. Yoksa, fotograf sahibinin (A) etiketi var mi? → A'nin ismi
3. Yoksa → "Bilinmeyen" + etiketleme butonu
```

## 2. Dosya Yapisi & Modul Organizasyonu

### Yeni Ortak Modul: src/app/uygulamalar/yuz-tanima/

```
yuz-tanima/
├── interfaces/
│   └── yuz-tanima.interface.ts
├── services/
│   ├── yuz-tanima-api.service.ts     // DbBaseService extend, aggregate/ekle/guncelle/sil
│   ├── yuz-gruplama.service.ts       // Etiket cozumleme, birlestirme mantigi
│   └── yuz-kuyruk-socket.service.ts  // Socket.IO kuyruk durumu + push
├── components/
│   ├── yuz-avatar/                   // Yuvarlak yuz crop avatar (buyuk boyutlu)
│   ├── kisi-grid/                    // Google Photos tarzi kisi grid (reusable)
│   ├── birlestirme-karti/            // "Bu ayni kisi mi?" inline kart
│   ├── yuz-etiketleme-popup/        // Fotograf uzerinde yuz bbox + etiketleme popover
│   └── kisi-chip-filtre/            // Chip filter bar
└── utils/
    └── etiket-cozumle.ts
```

### Kullanici Tarafi: src/app/uygulamalar/soyagaci/

```
soyagaci/
├── kisiler-galerisi/                 // BASTAN YAZILACAK
│   └── kisiler-galerisi.component.ts
├── kisi-fotograflari/                // YENI - Google Photos kisi fotograf galerisi
│   └── kisi-fotograflari.component.ts
├── kisi-sayfasi/                     // Mevcut - minor guncelleme
└── ... (mevcut dosyalar korunur)
```

### Admin Panel: src/app/uygulamalar/admin/yuz-tanima/

```
yuz-tanima/
├── yuz-tanima.routes.ts              // GUNCELLENECEK
├── pano/pano.component.ts            // YENI - Dashboard
├── global-havuz/                     // YENI - Tum embedding gruplari
│   └── global-havuz.component.ts
├── kullanici-goruntule/              // YENI - Secili kullanicinin galerisi
│   └── kullanici-goruntule.component.ts
├── kuyruk/kuyruk.component.ts        // Mevcut → guncelle
├── kisiler/kisiler.component.ts      // Mevcut → guncelle
├── tespitler/tespitler.component.ts  // Mevcut → guncelle
├── bilinmeyenler/                    // Mevcut → guncelle
└── ayarlar/ayarlar.component.ts      // Mevcut → guncelle
```

### Route Yapisi

```
/kisiler           → Kisiler galerisi (Google Photos tarzi)
/kisiler/:grupId   → Kisi fotograf galerisi (YENI)
/kisi/:kisiId      → Kisi profil sayfasi (mevcut)

/yuz-tanima/pano              → Admin dashboard
/yuz-tanima/global-havuz      → Global embedding havuzu
/yuz-tanima/kullanici/:userId → Kullanici galeri gorunumu
/yuz-tanima/kuyruk            → Islem kuyrugu
/yuz-tanima/ayarlar           → Sistem ayarlari
```

## 3. Kullanici Tarafi UI

### 3.1 Kisiler Galerisi Ana Sayfasi

Layout ustten alta:
1. **Arama bari** + gorunum toggle (grid/liste)
2. **Hizli erisim seridi** - yatay scroll, en cok fotografli 10 kisi (yuvarlak mini avatar)
3. **Birlestirme onerileri** - inline kartlar (iki avatar yan yana + Ayni/Farkli butonlari)
4. **Chip filtreler** - Tumu / Etiketli / Etiketsiz
5. **Kisi grid** - 80px yuvarlak avatar, yuz crop, isim + fotograf sayisi

Davranislar:
- Siralama: fotograf sayisina gore (en cok → en az)
- Hover: hafif scale + glow efekti
- Tiklama → kisi fotograf galerisi sayfasi
- Etiketsiz: turuncu kenarlik, "Isim Ver" butonu
- Responsive: masaustu 6 sutun → tablet 4 → mobil 3

### 3.2 Kisi Fotograf Galerisi

Layout:
1. **Header** - geri butonu, avatar + isim (inline edit), "Profil Sayfasi" butonu, 3 nokta menu
2. **Chip filtreler** - birlikte gorunenler (mini avatar), yil, konum
3. **Justified photo grid** - aya gore gruplanmis, en-boy orani korunur

Davranislar:
- Fotografa tiklama → lightbox + yuz bbox overlay'leri
- "Profil Sayfasi" → mevcut kisi-sayfasi route'u
- 3 nokta menu: Isim degistir, Soyagaci kisisine bagla, Birlestir, Gizle

### 3.3 Birlestirme Oneri Karti

- Iki yuvarlak avatar yan yana, aralarinda baglanti cizgisi
- Benzerlik yuzdesi
- 3 buton: Ayni (birlestir), Farkli (reddet), ? (ertele)
- "Ayni" secilince hangi isim kalacak dropdown
- Kaybolma animasyonu

## 4. Admin Panel UI

### 4.1 Dashboard

- Istatistik kartlari: Toplam yuz, taninan kisi, bilinmeyen, kuyruk bekleyen, aktif kullanici
- Gunluk islem grafigi + kuyruk durumu
- Son islenenler listesi (canli)
- En aktif kullanicilar

### 4.2 Global Havuz

- Tum embedding gruplari grid'i (avatar + grup no + yuz sayisi + kullanici sayisi)
- Grup detay acilir panel: etiketleyen kullanicilar listesi, ornek yuzler
- Islemler: Gruplari Birlestir, Grubu Bol, Sil
- Kullanici etiketini duzenleme

### 4.3 Kullanici Goruntule

- Kullanici secici (dropdown/arama)
- Secili kullanicinin kisiler galerisi (ayni component reuse)
- Admin ek butonlari: etiket duzenle, grubu kaldir, kullanici adina birlestir

### 4.4 Kuyruk Yonetimi

- Durum filtreleri: Tumuu, Beklemede, Isleniyor, Hata
- Canli ilerleme (Socket.IO)
- Hatali islemleri yeniden baslat
- Kuyruk durdur/baslat, eszamanlilik ayari

### 4.5 Ayarlar

- Eslestirme esigi slider (0.3-0.8)
- Birlestirme oneri esigi slider (0.6-0.95)
- Kuyruk ayarlari (eszamanli islem, timeout, yeniden deneme)
- Otomatik isleme (acik/kapali)

## 5. API Tasarimi

### Koleksiyon Komutlari (Mevcut FikoYTIstekKok Pattern)

```typescript
const DB = {
  embeddingler:     (op: string) => `FikoYT.sistem.DB.yuz_embeddingler.${op}`,
  kisiGruplari:     (op: string) => `FikoYT.sistem.DB.yuz_kisi_gruplari.${op}`,
  etiketler:        (op: string) => `FikoYT.sistem.DB.yuz_kullanici_etiketleri.${op}`,
  onerileri:        (op: string) => `FikoYT.sistem.DB.yuz_birlestirme_onerileri.${op}`,
  kuyruk:           (op: string) => `FikoYT.sistem.DB.yuz_islem_kuyrugu.${op}`,
} as const;
```

### YuzTanimaApiService (DbBaseService extend)

Tum islemler mevcut aggregate/ekle/guncelle/sil helper'lari ile yapilir. Ozel endpoint gerekmez.

### Socket.IO Event'leri

```
yuz.kuyruk.ilerleme    → { resimId, yuzde, asama }
yuz.kuyruk.tamamlandi  → { resimId, yuzSayisi, eslesmeler }
yuz.kuyruk.hata        → { resimId, hata }
yuz.oneri.yeni         → { oneriId, grup1, grup2, benzerlik }
yuz.grup.guncellendi   → { grupId, yuzSayisi }
yuz.admin.kuyrukDurumu → { beklemede, isleniyor, tamamlanan, hata }
yuz.admin.canliIslem   → { resimId, kullaniciId, asama, yuzde }
```

### Backend Isleme Pipeline

```
1. Resim yuklendi
2. yuz_islem_kuyrugu'na kayit (durum: 'beklemede')
3. Worker resmi alir (durum: 'isleniyor') → Socket.IO push
4. InsightFace: yuz tespit + embedding cikar
5. Her yuz icin mevcut yuz_kisi_gruplari'nda arama
   - Esik ustu eslesmie → mevcut gruba ekle
   - Esik alti ama yakin → birlestirme onerisi olustur
   - Hic eslesmme yok → yeni grup olustur
6. yuz_embeddingler'e kaydet → Socket.IO push
7. Birlestirme onerisi varsa → Socket.IO push
```

## 6. Paylasim Sistemi Entegrasyonu

### icerikler.component Guncellemesi

Mevcut otomatikYuzTespitSorgula() yerine yeni yuzEtiketleriCozumle() akisi:
1. Resimin embedding'lerini al
2. Her yuzun kisiGrupId'sini bul
3. Goruntuleyen kullanicinin etiketlerini cek
4. Fallback: paylasan kullanicinin etiketlerini cek
5. Sonuc: her yuz icin {bbox, isim, kaynak, soyagaciKisiId?}

### Kisi Balon Guncellemesi

- Etiket kaynagi rozeti: "Senin etiketin" / "Ahmet'in etiketi"
- "Kendin etiketle" butonu (baskasinin etiketini goruyorsa)
- Soyagacinda varsa → "Kisi Sayfasi" / "Fotograflari" baglantilari

### Yeni Fotograf Yuklendiginde

Otomatik kuyruga ekleme → Socket.IO ile tamamlanma bildirimi → UI guncelleme

## 7. Servis Paylasim Diyagrami

```
yuz-tanima/ (ortak modul)
    ├──→ soyagaci/kisiler-galerisi     (kullanici galeri)
    ├──→ soyagaci/kisi-fotograflari    (kisi fotograflari)
    ├──→ admin/yuz-tanima/*            (admin panel)
    └──→ paylasim-sistemi/icerikler    (kart yuz etiketleri)
```