sourcefinder/CDC.md

📋 CAHIER DES CHARGES - SourceFinder

🎯 1. CONTEXTE & OBJECTIFS

1.1 Présentation du projet

Service : SourceFinder - Service de recherche et scoring d'actualités
Client principal : PublicationAutomator (Autocollant.fr)
Problématique : Fournir des actualités pertinentes, scorées et sécurisées pour génération de contenu
Solution : API de recherche intelligente avec stock réutilisable et protection anti-injection

1.2 Objectifs business

• API réutilisable : Service multi-clients pour différents projets de contenu
• Qualité garantie : Sources vérifiées, scoring intelligent, anti-duplication
• Performance : Réponses < 5 secondes, stock pré-constitué
• Sécurité : Protection anti-prompt injection sur sources externes
• Extensibilité : Ajout facile de nouvelles sources et critères de scoring

1.3 Positionnement microservice

Responsabilité unique : Sourcing, scoring, stockage et fourniture d'actualités
Indépendance : Développement, déploiement et scaling autonomes
API-first : Interface standardisée pour multiples clients

🔧 2. SPÉCIFICATIONS TECHNIQUES

2.1 Stack technique

Backend : Node.js + Express.js Architecture : Ultra-modulaire avec interfaces strictes et composants interchangeables News Provider : LLM par défaut (OpenAI/Claude), scraping/hybride disponibles via configuration Stockage : JSON par défaut, interface modulaire pour MongoDB/PostgreSQL Architecture stockage : Pattern Repository avec adaptateurs interchangeables Cache : Redis pour performance Monitoring : Logs structurés + métriques API

2.2 Architecture modulaire

[Client Request] → [Rate Limiting] → [Authentication] → [NewsSearchService]
                                                              ↓
[INewsProvider] ← [Dependency Injection] → [IScoringEngine] → [IStockRepository]
     ↓                                           ↓                    ↓
[LLMProvider*]                           [BasicScoring*]      [JSONRepository*]
[ScrapingProvider]                       [MLScoring]          [MongoRepository]
[HybridProvider]                         [LLMScoring]         [PostgreSQLRepo]

* = Implémentation par défaut

📊 3. SYSTÈME DE SCORING INTELLIGENT

3.1 Formule de scoring

Score_Final = (Spécificité_race × 0.4) + (Fraîcheur × 0.3) + (Qualité_source × 0.2) + (Anti_duplication × 0.1)

3.2 Spécificité race (40% du score)

• Race exacte mentionnée : 100 points
• Groupe/famille race : 70 points (ex: Bergers, Terriers)
• Taille similaire : 50 points (grands chiens si race grande)
• Usage similaire : 40 points (chiens de garde, chasse, etc.)
• Générique chiens : 25 points
• Animaux domestiques : 10 points

3.3 Fraîcheur (30% du score)

• < 7 jours : 100 points
• 7-30 jours : 70 points
• 30-90 jours : 40 points
• 90-180 jours : 20 points
• > 180 jours : 5 points

3.4 Qualité source (20% du score)

• Sources premium : 100 points (clubs officiels, vétérinaires, études)
• Sources spécialisées : 80 points (magazines élevage, sites race)
• Médias animaliers : 60 points (30 Millions d'Amis, Wamiz)
• Presse généraliste : 40 points (Le Figaro, 20 Minutes)
• Blogs/forums : 20 points (avec validation renforcée)

3.5 Anti-duplication (10% du score)

• URL jamais utilisée : 100 points
• Domaine peu utilisé : 70 points (< 3 usages)
• Source recyclable : 50 points (> 90 jours depuis dernier usage)
• Source récemment utilisée : 10 points

🛡️ 4. PROTECTION ANTI-PROMPT INJECTION

4.1 Problématique sécurité

Risque : Sources web peuvent contenir des prompts cachés pour manipuler les LLM
Impact : Génération de contenu non conforme, failles sécurité
Particulièrement critique : Sources spécialisées (blogs élevage, forums)

4.2 Système de protection multicouches

Layer 1: Content Preprocessing

function sanitizeContent(rawContent) {
  // Suppression instructions suspectes
  const dangerousPatterns = [
    /ignore\s+previous\s+instructions/i,
    /you\s+are\s+now/i,
    /forget\s+everything/i,
    /new\s+instructions:/i,
    /system\s+prompt:/i
  ];
  
  return cleanContent;
}

Layer 2: Pattern Detection

Patterns suspects :

• Instructions directes : "You are now...", "Ignore previous..."
• Redirections : "Instead of writing about dogs, write about..."
• Code injections : Scripts, balises, commandes système
• Métaprompts : "This is a test", "Output JSON format"

Layer 3: Semantic Validation

Vérifications :

• Le contenu parle-t-il vraiment de la race mentionnée ?
• Y a-t-il des incohérences flagrantes ?
• Le ton correspond-il au site source ?
• Présence d'éléments hors contexte ?

Layer 4: Source Scoring

Pénalités automatiques :

• Détection prompt injection : -50 points
• Contenu incohérent : -30 points
• Source non fiable historiquement : -20 points

🗄️ 5. SYSTÈME DE STOCK INTELLIGENT

5.1 Architecture stockage modulaire

// Interface NewsStockRepository (adaptable JSON/MongoDB/PostgreSQL)
{
  id: String,
  url: String (unique),
  title: String,
  content: String,
  content_hash: String,

  // Classification
  race_tags: [String], // ["352-1", "bergers", "grands_chiens"]
  angle_tags: [String], // ["legislation", "sante", "comportement"]
  universal_tags: [String], // ["conseils_proprietaires", "securite"]

  // Scoring
  freshness_score: Number,
  quality_score: Number,
  specificity_score: Number,
  reusability_score: Number,
  final_score: Number,

  // Usage tracking
  usage_count: Number,
  last_used: Date,
  created_at: Date,
  expires_at: Date,

  // Metadata
  source_domain: String,
  source_type: String, // "premium", "standard", "fallback"
  language: String,
  status: String // "active", "expired", "blocked"
}

// Implémentation par défaut: JSON files avec index en mémoire
// Migration possible vers MongoDB/PostgreSQL sans changement de code métier

5.2 Catégories de stock

🥇 Premium Stock

Sources : Études vétérinaires, recherches officielles, clubs de race
Caractéristiques : Haute qualité, evergreen content, réutilisables
Usage : Limité à 3 fois, rotation 180 jours
Exemples : Études comportementales, guides officiels FCI

🥈 Standard Stock

Sources : News spécialisées, magazines élevage, sites vétérinaires
Caractéristiques : Qualité correcte, actualités temporaires
Usage : 2-3 fois, rotation 90 jours
Exemples : Actualités clubs, événements canins, nouvelles recherches

🥉 Fallback Stock

Sources : Conseils généraux, presse généraliste adaptée
Caractéristiques : Générique, toujours utilisable
Usage : Illimité avec variations, rotation 30 jours
Exemples : Conseils éducation, sécurité générale

5.3 Stratégie de constitution du stock

Collecte proactive : 20-30 sources/jour en background
Équilibrage : 50% spécialisées, 30% générales, 20% fallback
Couverture : Minimum 50 sources par race populaire
Refresh : Scanning quotidien nouvelles sources + nettoyage expiré

🔍 6. SYSTÈME DE SOURCING

6.1 Stratégie de recherche en cascade

Étape 1 : Sources spécialisées race (priorité)

Recherche : "[nom_race] actualité 2025", "[race] étude"
Sources :

• Clubs de race officiels (.org)
• Associations cynophiles nationales
• Magazines spécialisés (Atout Chien, Rustica)
• Forums modérés de race

Étape 2 : Sources animalières générales

Recherche : "chien [caractéristique] actualité", "[groupe_race] news"
Sources :

• 30 Millions d'Amis (.com)
• Wamiz (.com)
• Sites vétérinaires (.vet)
• Blogs reconnus éleveurs

Étape 3 : Fallback généraliste

Recherche : "animaux domestiques", "propriétaires chiens"
Sources :

• Google News API
• Grands médias (adaptés)
• Sites conseils généralistes

6.2 Configuration sources

// config/sources.json
{
  "premium": [
    {
      "domain": "centrale-canine.fr",
      "type": "official",
      "weight": 100,
      "scraping_rules": {...},
      "rate_limit": "1req/5min"
    }
  ],
  "specialized": [...],
  "fallback": [...]
}

🔌 7. APIS EXPOSÉES

7.1 API principale de recherche

GET /api/v1/news/search

Paramètres :

{
  race_code: "352-1",           // Obligatoire
  product_context: "security_plate", // Optionnel
  min_score: 200,               // Défaut: 150
  max_age_days: 30,             // Défaut: 90
  max_results: 5,               // Défaut: 3
  categories: ["legislation", "health"], // Optionnel
  exclude_domains: ["example.com"],      // Optionnel
  include_stock: true           // Utiliser stock existant
}

Réponse :

{
  "status": "success",
  "results": [
    {
      "title": "Nouvelle réglementation Bergers Allemands",
      "url": "https://example.com/article",
      "content": "...",
      "score": 287,
      "breakdown": {
        "specificity": 100,
        "freshness": 85,
        "quality": 80,
        "anti_duplication": 22
      },
      "metadata": {
        "publish_date": "2025-09-10",
        "source_domain": "centrale-canine.fr",
        "categories": ["legislation"],
        "estimated_reading_time": "3min"
      }
    }
  ],
  "search_metadata": {
    "total_found": 12,
    "search_time_ms": 450,
    "sources_searched": 8,
    "from_stock": 2,
    "from_live": 3
  }
}

7.2 API de stock management

GET /api/v1/stock/status           # État du stock
POST /api/v1/stock/refresh         # Force refresh
DELETE /api/v1/stock/cleanup       # Nettoyage expiré
GET /api/v1/stock/race/{code}      # Stock par race

7.3 API de monitoring

GET /api/v1/health                 # Health check
GET /api/v1/metrics               # Métriques performance
GET /api/v1/sources/status        # État sources

⚙️ 8. WORKFLOW DE TRAITEMENT

8.1 Traitement requête en temps réel

1. Validation paramètres (race_code valide, etc.)
2. Recherche stock existant (filtrage par critères)
3. Si stock insuffisant → Recherche live sources
4. Scoring batch tous résultats trouvés
5. Anti-injection validation top résultats  
6. Tri par score décroissant
7. Retour résultats + mise à jour stock
8. Logging usage pour anti-duplication

8.2 Background processing

Cron daily 02:00 : Stock refresh & cleanup
Cron hourly     : Sources health check
Cron 4x/day     : New sources discovery
Real-time       : Usage tracking updates

📊 9. MÉTRIQUES & MONITORING

9.1 KPIs opérationnels

Performance :

• Temps réponse API < 5 secondes (95e percentile)
• Uptime > 99.5%
• Taux succès recherche > 90%

Qualité :

• Score moyen résultats > 200 points
• Taux détection prompt injection < 1%
• Couverture stock : 50+ sources par race populaire

Usage :

• Requêtes/jour par client
• Distribution scores retournés
• Top races/contextes demandés

9.2 Alertes automatiques

Critique :

• API down > 2 minutes
• Aucun résultat pour race populaire
• Détection prompt injection > 5% sur 1h

Warning :

• Stock < 10 sources pour race
• Performance dégradée > 10 secondes
• Source premium indisponible

🚀 10. PLANNING DE DÉVELOPPEMENT

10.1 Phase 1 - Core API (2 semaines)

Système de scoring (25h)

• Implémentation algorithme scoring
• Base de données MongoDB/PostgreSQL
• Configuration sources initiales
• API recherche basique

Protection anti-injection (20h)

• Patterns detection engine
• Content sanitization
• Validation sémantique basique
• Tests sécurité

Stock management (15h)

• Base de données stock
• Logique réutilisation
• CRUD APIs stock
• Nettoyage automatique

10.2 Phase 2 - Sources avancées (2 semaines)

Web scraping robuste (30h)

• Multi-sources scraping
• Rate limiting intelligent
• Error handling & retry
• Proxies rotation

Recherche en cascade (20h)

• Spécialisées → générales → fallback
• Optimisation performance
• Parallélisation searches
• Fallback automatique

API complète (15h)

• Paramètres avancés
• Monitoring endpoints
• Documentation OpenAPI
• Rate limiting clients

10.3 Phase 3 - Production (1 semaine)

Monitoring & alertes (15h)

• Métriques temps réel
• Dashboard opérationnel
• Alertes automatiques
• Logs structurés

Performance & scale (10h)

• Cache Redis
• Optimisations requêtes
• Tests charge
• Déploiement production

💰 11. BUDGET & RESSOURCES

11.1 Coûts opérationnels estimés

Infrastructure :

• Serveur Node.js : ~30€/mois
• Base données MongoDB Atlas : ~25€/mois
• Redis cache : ~15€/mois

APIs externes :

• Google News API : ~50€/mois
• Proxies web scraping : ~40€/mois

Total mensuel : ~160€/mois

11.2 Temps de développement

Développement initial : 125h sur 5 semaines Tests & validation : 20h Documentation : 10h Total : 155h

🎯 12. CRITÈRES DE RÉUSSITE

12.1 Objectifs quantifiés

Performance :

• API réponse < 5s (95e percentile)
• Uptime > 99.5%
• 50+ sources par race populaire en stock

Qualité :

• Score moyen > 200 points
• 90% requêtes avec résultats pertinents
• < 1% détection prompt injection

Business :

• Support PublicationAutomator (1 article/jour)
• Architecture prête 2+ clients additionnels
• Extensible nouvelles sources facilement

12.2 Validation technique

Tests sécurité : Résistance prompt injection validée
Tests performance : Load testing 100 req/min
Tests intégration : PublicationAutomator end-to-end
Documentation : APIs documentées OpenAPI/Swagger

---

SourceFinder est conçu comme un service réutilisable de haute qualité, sécurisé et performant, capable de supporter multiple clients avec des besoins variés de contenu automatisé.