From 0ba0cb10710d8f1d643339b4f1e9d471d9c3464d Mon Sep 17 00:00:00 2001 From: wisecolt Date: Mon, 16 Feb 2026 09:32:41 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20mimari=20ve=20operasyon=20dok=C3=BCmant?= =?UTF-8?q?asyonlar=C4=B1n=C4=B1=20ekle?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - `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. --- doc/ARCHITECTURE_AND_FLOW.md | 83 +++++++++++++++++++++++++++++ doc/HANDOVER_2026-02-16.md | 91 ++++++++++++++++++++++++++++++++ doc/OPERATIONS_RUNBOOK.md | 65 +++++++++++++++++++++++ doc/README.md | 22 ++++++++ doc/TURKCEALTYAZI_REAL_STATUS.md | 82 ++++++++++++++++++++++++++++ 5 files changed, 343 insertions(+) create mode 100644 doc/ARCHITECTURE_AND_FLOW.md create mode 100644 doc/HANDOVER_2026-02-16.md create mode 100644 doc/OPERATIONS_RUNBOOK.md create mode 100644 doc/README.md create mode 100644 doc/TURKCEALTYAZI_REAL_STATUS.md diff --git a/doc/ARCHITECTURE_AND_FLOW.md b/doc/ARCHITECTURE_AND_FLOW.md new file mode 100644 index 0000000..ba54b48 --- /dev/null +++ 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. + diff --git a/doc/HANDOVER_2026-02-16.md b/doc/HANDOVER_2026-02-16.md new file mode 100644 index 0000000..1b5ee28 --- /dev/null +++ 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. + diff --git a/doc/OPERATIONS_RUNBOOK.md b/doc/OPERATIONS_RUNBOOK.md new file mode 100644 index 0000000..09d3a90 --- /dev/null +++ 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` diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000..e892122 --- /dev/null +++ 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. diff --git a/doc/TURKCEALTYAZI_REAL_STATUS.md b/doc/TURKCEALTYAZI_REAL_STATUS.md new file mode 100644 index 0000000..c8180a3 --- /dev/null +++ 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` +