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