sourcefinder/TODO.md

# 📋 TODO EXHAUSTIF - SourceFinder

*Basé sur le CDC complet - 25 composants majeurs à développer*

## 🏗️ PHASE 1 - ARCHITECTURE & CORE (2 semaines)

### 🔧 Infrastructure de base
- [ ] **Architecture ultra-modulaire Node.js + Express**
  - Structure avec interfaces strictes (INewsProvider, IStockRepository, IScoringEngine)
  - Dependency Injection Container
  - Configuration environment (.env)
  - Scripts package.json
  - Middleware de base

- [ ] **Système de stockage JSON modulaire**
  - Interface Repository abstraite (IStockRepository)
  - Implémentation JSON par défaut (JSONStockRepository)
  - Adaptateurs MongoDB/PostgreSQL (futurs, plug-and-play)
  - Index en mémoire pour performance
  - Migration path documenté

### 🧮 Système de scoring intelligent
- [ ] **Algorithme de scoring principal**
  - Formule: (Spécificité×0.4) + (Fraîcheur×0.3) + (Qualité×0.2) + (Anti-dup×0.1)
  - Classes ScoreCalculator avec breakdown détaillé
  - Tests unitaires sur calculs de scores

- [ ] **Scoring spécificité race (40%)**
  - Race exacte: 100pts
  - Groupe/famille: 70pts
  - Taille similaire: 50pts
  - Usage similaire: 40pts
  - Générique chiens: 25pts
  - Mapping races vers groupes/tailles/usages

- [ ] **Scoring fraîcheur (30%)**
  - < 7j: 100pts, 7-30j: 70pts, 30-90j: 40pts, 90-180j: 20pts, >180j: 5pts
  - Parsing dates multiformats
  - Gestion timezones

- [ ] **Scoring qualité source (20%)**
  - Premium: 100pts, Spécialisées: 80pts, Médias animaliers: 60pts
  - Presse généraliste: 40pts, Blogs/forums: 20pts
  - Base de données domaines avec scores

- [ ] **Scoring anti-duplication (10%)**
  - URL jamais utilisée: 100pts
  - Domaine peu utilisé: 70pts
  - Source recyclable: 50pts
  - Tracking usage avec timestamps

### 🛡️ Protection anti-prompt injection
- [ ] **Layer 1: Content Preprocessing**
  - Patterns dangereux: ignore instructions, you are now, forget everything
  - Suppression/masquage instructions suspectes
  - Normalisation texte

- [ ] **Layer 2: Pattern Detection**
  - Instructions directes, redirections, code injections, métaprompts
  - Regex + machine learning detection
  - Scoring suspicion

- [ ] **Layer 3: Validation sémantique**
  - Cohérence contenu/race mentionnée
  - Détection incohérences flagrantes
  - Analyse ton vs site source

- [ ] **Layer 4: Source Scoring avec pénalités**
  - Prompt injection: -50pts
  - Contenu incohérent: -30pts
  - Source historiquement non fiable: -20pts

### 🗄️ Système de stock intelligent
- [ ] **Architecture BDD stock**
  - Schema complet avec race_tags, angle_tags, universal_tags
  - Scoring fields, usage tracking, metadata
  - Index optimisés pour recherche rapide

- [ ] **Catégories de stock**
  - Premium: études, clubs officiels (3 usages, 180j rotation)
  - Standard: news spécialisées (2-3 usages, 90j rotation)
  - Fallback: conseils généraux (illimité, 30j rotation)

- [ ] **Logique réutilisation**
  - Tracking usage_count et last_used
  - Calcul éligibilité selon catégorie
  - Rotation automatique

## 🔍 PHASE 2 - NEWS PROVIDERS MODULAIRES (2 semaines)

### 🧠 LLM News Provider (implémentation par défaut)
- [ ] **Interface INewsProvider**
  - Contrat strict pour tous les providers
  - Méthodes searchNews(), validateResults(), getMetadata()
  - Types TypeScript pour robustesse

- [ ] **LLMNewsProvider implementation**
  - Intégration OpenAI/Claude API
  - Prompts optimisés pour recherche spécialisée
  - Gestion tokens et coûts
  - Cache intelligent des résultats

- [ ] **Providers alternatifs (futurs)**
  - ScrapingProvider (Puppeteer + anti-détection gratuite)
  - HybridProvider (LLM + scraping fallback)
  - Configuration plug-and-play

### 🔄 Recherche en cascade
- [ ] **Étape 1: Sources spécialisées race**
  - Recherche "[nom_race] actualité 2025"
  - Clubs race, associations cynophiles
  - Magazines élevage, forums modérés

- [ ] **Étape 2: Sources animalières générales**
  - "chien [caractéristique] actualité"
  - Médias animaliers grands publics
  - Sites conseils vétérinaires

- [ ] **Étape 3: Fallback généraliste**
  - "animaux domestiques", "propriétaires chiens"
  - Google News API
  - Adaptation contenu mainstream

### ⚙️ Configuration sources
- [ ] **Fichier config/sources.json**
  - Structure premium/specialized/fallback
  - Rules de scraping par domaine
  - Weights et rate limits

- [ ] **Management dynamique sources**
  - CRUD sources via API admin
  - Test automatique disponibilité
  - Scoring fiabilité historique

## 🔌 PHASE 3 - APIs & INTÉGRATIONS (1 semaine)

### 📡 API principale de recherche
- [ ] **Endpoint GET /api/v1/news/search**
  - Paramètres: race_code, product_context, min_score, max_age_days
  - Validation paramètres entrants
  - Réponse JSON structurée avec metadata

- [ ] **Logique de recherche**
  - Stock search d'abord
  - Live scraping si insuffisant
  - Scoring batch + tri
  - Filtrage anti-injection

### 🏪 APIs stock management
- [ ] **GET /api/v1/stock/status**
  - État global stock par race
  - Métriques coverage et qualité
  - Alertes stock bas

- [ ] **POST /api/v1/stock/refresh**
  - Force refresh sources
  - Background job trigger
  - Progress tracking

- [ ] **DELETE /api/v1/stock/cleanup**
  - Nettoyage articles expirés
  - Purge contenus bloqués
  - Stats cleanup

- [ ] **GET /api/v1/stock/race/{code}**
  - Stock détaillé par race
  - Breakdown par catégorie
  - Usage history

### 📊 APIs monitoring
- [ ] **GET /api/v1/health**
  - Status database, Redis, external APIs
  - Response time checks
  - Memory/CPU usage

- [ ] **GET /api/v1/metrics**
  - KPIs performance (temps réponse, uptime)
  - KPIs qualité (scores moyens, détection injection)
  - KPIs usage (req/jour, top races)

- [ ] **GET /api/v1/sources/status**
  - Health check toutes sources
  - Taux succès scraping
  - Sources en erreur

## ⚡ PHASE 4 - PERFORMANCE & PRODUCTION (1 semaine)

### 🚀 Performance & Cache
- [ ] **Configuration Redis**
  - Cache résultats recherche (TTL intelligent)
  - Session storage rate limiting
  - Background job queues

- [ ] **Optimisations requêtes**
  - Index database optimaux
  - Query optimization + profiling
  - Connection pooling

### 🔐 Sécurité & Rate limiting
- [ ] **Authentification API**
  - API keys management
  - JWT tokens option
  - Scopes permissions

- [ ] **Rate limiting**
  - Limites par client/IP
  - Burst allowance
  - Graceful degradation

### 📅 Background processing
- [ ] **Cron jobs**
  - Daily 02:00: Stock refresh & cleanup
  - Hourly: Sources health check
  - 4x/day: New sources discovery

- [ ] **Queue management**
  - Job queues Redis-based
  - Retry logic avec backoff
  - Dead letter queue

### 📈 Monitoring avancé
- [ ] **Métriques temps réel**
  - Prometheus/Grafana setup
  - Custom metrics business
  - Alerting rules

- [ ] **Logs structurés**
  - Winston/Bunyan logger
  - Structured JSON logging
  - Log aggregation

- [ ] **Alertes automatiques**
  - API down > 2min
  - Prompt injection > 5%/1h
  - Stock < 10 sources/race
  - Performance > 10s

- [ ] **Dashboard opérationnel**
  - Vue temps réel système
  - Graphs performance
  - Source status overview

## 🧪 PHASE 5 - TESTS & QUALITÉ

### 🔒 Tests sécurité
- [ ] **Tests prompt injection**
  - Battery patterns malveillants
  - Validation détection multicouches
  - Faux positifs acceptable

- [ ] **Tests validation sémantique**
  - Contenu hors contexte
  - Incohérences flagrantes
  - Edge cases validation

### ⚡ Tests performance
- [ ] **Load testing**
  - 100 req/min sustained
  - Spike testing 500 req/min
  - Memory leaks detection

- [ ] **Tests API endpoints**
  - Response time < 5s (95e percentile)
  - Concurrent users
  - Error rate < 1%

### 🔗 Tests intégration
- [ ] **End-to-end PublicationAutomator**
  - Workflow complet 1 article/jour
  - Qualité résultats retournés
  - Gestion erreurs gracieuse

- [ ] **Tests multi-clients**
  - Isolation données clients
  - Rate limiting per client
  - Scaling behavior

### 📚 Documentation
- [ ] **OpenAPI/Swagger**
  - Specs complètes toutes APIs
  - Exemples requêtes/réponses
  - Interactive testing

- [ ] **Documentation technique**
  - Architecture decision records
  - Deployment guides
  - Troubleshooting runbooks

---

## 🎯 DÉFINITION OF DONE

Chaque tâche doit respecter:
✅ **Code quality**: Linting, type safety, patterns cohérents
✅ **Tests**: Unit tests + integration appropriés
✅ **Sécurité**: Validation anti-injection, no secrets exposed
✅ **Performance**: Benchmarks validés selon KPIs
✅ **Documentation**: Code comments + API docs
✅ **Monitoring**: Logs + métriques appropriés

## 📊 MÉTRIQUES DE RÉUSSITE

**Performance**: API < 5s (95e), Uptime > 99.5%, 50+ sources/race
**Qualité**: Score moyen > 200pts, 90% requêtes avec résultats, < 1% injection
**Business**: Support PublicationAutomator, architecture multi-clients, extensibilité sources

---
*Total estimé: 155h sur 5 semaines - Projet complexe nécessitant approche méthodique*