# API LinkedIn Métriques Historiques (Avant AMC)

## Vue d'ensemble

Cette API permet de gérer les métriques LinkedIn des posts publiés **avant l'utilisation d'AMC**. Elle offre deux modes de collecte :

1. **Mode Interface** : Saisie dynamique via l'interface web (nouveaux endpoints)
2. **Mode Excel** : Import/Export via fichiers Excel (endpoints existants conservés)

---

## 🆕 Nouveaux Endpoints (Interface Web)

### 1. GET `/api/linkedin-historical/stats`

Récupère les statistiques globales pour le dashboard.

**Paramètres (query):**
- `entreprise_id` (required) : UUID de l'entreprise

**Réponse:**
```json
{
  "success": true,
  "data": {
    "posts_collected": 152,
    "collections_completed": 12,
    "posts_incomplete": 8,
    "last_collection": "15/05/2025"
  }
}
```

---

### 2. GET `/api/linkedin-historical/collections`

Liste toutes les collectes (groupées par période).

**Paramètres (query):**
- `entreprise_id` (required) : UUID de l'entreprise
- `page` (optional) : Numéro de page (défaut: 1)
- `per_page` (optional) : Éléments par page (défaut: 10, max: 100)

**Réponse:**
```json
{
  "success": true,
  "data": [
    {
      "period": {
        "start": "01/01/2023",
        "end": "31/12/2023",
        "key": "2023-01"
      },
      "posts_count": 24,
      "complete_count": 21,
      "partial_count": 2,
      "none_count": 1,
      "completion_percentage": 87,
      "status": "in_progress",
      "last_updated": "15/05/2025 14:30"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total": 3,
    "last_page": 1
  }
}
```

**Statuts possibles:**
- `completed` : 100% de complétude
- `in_progress` : 50-99% de complétude
- `incomplete` : < 50% de complétude

---

### 3. GET `/api/linkedin-historical/posts`

Récupère les posts d'une période spécifique.

**Paramètres (query):**
- `entreprise_id` (required) : UUID de l'entreprise
- `start_date` (required) : Date de début (format: YYYY-MM-DD)
- `end_date` (optional) : Date de fin (format: YYYY-MM-DD)
- `page` (optional) : Numéro de page (défaut: 1)
- `per_page` (optional) : Éléments par page (défaut: 50, max: 100)

**Réponse:**
```json
{
  "success": true,
  "data": [
    {
      "id": "uuid-123",
      "url": "https://www.linkedin.com/posts/...",
      "content": "Contenu du post...",
      "type": "image",
      "date": "2023-06-15",
      "likes": 45,
      "comments": 12,
      "shares": 8
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total": 24,
    "last_page": 1
  }
}
```

---

### 4. POST `/api/linkedin-historical/posts`

Sauvegarde ou met à jour plusieurs posts (batch).

**Body (JSON):**
```json
{
  "entreprise_id": "uuid-entreprise",
  "posts": [
    {
      "id": "uuid-123",  // Optionnel : si présent = update, sinon = create
      "url": "https://www.linkedin.com/posts/...",
      "content": "Contenu du post...",
      "type": "image",  // texte | image | video
      "date": "2023-06-15",
      "likes": 45,
      "comments": 12,
      "shares": 8
    }
  ]
}
```

**Réponse:**
```json
{
  "success": true,
  "message": "Posts sauvegardés avec succès.",
  "data": {
    "saved": 5,
    "updated": 3,
    "errors": []
  }
}
```

**Notes:**
- Auto-calcul de `reach_count` et `engagement_rate`
- Formule reach : `(likes + comments + shares) × 50`
- Formule engagement : `((likes×1 + comments×2 + shares×3) / reach) × 100`

---

### 5. DELETE `/api/linkedin-historical/posts/{id}`

Supprime un post individuel.

**Paramètres (query):**
- `entreprise_id` (required) : UUID de l'entreprise

**Réponse:**
```json
{
  "success": true,
  "message": "Post supprimé avec succès."
}
```

---

## 📊 Endpoints Excel (Existants)

### 6. GET `/api/linkedin-posts/historical/download-template`

Télécharge un template Excel avec les posts existants.

**Paramètres (query):**
- `entreprise_id` (required) : UUID de l'entreprise

**Réponse:** Fichier Excel (.xlsx)

---

### 7. POST `/api/linkedin-posts/historical/import-metrics`

Importe un fichier Excel (remplace tous les posts existants).

**Body (multipart/form-data):**
- `excel_file` (required) : Fichier Excel (.xlsx, .xls, max 10MB)
- `entreprise_id` (required) : UUID de l'entreprise

**Réponse:**
```json
{
  "success": true,
  "message": "Import historique terminé avec succès.",
  "queued": false,
  "updated": 0,
  "platform_posts_updated": 0,
  "analysis_pending_posts": 0,
  "historical_posts_created": 24,
  "errors": []
}
```

**⚠️ Attention:** Cet endpoint **supprime tous les posts existants** avant d'insérer les nouveaux.

---

## 🔐 Sécurité

- **Rôle requis:** `collecteur` uniquement
- **Validation:** Tous les endpoints vérifient que l'entreprise appartient au collecteur
- **Logs:** Toutes les opérations sont loggées avec le préfixe `[LINKEDIN_HISTORICAL_*]`

---

## 📝 Structure de la table `historical_posts`

```sql
CREATE TABLE historical_posts (
    uuid VARCHAR(36) PRIMARY KEY,
    linkedin_url VARCHAR(500) NULL,
    post_type ENUM('texte', 'image', 'video') NULL,
    content TEXT NULL,
    like_count INT DEFAULT 0,
    comment_count INT DEFAULT 0,
    share_count INT DEFAULT 0,
    views_count INT DEFAULT 0,
    reach_count INT DEFAULT 0,
    engagement_rate DECIMAL(5,2) NULL,
    publication_date TIMESTAMP NULL,
    company_id VARCHAR(36) NULL,
    source VARCHAR(50) NULL,  -- 'excel_import' | 'manual_entry'
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    FOREIGN KEY (company_id) REFERENCES companies(uuid)
);
```

---

## 🎯 Cas d'usage

### Scénario 1 : Nouvelle collecte via interface
1. Utilisateur sélectionne une période (ex: 01/01/2023 - 31/12/2023)
2. Frontend appelle `GET /posts?start_date=2023-01-01&end_date=2023-12-31`
3. Utilisateur saisit les posts dans le tableau dynamique
4. Auto-sauvegarde toutes les 30s via `POST /posts`
5. Dashboard mis à jour via `GET /stats` et `GET /collections`

### Scénario 2 : Import Excel (ancien système)
1. Utilisateur télécharge le template via `GET /historical/download-template`
2. Remplit le fichier Excel manuellement
3. Réimporte via `POST /historical/import-metrics`
4. Tous les anciens posts sont remplacés

---

## 🔄 Différences avec Métriques Concurrentielles

| Aspect | Métriques Concurrentielles | Métriques LinkedIn Historiques |
|--------|---------------------------|--------------------------------|
| **Cible** | Plusieurs entreprises concurrentes | Une seule entreprise (la sienne) |
| **Collections** | Entités en base avec `collection_id` | Regroupements virtuels par période |
| **Détails** | Likes/commentaires détaillés (auteur, type) | Juste les totaux (counts) |
| **Logique** | CRUD complet avec collections | CRUD simplifié sur posts uniquement |
| **Excel** | Import/Export avec détails | Import/Export avec totaux |

---

## 📚 Exemples d'appels

### Récupérer les stats
```bash
curl -X GET "https://api.amc.com/api/linkedin-historical/stats?entreprise_id=uuid-123" \
  -H "Authorization: Bearer TOKEN"
```

### Sauvegarder des posts
```bash
curl -X POST "https://api.amc.com/api/linkedin-historical/posts" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entreprise_id": "uuid-123",
    "posts": [
      {
        "url": "https://linkedin.com/posts/abc",
        "content": "Mon premier post",
        "type": "texte",
        "date": "2023-01-15",
        "likes": 25,
        "comments": 5,
        "shares": 2
      }
    ]
  }'
```

### Supprimer un post
```bash
curl -X DELETE "https://api.amc.com/api/linkedin-historical/posts/uuid-post?entreprise_id=uuid-123" \
  -H "Authorization: Bearer TOKEN"
```