# 📋 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
```javascript
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
```javascript
// 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
```javascript
// 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
```http
GET /api/v1/news/search
```

**Paramètres** :
```javascript
{
  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** :
```javascript
{
  "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
```http
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
```http
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é.*