feat(api): turkcealtyazi gerçek modu desteği ekle

TurkceAltyazi sağlayıcısı için gerçek HTTP istekleri ve HTML
parsing özelliği eklendi. Özellik bayrak ile açılıp kapatılabilir
ve hata durumunda mock moduna dönüş yapabilir.

Yapılan değişiklikler:
- Yeni ortam değişkenleri eklendi (ENABLE_TURKCEALTYAZI_REAL, vb.)
- axios ve cheerio bağımlılıkları eklendi
- Gerçek indirme ve arama işlemleri için turkcealtyaziReal.ts modülü eklendi
- Dokümantasyon güncellendi
- Detaylı trace logging desteği eklendi

services/api/src/lib/subtitleEngine.ts

@@ -14,7 +14,10 @@ import { chooseBest, scoreCandidateFile } from './scoring.js';
 
 const execFileAsync = promisify(execFile);
 
-const providers: SubtitleProvider[] = [new TurkceAltyaziProvider(), new OpenSubtitlesProvider()];
+const providerEntries: Array<{ name: Candidate['provider']; impl: SubtitleProvider }> = [
+  { name: 'turkcealtyazi', impl: new TurkceAltyaziProvider() },
+  { name: 'opensubtitles', impl: new OpenSubtitlesProvider() }
+];
 
 function defaultLimits() {
   return { maxFiles: 300, maxTotalBytes: 250 * 1024 * 1024, maxSingleBytes: 10 * 1024 * 1024 };
@@ -44,18 +47,35 @@ export async function searchSubtitles(input: SearchParams) {
   const dirs = await ensureJobDirs(jobToken);
 
   const allCandidates: Candidate[] = [];
-  for (const p of providers) {
-    const c = await p.search(input);
+  for (const p of providerEntries) {
+    if (p.name === 'turkcealtyazi') {
+      trace.push({ level: 'info', step: 'TA_SEARCH_REQUEST', message: 'TurkceAltyazi provider search started' });
+    }
+    trace.push({ level: 'info', step: 'SUBTITLE_SEARCH_STARTED', message: `Provider search started: ${p.name}` });
+    const c = await p.impl.search(input);
+    trace.push({ level: 'info', step: 'SUBTITLE_SEARCH_DONE', message: `Provider search done: ${p.name}`, meta: { count: c.length } });
+    if (p.name === 'turkcealtyazi') {
+      const realCount = c.filter((item) => item.scoreHints.includes('real_provider')).length;
+      trace.push({
+        level: 'info',
+        step: 'TA_SEARCH_PARSED',
+        message: `TurkceAltyazi candidates parsed`,
+        meta: { total: c.length, real: realCount, mock: c.length - realCount }
+      });
+    }
     allCandidates.push(...c);
   }
 
   const scored: any[] = [];
 
   for (const candidate of allCandidates) {
-    const provider = providers.find((p: any) => p.constructor.name.toLowerCase().includes(candidate.provider === 'turkcealtyazi' ? 'turkce' : 'open'));
+    const provider = providerEntries.find((p) => p.name === candidate.provider)?.impl;
     if (!provider) continue;
 
     const dl = await provider.download(candidate, input, jobToken);
+    if (Array.isArray(dl.trace)) {
+      trace.push(...dl.trace);
+    }
     trace.push({ level: 'info', step: 'ARCHIVE_DOWNLOADED', message: `${candidate.provider}:${candidate.id}`, meta: { path: dl.filePath, type: dl.type } });
 
     let files: string[] = [];