docs: mimari ve operasyon dokümantasyonlarını ekle

- `ARCHITECTURE_AND_FLOW.md`: Mimari, servis sorumlulukları, kuyruklar ve iş akışı. - `HANDOVER_2026-02-16.md`: Tamamlanan kapsam, düzeltmeler ve sonraki adımlar. - `OPERATIONS_RUNBOOK.md`: Dev/prod çalıştırma, test ve sık karşılaşılan sorunlar. - `TURKCEALTYAZI_REAL_STATUS.md`: Gerçek provider entegrasyon durumu ve yapılacaklar. - `README.md`: Dokümantasyon dizini için giriş ve indeks.
2026-02-16 09:32:41 +03:00
parent 9f07ff445e
commit 0ba0cb1071
5 changed files with 343 additions and 0 deletions
--- a/doc/ARCHITECTURE_AND_FLOW.md
+++ b/doc/ARCHITECTURE_AND_FLOW.md
@@ -0,0 +1,83 @@
+# Mimari ve Is Akisi
+
+## Servisler
+
+## `services/core`
+
+Sorumluluklar:
+- Dizin izleme (`/media/tv`, `/media/movie`)
+- Stabil dosya kontrolu
+- Dosya adi parse
+- ffprobe media analizi
+- BullMQ pipeline orchestration
+- Job/log API + SSE stream
+- Review endpointleri
+
+Queue'lar:
+- `fileEvents`
+- `mediaAnalysis`
+- `subtitleFetch`
+- `finalizeWrite`
+
+Durumlar (ozet):
+- `PENDING`
+- `WAITING_FILE_STABLE`
+- `PARSED`
+- `ANALYZED`
+- `REQUESTING_API`
+- `FOUND_TEMP`
+- `NORMALIZING_ENCODING`
+- `WRITING_SUBTITLE`
+- `DONE`
+- `NEEDS_REVIEW`
+- `NOT_FOUND`
+- `AMBIGUOUS`
+- `ERROR`
+
+## `services/api`
+
+Sorumluluklar:
+- `/v1/subtitles/search`
+- `/v1/subtitles/choose`
+- archive extraction + guvenlik
+- icerik tabanli SRT/ASS dogrulama
+- scoring + best/ambiguous/not_found karari
+- temp cleanup
+
+Providerlar:
+- `TurkceAltyaziProvider`
+- `OpenSubtitlesProvider`
+
+Not:
+- OpenSubtitles su an mock.
+- TurkceAltyazi mock + feature-flag ile real deneme moduna sahip.
+
+## `services/ui`
+
+Sayfalar:
+- Dashboard
+- Jobs
+- Job Detail (SSE canli log)
+- Review
+- Settings
+- Watched Paths
+
+## Veri modeli (Mongo)
+
+- `watched_paths`
+- `settings`
+- `media_files`
+- `jobs`
+- `job_logs`
+
+## Uctan uca akis (movie ornegi)
+
+1. Watcher `add/change` event yakalar.
+2. `fileEvents` job olusur.
+3. Stabil kontrol -> parse -> media kaydi.
+4. `mediaAnalysis` ffprobe calistirir.
+5. `subtitleFetch` API `search` cagirir.
+6. API provider adaylarini indirir/isler.
+7. best secilirse core `finalizeWrite` ile dosyayi yazar.
+8. Job `DONE` olur, loglar UI'da canli akar.
+
--- a/doc/HANDOVER_2026-02-16.md
+++ b/doc/HANDOVER_2026-02-16.md
@@ -0,0 +1,91 @@
+# Handover Notu (16 Subat 2026)
+
+Bu belge, 16 Subat 2026 tarihine kadar subwatcher projesinde tamamlanan calismalari ozetler.
+
+## 1) Tamamlanan kapsam
+
+- Monorepo iskeleti olusturuldu:
+  - `services/core` (Fastify + watcher + BullMQ + Mongo)
+  - `services/api` (Fastify + provider katmani + extraction/security/selection)
+  - `services/ui` (React + Vite)
+- Docker yapisi kuruldu:
+  - `compose.dev.yml` (hot reload)
+  - `compose.yml` (prod)
+  - Her servis icin Dockerfile
+- Temel altyazi pipeline aktif:
+  - Dosya izleme
+  - Stabil dosya kontrolu
+  - Parse
+  - ffprobe (hata halinde fallback mediaInfo)
+  - Subtitle arama
+  - Encoding normalize + hedefe yazma
+- Mongo koleksiyonlari ve job log mekanizmasi aktif.
+- UI sayfalari aktif:
+  - Dashboard
+  - Jobs
+  - Job Detail (SSE log akisi)
+  - Review listesi + manuel secim akisi
+  - Settings
+  - Watched Paths
+- API tarafinda mock provider altyapisi aktif:
+  - TurkceAltyazi (mock)
+  - OpenSubtitles (mock)
+- Archive extraction/security aktif:
+  - 7z extraction
+  - zip slip kontrolu
+  - limit kontrolleri
+  - icerik tabanli SRT/ASS validasyonu
+
+## 2) Sonradan yapilan kritik duzeltmeler
+
+- `p7zip-rar` Docker build hatasi duzeltildi:
+  - `services/api/Dockerfile` -> `p7zip-full unrar-free`
+- Dev ortamda bagimlilik drift sorunu duzeltildi:
+  - `compose.dev.yml` icin `api/core/ui` servislerine:
+    - `command: sh -c "npm install && npm run dev"`
+- Parse gorunurlugu iyilestirildi:
+  - `PARSE_DONE` log meta icine `release/year/season/episode`
+  - UI Job Detail ekraninda release/year/season-episode gosterimi
+
+## 3) Gercek TurkceAltyazi entegrasyonu (v2) icin yapilanlar
+
+- Feature flag eklendi (API env):
+  - `ENABLE_TURKCEALTYAZI_REAL`
+  - `TURKCEALTYAZI_ALLOW_MOCK_FALLBACK`
+  - `TURKCEALTYAZI_BASE_URL`
+  - `TURKCEALTYAZI_TIMEOUT_MS`
+  - `TURKCEALTYAZI_MIN_DELAY_MS`
+- Yeni real adapter helper eklendi:
+  - `services/api/src/lib/turkcealtyaziReal.ts`
+- `TurkceAltyaziProvider` guncellendi:
+  - real search denemesi
+  - detail->download URL resolve
+  - dosya indirme (archive/direct ayrimi)
+- Provider trace adimlari eklendi:
+  - `TA_SEARCH_REQUEST`
+  - `TA_SEARCH_PARSED`
+  - `TA_DETAIL_FETCHED`
+  - `TA_DOWNLOAD_URL_RESOLVED`
+- `services/api/package.json` eklendi:
+  - `axios`
+  - `cheerio`
+
+## 4) Mevcut calisan durum
+
+- API ve Core servisleri basariyla ayaga kalkiyor.
+- Yeni bagimliliklar kurulduktan sonra `ERR_MODULE_NOT_FOUND: axios` problemi cozuldu.
+- Pipeline genel olarak calisiyor; yeni eklenen film dosyalarinda job ilerlemesi izlenebiliyor.
+
+## 5) Bilinen riskler
+
+- TurkceAltyazi HTML parser heuristik, site DOM degisirse kirilabilir.
+- Gercek TA akisi icin cookie/challenge korumalari ihtiyac halinde ek hardening gerektirebilir.
+- Watcher coklu event uretebildigi icin tek dosya icin birden fazla job olusabiliyor (de-dup katmani guclendirilmeli).
+
+## 6) Sonraki oncelikli isler (onerilen)
+
+1. Watcher dedup mekanizmasi ekle (path + zaman penceresi + aktif job kontrolu).
+2. TurkceAltyazi parserini fixture testlerle sabitle.
+3. TA hata tiplerini ayir (network/parsing/rate-limit/blocked).
+4. Core tarafinda retry/policy netlestir.
+
--- a/doc/OPERATIONS_RUNBOOK.md
+++ b/doc/OPERATIONS_RUNBOOK.md
@@ -0,0 +1,65 @@
+# Operations Runbook
+
+## Dev calistirma
+
+```bash
+docker compose -f compose.dev.yml up --build
+```
+
+Not:
+- Dev compose servisleri startup'ta otomatik `npm install` yapar.
+- Bu sayede yeni dependency eklendiginde `node_modules` volume drift sorunu azalir.
+
+## Ortam guvenligi
+
+- `.env` dosyasinda gizli anahtarlar bulunabilir.
+- Bu dosyayi git'e commit etme.
+- Baska cihaza geciste guvenli sekilde tasiyip sadece lokalde kullan.
+
+## Health check
+
+```bash
+curl http://localhost:3001/api/health
+curl http://localhost:3002/v1/health
+```
+
+## Test media yerlestirme
+
+- Film: `./_media/movie`
+- Dizi: `./_media/tv`
+
+## Job tetikleme (dev endpoint)
+
+```bash
+curl -X POST http://localhost:3001/api/debug/enqueue \
+  -H 'content-type: application/json' \
+  -d '{"path":"/media/movie/test.mkv","kind":"movie"}'
+```
+
+## Log izleme
+
+```bash
+docker compose -f compose.dev.yml logs -f api core ui
+```
+
+UI:
+- `http://localhost:5173`
+- Job Detail -> Canli Loglar paneli
+
+## SIk sorunlar
+
+1. `ERR_MODULE_NOT_FOUND` (yeni paket)
+- Neden: node_modules volume eski.
+- Cozum:
+  ```bash
+  docker compose -f compose.dev.yml up -d --build api core ui
+  ```
+
+2. Cok sayida `PENDING` job
+- Neden: watcher coklu event (add/change) uretebilir.
+- Cozum (kisa vade): dosya transfer tamamlandiktan sonra tek tetikleme.
+- Orta vade: core tarafina de-dup logic eklenmeli.
+
+3. ffprobe hata veriyor
+- Pipeline fallback metadata ile devam eder.
+- Log adimi: `FFPROBE_DONE - ffprobe failed, fallback metadata used`
--- a/doc/README.md
+++ b/doc/README.md
@@ -0,0 +1,22 @@
+# subwatcher Dokumantasyon Indeksi
+
+Bu klasor, projeyi baska bir cihazdan devralip hizli devam etmek icin olusturuldu.
+
+## Dosyalar
+
+- `doc/HANDOVER_2026-02-16.md`
+  - Bu tarihe kadar yapilan tum gelistirmelerin ozet dokumu.
+- `doc/ARCHITECTURE_AND_FLOW.md`
+  - Core/API/UI servis mimarisi, kuyruklar, veri modeli ve is akis detaylari.
+- `doc/OPERATIONS_RUNBOOK.md`
+  - Dev/prod calistirma, debug, smoke test ve sik sorunlar.
+- `doc/TURKCEALTYAZI_REAL_STATUS.md`
+  - Gercek TurkceAltyazi entegrasyonunda su anki asama, kalan isler ve devam adimlari.
+
+## Hangi dosyadan baslamaliyim?
+
+1. Once `doc/HANDOVER_2026-02-16.md`
+2. Sonra `doc/TURKCEALTYAZI_REAL_STATUS.md`
+3. Ardindan `doc/OPERATIONS_RUNBOOK.md`
+
+Bu siralama ile en hizli sekilde kaldigin yerden devam edebilirsin.
--- a/doc/TURKCEALTYAZI_REAL_STATUS.md
+++ b/doc/TURKCEALTYAZI_REAL_STATUS.md
@@ -0,0 +1,82 @@
+# TurkceAltyazi Gercek Entegrasyon Durum Raporu
+
+Guncel durum tarihi: **16 Subat 2026**
+
+## Hedef
+
+Mock yerine TurkceAltyazi kaynagindan gercek aday bulma ve indirme akisini aktif etmek.
+
+## Tamamlananlar
+
+1. Feature flags tanimli:
+- `ENABLE_TURKCEALTYAZI_REAL`
+- `TURKCEALTYAZI_ALLOW_MOCK_FALLBACK`
+- `TURKCEALTYAZI_BASE_URL`
+- `TURKCEALTYAZI_TIMEOUT_MS`
+- `TURKCEALTYAZI_MIN_DELAY_MS`
+
+2. Real helper dosyasi var:
+- `services/api/src/lib/turkcealtyaziReal.ts`
+  - Arama URL denemeleri
+  - HTML parse ile aday cikarimi
+  - Detail sayfasinda download link cikarimi
+  - Binary indirme
+
+3. Provider real/mok gecisi var:
+- `services/api/src/providers/TurkceAltyaziProvider.ts`
+  - Real aciksa once real dener
+  - Basarisiz olursa fallback policy'e gore mock'a duser
+
+4. Trace log adimlari var:
+- `TA_SEARCH_REQUEST`
+- `TA_SEARCH_PARSED`
+- `TA_DETAIL_FETCHED`
+- `TA_DOWNLOAD_URL_RESOLVED`
+
+## Su an nerede kaldik?
+
+- KOD seviyesinde real TA akisi entegre edildi.
+- Servisler ayaga kalkiyor.
+- Runtime'da real TA davranisinin stabilitesi daha test edilmedi (site response/DOM degiskenligi nedeniyle).
+- Yani entegrasyon **ilk calisir prototip** seviyesinde.
+
+## Kalan kritik isler
+
+1. HTML parseri fixture testlerle sabitle
+- Ornek TA arama/detay HTML snapshotlari ile unit test yaz.
+- DOM degisikliklerine karsi fallback selector stratejisi ekle.
+
+2. Dayaniklilik katmani
+- 403/429/Cloudflare benzeri durumlari ayri hata kodlariyla logla.
+- Retry/backoff politikasi daha netlestir.
+
+3. Download tipi dogrulama
+- Content-Type + dosya signature kontrolu ekle.
+- Yanlis mime/redirect durumlarini net hata ile ele al.
+
+4. Yasal/etik uyum notu
+- Robots/ToS uyumunu projede dokumante et.
+
+## Devam ederken kontrol listesi
+
+1. `.env`:
+```env
+ENABLE_TURKCEALTYAZI_REAL=true
+TURKCEALTYAZI_ALLOW_MOCK_FALLBACK=true
+```
+2. Servisleri yeniden baslat:
+```bash
+docker compose -f compose.dev.yml up -d --build api core
+```
+3. Yeni bir movie job tetikle.
+4. Job logda TA adimlarini dogrula.
+5. Mock'a dustuyse sebebi logla ve parseri iyilestir.
+
+## Onemli dosyalar
+
+- `services/api/src/lib/turkcealtyaziReal.ts`
+- `services/api/src/providers/TurkceAltyaziProvider.ts`
+- `services/api/src/lib/subtitleEngine.ts`
+- `.env`
+- `.env.example`
+