feat(analytics): Implement Analytics Dashboard and Token Management

2026-10-24 15:38:10 +02:00 · 2026-01-20 13:49:24 +01:00
1 parent b38f082d6e
commit f8ddb44e38
@@ -0,0 +1,314 @@
+---
+stepsCompleted: [1, 2, 3, 4, 5, 6]
+inputDocuments:
+  - _bmad-output/planning-artifacts/prd.md
+  - package.json
+  - shared/schema.ts
+workflowType: 'architecture'
+project_name: 'Socialflow'
+user_name: 'Michael'
+date: '2026-01-20'
+---
+
+# Architecture Decision Document
+
+_This document builds collaboratively through step-by-step discovery. Sections are appended as we work through each architectural decision together._
+
+## Project Context Analysis
+
+### Requirements Overview
+
+**Functional Requirements:**
+Le système doit évoluer pour intégrer deux modules critiques :
+
+1. **Gestion des Tokens (Critique)** : Un système robuste de renouvellement automatique des tokens Facebook Page est nécessaire pour éviter les interruptions de service (expiration ~60 jours).
+2. **Analytics & Recommandations** : Un nouveau sous-système pour ingérer, stocker et analyser les métriques Facebook (Insights API) et fournir des recommandations simples (règles métier).
+
+**Non-Functional Requirements:**
+
+- **Fiabilité** : Le job de renouvellement de token est le point de défaillance unique (SPOF) à sécuriser absolument.
+- **Isolation des données** : L'architecture multi-tenant actuelle doit être strictement appliquée aux nouvelles données analytiques.
+- **Performance** : Les dashboards doivent rester rapides (<2s) malgré l'historisation croissante des données.
+
+**Scale & Complexity:**
+
+- **Primary domain**: Web App B2B (Social Media Management)
+- **Complexity level**: Moyenne (L'authentification OAuth et les APIs tierces ajoutent de la complexité accidentelle).
+- **Estimated architectural components**: 3 majeurs (TokenManager, AnalyticsIngestor, RecommendationEngine).
+
+### Technical Constraints & Dependencies
+
+- **Facebook Graph API** : Dépendance forte. Besoin de gérer les rate limits et les erreurs transitoires.
+- **Drizzle ORM** : Le schéma doit être étendu pour supporter les nouvelles métriques sans casser l'existant.
+- **Architecture existante** : On ne réécrit pas, on étend. Les nouveaux services doivent s'intégrer dans le pattern Service/Controller existant.
+
+### Cross-Cutting Concerns Identified
+
+- **Gestion des erreurs et Retries** : Critique pour les appels API Facebook.
+- **Logging & Monitoring** : Essentiel pour savoir si le renouvellement de token a échoué silencieusement.
+- **Sécurité des Credentials** : Stockage sécurisé des tokens (chiffrement au repos recommandé par NFRs).
+
+## Starter Template Evaluation (Brownfield Context)
+
+**Project Status:** Brownfield (Existing Codebase)
+**Decision:** Keep existing stack. No new starter template needed.
+
+### Existing Architecture Stack
+
+**Primary Technology Domain:** Full-Stack Web Application (Node.js/React)
+
+**Architectural Decisions Already in Place:**
+
+**Language & Runtime:**
+
+- **Runtime:** Node.js
+- **Language:** TypeScript (Strict mode)
+
+**Frontend Stack:**
+
+- **Framework:** React 18
+- **Build Tool:** Vite
+- **Routing:** Wouter (Client-side)
+- **State Management:** TanStack Query (React Query)
+- **Styling:** Radix UI + Tailwind CSS
+
+**Backend Stack:**
+
+- **Server:** Express.js
+- **Database:** PostgreSQL
+- **ORM:** Drizzle ORM
+- **Auth:** Passport.js (Session based)
+
+**Infrastructure:**
+
+- **Deployment:** Docker (Containerized)
+- **Media Storage:** Cloudinary
+
+**Decision:** The new features (Analytics, Token Automations) will simply extend this existing mature architecture. No migration required.
+
+## Core Architectural Decisions
+
+### Decision Priority Analysis
+
+**Critical Decisions (Block Implementation):**
+
+1. **Token Refresh Strategy**: Must be automated and robust (SPOF).
+2. **Analytics Schema Design**: Must support efficiently querying historical data.
+3. **Job Scheduling**: How to reliable trigger daily tasks in this stack.
+
+**Important Decisions (Shape Architecture):**
+
+1. **Facebook Service Refactoring**: Split monolithic service vs maintain as is.
+2. **Recommendation Engine Logic**: Hardcoded heuristics vs External AI.
+
+### Data Architecture
+
+**Schema Extensions (Drizzle ORM):**
+
+- **New Tables**:
+  - `postAnalytics`: Stockage des snapshots de métriques (impressions, clicks, etc.) liés à `posts`.
+  - `pageAnalyticsHistory`: Snapshots journaliers des followers par page.
+- **Modifications**:
+  - `socialPages`: Ajout de champs de statut (`tokenStatus`, `lastTokenCheck`).
+- **Migration Strategy**: Drizzle Kit (`drizzle-kit push` ou migration files).
+
+### Authentication & Security
+
+**Token Management:**
+
+- **Encryption**: Les tokens sont sensibles.
+  - _Décision_: Chiffrement au repos via une utilité `encrypt/decrypt` (AES-256) avant insertion en DB, transparent pour le service applicatif.
+- **Refresh Mechanism**:
+  - _Décision_: Utilisation d'un endpoint API dédié sécurisé (`/api/cron/refresh-tokens`) appelé par un CRON externe (type GitHub Actions ou service d'hébergement) ou un scheduler in-process (type `node-cron`) si déploiement persistant.
+  - _Choix Brownfield_: `node-cron` pour simplicité du déploiement Docker unique actuel.
+
+### API & Communication Patterns
+
+**Facebook Integration:**
+
+- **Service Layer**:
+  - Création de `AnalyticsService.ts` séparé de `FacebookService.ts` pour éviter le God Object.
+  - Abstraction commune `GraphAPIClient` pour gérer les appels HTTP, rate limits et erreurs.
+- **Frontend-Backend**:
+  - Nouveau routeur `analytics.routes.ts`.
+  - Cache: React Query sur le frontend (staleTime 5min) pour éviter le spam F5 sur les analytics.
+
+### Infrastructure & Deployment
+
+**Job Scheduling (CRON):**
+
+- **Pattern**: In-process scheduling via `node-cron`.
+  - _Avantage_: Pas de nouvelle infrastructure requise.
+  - _Inconvénient_: Si le serveur redémarre, le job peut sauter un tour (acceptable pour un refresh journalier avec marge de 7 jours).
+
+### Decision Impact Analysis
+
+**Implementation Sequence:**
+
+1. **Schema Update**: Créer les tables Analytics et mettre à jour SocialPages.
+2. **Token Manager**: Implémenter le chiffrement et le service de renouvellement.
+3. **Cron Job**: Configurer `node-cron` pour le check quotidien.
+4. **Analytics Ingestion**: Service pour puller les data de FB vers DB.
+5. **Analytics API**: Exposer les données au front.
+6. **UI**: Dashboard Analytics.
+
+## Implementation Patterns & Consistency Rules
+
+### Pattern Categories Defined
+
+**Critical Conflict Points Identified:**
+
+- **Naming**: Drizzle (snake_case DB) vs API (camelCase JSON).
+- **Service Structure**: Business Logic placement (Controller vs Service).
+- **Error Handling**: Silent fails in Cron Jobs vs User Feedback in UI.
+
+### Naming Patterns
+
+**Database Naming Conventions (Drizzle):**
+
+- **Tables**: `snake_case` plural (ex: `post_analytics`)
+- **Columns**: `snake_case` (ex: `followers_count`)
+- **Foreign Keys**: `snake_case` ending with `_id` (ex: `page_id`)
+
+**API Naming Conventions (REST):**
+
+- **Endpoints**: Kebab-case plural resources (ex: `/api/analytics/posts-insights`)
+- **JSON Props**: `camelCase` (ex: `followersCount` - necessitates transformation from DB snake_case)
+
+**Code Naming Conventions:**
+
+- **Services**: `TopicService.ts` containing class `TopicService`
+- **Interfaces**: PascalCase, generally not prefixed with 'I' in TS modern patterns (ex: `FacebookInsight`)
+
+### Structure Patterns
+
+**Project Organization:**
+
+- **Services**: `server/services/*.ts` - Business logic enabling re-use.
+- **Routes**: `server/routes.ts` - HTTP handlers, params validation, calling services.
+- **Schema**: `shared/schema.ts` - Centralized Drizzle schema & Zod types.
+
+### Communication Patterns
+
+**Async Jobs (Cron):**
+
+- **Logging**: All cron jobs MUST log start/finish/error with timestamp.
+- **State**: Jobs extending `socialPages` status must update `last_token_check` timestamp.
+
+### Process Patterns
+
+**Error Handling:**
+
+- **External APIs (FB/IG)**:
+  - Never crash the server on API failure.
+  - Wrap calls in try/catch.
+  - Throw typed application errors (`FacebookApiError`) for upstream handling.
+
+**Enforcement Guidelines:**
+
+**All AI Agents MUST:**
+
+1. Use `db.insert(...).returning()` pattern for creations.
+2. Use Zod schemas from `shared/schema.ts` for validation.
+3. Encrypt sensitive tokens before saving using `encrypt()` utility.
+
+## Project Structure & Boundaries
+
+### Complete Project Directory Structure
+
+```
+Socialflow/
+├── package.json
+├── tsconfig.json
+├── server/
+│   ├── index.ts                # App entry point
+│   ├── routes.ts               # Main router (delegates to sub-routers)
+│   ├── services/
+│   │   ├── facebook.ts         # Legacy Facebook service
+│   │   ├── analytics.ts        # [NEW] Analytics logic (fetch insights)
+│   │   ├── token_manager.ts    # [NEW] Token encryption & refresh logic
+│   │   └── recommendation.ts   # [NEW] Recommendation engine
+│   └── routes/
+│       └── analytics.routes.ts # [NEW] Analytics specific endpoints
+├── client/src/
+│   ├── App.tsx                 # Main frontend component
+│   ├── pages/
+│   │   ├── Dashboard.tsx       # Existing Dashboard
+│   │   └── analytics/          # [NEW] Analytics Section
+│   │       └── AnalyticsPage.tsx
+│   ├── components/
+│   │   ├── analytics/          # [NEW] Shared Analytics Components
+│   │   │   ├── StatCard.tsx
+│   │   │   ├── FollowersChart.tsx
+│   │   │   └── PostsTable.tsx
+│   │   └── ui/                 # Existing UI components (Radix)
+│   └── lib/
+│       ├── api.ts              # API client
+│       └── queryClient.ts      # React Query config
+├── shared/
+│   └── schema.ts               # Drizzle Schema & Zod Types
+└── migrations/                 # Drizzle migrations
+```
+
+### Architectural Boundaries
+
+**API Boundaries:**
+
+- **Endpoints**: `/api/analytics/*` (Protected by `requireAuth`)
+- **Internal Services**: Services communicate securely; `AnalyticsService` calls `FacebookService` only if necessary, prefers direct API calls via `GraphClient`.
+
+**Component Boundaries:**
+
+- **Frontend**: `AnalyticsPage` is the orchestrator. Contains `StatCard`, `Charts`.
+- **State**: React Query manages server state (caching insights). Local state for UI filters (date range).
+
+### Requirements to Structure Mapping
+
+**Feature/Epic Mapping:**
+**Analytics Module**:
+
+- Backend: `server/services/analytics.ts` + `server/routes/analytics.routes.ts`
+- Frontend: `client/src/pages/analytics/`
+- Data: `post_analytics`, `page_analytics_history` (in `schema.ts`)
+
+**Token Management Module**:
+
+- Service: `server/services/token_manager.ts`
+- Job: `server/jobs/token_refresh_job.ts` (Scheduled via node-cron in `server/index.ts`)
+- Data: `social_pages` (extended fields)
+
+### Integration Points
+
+**External Integrations:**
+
+- **Facebook Graph API**: Accessed via `server/utils/graph_client.ts` (to be created for standardized access).
+- **Cron System**: `node-cron` initialized in `server/index.ts` triggers `TokenManager.checkAndRefreshTokens()`.
+
+## Architecture Validation Results
+
+### Coherence Validation ✅
+
+- **Pattern Consistency**: The service-based architecture aligns with the existing Express/Drizzle stack.
+- **Structure Alignment**: New `analytics.ts` and `token_manager.ts` fit naturally into `server/services`.
+
+### Requirements Coverage Validation ✅
+
+- **Critical (Token Refresh)**: Covered by `TokenManager.checkAndRefreshTokens()` + encryption.
+- **Critical (Analytics)**: Covered by new schema + `AnalyticsService`.
+- **Security**: Encryption at rest addresses strict NFRs.
+
+### Architecture Readiness Assessment
+
+**Overall Status:** READY FOR IMPLEMENTATION
+**Confidence Level:** High
+
+### Implementation Handoff
+
+**AI Agent Guidelines:**
+
+- Strictly follow `camelCase` for JSON and `snake_case` for DB.
+- Use `Zod` schemas for all validation.
+- **Do not bypass** the encryption utility for token storage.
+
+**First Implementation Priority:**
+Initialize modules: `npx drizzle-kit push` (after schema update) -> `TokenManager` setup.
@@ -0,0 +1,531 @@
+---
+stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
+inputDocuments:
+  - package.json (stack technique)
+  - shared/schema.ts (modèle de données)
+  - server/services/facebook.ts (service Facebook existant)
+workflowType: 'prd'
+lastStep: 11
+scope: 'Dashboard Analytics Facebook (Recommandations) + Gestion Tokens Automatique'
+projectType: 'brownfield'
+documentCounts:
+  briefs: 0
+  research: 0
+  projectDocs: 3
+---
+
+# Product Requirements Document - Socialflow
+
+**Author:** Michael
+**Date:** 2026-01-20
+
+---
+
+## Executive Summary
+
+**Socialflow** est une application de gestion de réseaux sociaux permettant de publier du contenu sur Facebook (Feed et Stories) avec génération de texte par IA, planification, et gestion multi-utilisateurs.
+
+Ce PRD définit **deux évolutions majeures** pour étendre les capacités de la plateforme :
+
+### 1. Dashboard Analytics Facebook
+
+Tableau de bord complet présentant les performances des publications avec :
+
+- **Métriques clés** : Followers, Reach, Engagement, Clics
+- **Historisation des données** : Suivi de l'évolution dans le temps
+- **Analyse intelligente** : Recommandations IA sur les meilleurs types de posts, justifiées par les données collectées
+- **Vue par page** : Statistiques globales agrégées par page Facebook
+
+### 2. Support Instagram
+
+Extension de Socialflow pour publier sur Instagram depuis la même interface :
+
+- **Récupération du token Instagram** : Déblocage de l'accès API via Instagram Graph API
+- **Types de contenu** : Feed (photos/vidéos), Stories, Reels
+- **Vision unifiée** : Gérer Facebook et Instagram depuis un seul endroit
+
+### What Makes This Special
+
+**La valeur différenciante de ces évolutions :**
+
+1. **Data-Driven Insights** : Les recommandations IA ne sont pas des suppositions - elles sont **justifiées par les données réelles** de performance (likes, commentaires, reach).
+
+2. **Le moment "Aha!"** : Voir en un coup d'œil les **réactions sur chaque post** (likes, commentaires) et comprendre ce qui fonctionne.
+
+3. **Vision Unifiée** : Une seule plateforme pour gérer **Facebook ET Instagram** - plus besoin de jongler entre plusieurs outils.
+
+---
+
+## Project Classification
+
+| Critère | Valeur |
+|---------|--------|
+| **Technical Type** | `web_app` + `saas_b2b` |
+| **Domain** | Social Media Management |
+| **Complexity** | Moyenne |
+| **Project Context** | Brownfield - extension du système existant |
+
+### Implications techniques
+
+- **APIs externes** : Facebook Graph API (Insights) + Instagram Graph API
+- **Stockage** : Nouvelles tables pour historiser les métriques
+- **IA** : Réutilisation possible d'OpenRouter pour les recommandations
+- **Architecture** : Extension des services existants, pas de refonte
+
+---
+
+## Success Criteria
+
+### User Success
+
+| Critère | Description |
+|---------|-------------|
+| **Lisibilité** | Dashboard facile à lire avec les informations importantes clairement visibles |
+| **Informations actionnables** | L'utilisateur comprend immédiatement comment améliorer ses publications |
+| **Publication unifiée** | Publier sur Instagram ET Facebook en un seul clic |
+| **Gain de temps perçu** | L'utilisateur ressent que l'application lui fait gagner du temps |
+
+**Aha! Moments :**
+
+- Découvrir quel type de post fonctionne le mieux grâce aux insights
+- Réussir sa première publication simultanée Facebook + Instagram
+
+### Business Success
+
+| Horizon | Objectif |
+|---------|----------|
+| **3 mois** | Fonctionnalités déployées et utilisées (metrics à définir post-lancement) |
+| **Métrique clé** | Nombre de posts publiés (indicateur d'adoption) |
+
+### Technical Success
+
+| Critère | Cible |
+|---------|-------|
+| **Intégration Facebook Insights** | API fonctionnelle, données récupérées correctement |
+| **Intégration Instagram Graph API** | Token récupéré, publications Feed/Stories/Reels opérationnelles |
+| **Historisation** | Données stockées et requêtables pour analyse |
+| **Performance** | Dashboard charge en < 3 secondes |
+
+### Measurable Outcomes
+
+- ✅ Les utilisateurs peuvent voir les stats de leurs posts (likes, commentaires, reach)
+- ✅ Les recommandations IA sont basées sur des données réelles
+- ✅ Publication Instagram fonctionne (Feed, Stories, Reels)
+- ✅ Vision unifiée : une seule interface pour gérer les deux plateformes
+
+---
+
+## Product Scope
+
+### MVP - Minimum Viable Product
+
+**Dashboard Analytics :**
+
+- Affichage des métriques par page (followers, reach, engagement)
+- Historique des performances sur 30 jours
+- Liste des posts avec leurs réactions (likes, commentaires)
+
+**Instagram :**
+
+- Récupération automatique du token Instagram Business
+- Publication sur le Feed Instagram (photos/vidéos)
+- Publication de Stories Instagram
+
+### Growth Features (Post-MVP)
+
+- Recommandations IA ("Vos photos fonctionnent mieux le mardi")
+- Comparaison de performance entre posts
+- Publication de Reels Instagram
+- Analytics Instagram (en plus de Facebook)
+
+### Vision (Future)
+
+- Rapport PDF automatique des performances
+- Suggestions automatiques de contenu basées sur les tendances
+- Support d'autres plateformes (TikTok, LinkedIn, X)
+- Planification intelligente basée sur les meilleurs horaires
+
+---
+
+## User Journeys
+
+### Journey 1 : Sophie Durand - La Community Manager Débordée
+
+**Profil :** Sophie, 28 ans, community manager dans une agence web. Elle gère les réseaux sociaux de 5 clients différents.
+
+**Sa douleur :** Sophie passe ses lundis matin à compiler des rapports Excel pour chaque client, copiant manuellement les statistiques depuis Facebook. Elle doit ensuite publier le même contenu sur Facebook ET Instagram séparément, ce qui double son temps de travail. "Je fais plus de copier-coller que de créatif", soupire-t-elle.
+
+**Son parcours avec Socialflow :**
+
+Un mardi matin, Sophie ouvre Socialflow pour préparer les publications de la semaine. Elle clique sur le nouveau **Dashboard Analytics** et découvre immédiatement que les posts photos de son client "Boulangerie Martin" génèrent 3x plus d'engagement que les posts texte.
+
+Elle décide de créer un nouveau post avec une belle photo de croissants. En quelques clics, elle rédige le texte, sélectionne l'image, puis aperçoit une **nouvelle option** : publier sur **Facebook ET Instagram** simultanément. Un seul clic, et le post est programmé sur les deux plateformes.
+
+**Le moment de victoire :** Le vendredi, Sophie génère son rapport client en 2 minutes au lieu de 30. Les graphiques montrent clairement l'évolution des followers et l'engagement. Son client est impressionné par la clarté des données. Sophie rentre chez elle à 18h au lieu de 20h.
+
+**Capabilities révélées :**
+
+- Dashboard Analytics avec vue par page
+- Historique des performances
+- Publication multi-plateforme (FB + IG) en un clic
+- Visualisation claire des types de posts performants
+
+---
+
+### Journey 2 : Marc Lefebvre - Le Gérant de Commerce Local
+
+**Profil :** Marc, 45 ans, propriétaire d'une boutique de vélos. Il gère lui-même sa page Facebook mais n'a jamais osé Instagram.
+
+**Sa douleur :** Marc publie "quand il y pense" sur Facebook, sans vraie stratégie. Il ne sait pas ce qui fonctionne. Instagram lui fait peur : "C'est pour les jeunes, je ne sais pas comment ça marche."
+
+**Son parcours avec Socialflow :**
+
+Marc se connecte à Socialflow un dimanche soir tranquille. Il découvre le **Dashboard** et voit que ses photos de vélos restaurés ont beaucoup plus de likes que ses posts promotionnels. "Ah, les gens aiment voir mon travail !"
+
+Encouragé, il décide de poster une photo de sa dernière restauration. Socialflow lui propose de publier aussi sur Instagram. Hésitant, il clique sur "Connecter Instagram". Le système détecte automatiquement son compte Instagram professionnel lié à sa page Facebook. **En 30 secondes, c'est configuré.**
+
+Il publie sa photo sur les deux plateformes. Le lendemain, il reçoit 3 messages de clients potentiels via Instagram - des gens qui ne l'auraient jamais trouvé sur Facebook.
+
+**Le moment de victoire :** Marc regarde ses stats un mois plus tard. +150 followers Instagram, +40% d'engagement sur ses posts "restauration". Il comprend maintenant que montrer son expertise attire plus de clients que les promotions.
+
+**Capabilities révélées :**
+
+- Configuration Instagram simplifiée (auto-détection du compte lié)
+- Insights sur les types de contenus performants
+- Publication simultanée pour les non-technophiles
+- Suivi de l'évolution des followers
+
+---
+
+### Journey 3 : Admin Système - Configuration Multi-Utilisateurs
+
+**Profil :** Thomas, administrateur Socialflow dans l'agence de Sophie.
+
+**Sa douleur :** Gérer les accès de 10 community managers à 30 pages clients différentes, sans qu'ils voient les données des autres clients.
+
+**Son parcours avec Socialflow :**
+
+Thomas reçoit une demande : "Sophie doit maintenant gérer le client Instagram BioMarché." Il se connecte en admin, va dans les paramètres utilisateurs, et assigne la page BioMarché (Facebook + Instagram) à Sophie.
+
+Sophie voit immédiatement la nouvelle page dans son dashboard, avec l'analytics et la possibilité de publier. Elle n'a accès qu'aux pages qui lui sont assignées.
+
+Quand un stagiaire quitte l'agence, Thomas retire ses accès en 2 clics. Sécurité maintenue.
+
+**Capabilities révélées :**
+
+- Gestion des permissions par utilisateur
+- Assignation de pages (FB + IG) aux utilisateurs
+- Isolation des données entre utilisateurs
+- Révocation rapide des accès
+
+---
+
+### Journey 4 : Erreur et Récupération - Token Instagram Expiré
+
+**Profil :** Sophie, 3 mois après avoir connecté Instagram.
+
+**Sa douleur :** Son post Instagram échoue avec l'erreur "Token expiré".
+
+**Son parcours :**
+
+Sophie tente de publier sur Instagram mais voit un message d'erreur clair : "🔴 La connexion Instagram a expiré. Reconnectez en 1 clic."
+
+Elle clique sur "Reconnecter", est redirigée vers Facebook pour réautoriser, et revient sur Socialflow. Le système confirme : "✅ Instagram reconnecté". Elle relance sa publication qui passe sans problème.
+
+**Le moment de soulagement :** Pas besoin d'appeler le support. L'erreur était claire, la solution évidente.
+
+**Capabilities révélées :**
+
+- Messages d'erreur explicites et actionnables
+- Reconnexion OAuth simplifiée
+- Gestion gracieuse des tokens expirés
+
+---
+
+### Journey Requirements Summary
+
+| Capability | Journeys |
+|------------|----------|
+| Dashboard Analytics | Sophie, Marc |
+| Publication multi-plateforme | (Reporté en Phase 2) |
+| Configuration Instagram auto | (Reporté en Phase 2) |
+| Insights & Recommandations FB | Sophie |
+| Gestion permissions | Admin |
+| Gestion erreurs token | Erreur/Récupération |
+| Historique followers | Sophie |
+
+---
+
+## Web App + SaaS B2B Specific Requirements
+
+### Project-Type Overview
+
+Socialflow est une **application web SPA (Single Page Application)** construite avec React et Vite, exposant une API REST Express.js. L'architecture existante est maintenue pour les nouvelles fonctionnalités.
+
+**Caractéristiques confirmées :**
+
+- ✅ SPA React conservée
+- ✅ Pas de temps réel requis (polling acceptable pour les stats)
+- ✅ Multi-tenant existant suffisant
+- ✅ Intégrations limitées à Facebook/Instagram/Cloudinary/OpenRouter
+
+### Technical Architecture Considerations
+
+#### Frontend (Existant - Extension)
+
+| Aspect | Spécification |
+|--------|---------------|
+| Framework | React 18 avec Vite |
+| Routing | Wouter (client-side) |
+| State | TanStack Query (React Query) |
+| UI | Radix UI + Tailwind CSS |
+| Charts | Recharts (pour le dashboard analytics) |
+
+**Nouvelles pages à créer :**
+
+- `/analytics` - Dashboard des statistiques
+- Extension de `/settings` - Configuration Instagram
+
+#### Backend (Existant - Extension)
+
+| Aspect | Spécification |
+|--------|---------------|
+| Runtime | Node.js avec Express |
+| ORM | Drizzle ORM |
+| Base de données | PostgreSQL |
+| Auth | Passport.js (sessions) |
+| Déploiement | Docker |
+
+**Nouveaux services à créer :**
+
+- `AnalyticsService` - Récupération des insights Facebook
+- `InstagramService` - Publication sur Instagram via Graph API
+
+#### Nouvelles Tables de Données
+
+```sql
+-- Statistiques par post
+CREATE TABLE post_analytics (
+  id UUID PRIMARY KEY,
+  post_id UUID REFERENCES posts(id),
+  impressions INTEGER,
+  reach INTEGER,
+  engagement INTEGER,
+  reactions_count INTEGER,
+  comments_count INTEGER,
+  clicks INTEGER,
+  fetched_at TIMESTAMP
+);
+
+-- Historique followers par page
+CREATE TABLE page_analytics_history (
+  id UUID PRIMARY KEY,
+  page_id UUID REFERENCES social_pages(id),
+  followers_count INTEGER,
+  recorded_at TIMESTAMP
+);
+
+-- Comptes Instagram liés
+CREATE TABLE instagram_accounts (
+  id UUID PRIMARY KEY,
+  page_id UUID REFERENCES social_pages(id),
+  instagram_business_id TEXT,
+  access_token TEXT,
+  token_expires_at TIMESTAMP
+);
+```
+
+### API Integration Requirements
+
+#### Facebook Graph API - Insights
+
+| Endpoint | Données récupérées |
+|----------|-------------------|
+| `/{page-id}?fields=followers_count` | Nombre de followers |
+| `/{post-id}/insights` | Impressions, reach, engagement |
+| `/{post-id}/reactions` | Nombre de réactions par type |
+| `/{post-id}/comments` | Nombre de commentaires |
+
+**Permissions requises :** `pages_read_engagement`, `read_insights`
+
+#### Instagram Graph API
+
+| Endpoint | Action |
+|----------|--------|
+| `/{page-id}?fields=instagram_business_account` | Récupérer l'ID Instagram lié |
+| `/{ig-id}/media` | Créer un post (step 1) |
+| `/{ig-id}/media_publish` | Publier le post (step 2) |
+| `/{ig-id}/stories` | Publier une story |
+
+**Permissions requises :** `instagram_basic`, `instagram_content_publish`
+
+### Implementation Considerations
+
+#### Priorité d'implémentation
+
+1. **Phase 1 - Instagram Token** : Récupération automatique de l'Instagram Business Account ID
+2. **Phase 2 - Publication Instagram** : Feed et Stories
+3. **Phase 3 - Analytics Facebook** : Dashboard avec métriques
+4. **Phase 4 - Historisation** : Stockage et graphiques d'évolution
+
+#### Points d'attention
+
+- **Rate Limits** : Facebook impose des limites d'appels API (à monitorer)
+- **Token Refresh** : Les tokens expirent, prévoir le renouvellement automatique
+- **Rétrocompatibilité** : Les nouvelles features ne doivent pas casser l'existant
+
+---
+
+## Project Scoping & Phased Development
+
+### MVP Strategy & Philosophy
+
+**Approche choisie :** Problem-Solving MVP
+
+- Résoudre le problème core avec le minimum de features
+- Focus sur la valeur utilisateur immédiate
+- Itérer rapidement basé sur le feedback
+
+**Timeline :** Flexible (estimation 4-6 semaines)
+
+**Équipe requise :** 1 développeur full-stack
+
+### MVP Feature Set (Phase 1)
+
+**Philosophie :** Focus total sur la fiabilité (Tokens) et la valeur ajoutée (Analytics + Recommandations). La publication Instagram est reportée.
+
+#### Module 1 : Gestion des Tokens (Fondation Critique)
+
+| Feature | Priorité | Effort |
+|---------|----------|--------|
+| Récupération & Stockage Token Facebook | 🔥 Critique | 2h |
+| **Renouvellement automatique Token Facebook** | 🔥 Critique | 4h |
+| Détection expiration & UI reconnexion | 🔥 Critique | 3h |
+| Notification email "Token Expiré" | ⭐ Important | 2h |
+
+> ⚠️ **Point critique** : Les tokens Facebook Page expirent (~60 jours). L'automatisation du renouvellement est la clé de la fiabilité.
+
+#### Module 2 : Dashboard Analytics & Recommandations
+
+| Feature | Priorité | Effort |
+|---------|----------|--------|
+| Récupération métriques posts (API Insights) | 🔥 Critique | 4h |
+| Affichage KPIs globaux (Reach, Engagement) | 🔥 Critique | 3h |
+| Historisation quotidienne des Followers | ⭐ Important | 3h |
+| **Moteur de Recommandations (Basique)** | 🔥 Critique | 4h |
+| *Ex: "Publiez des Vidéos le Mardi"* | | |
+
+> **Note sur les Recommandations** : Analyse simple basée sur l'historique (ex: Top 3 formats, Top 3 horaires).
+
+### Post-MVP Features (Phase 2)
+
+| Feature | Description |
+|---------|-------------|
+| **Support Complet Instagram** | Publication Feed/Stories & Analytics |
+| Publication multi-plateforme | Unification FB + IG |
+| Recommandations IA avancées | Analyse sémantique du contenu |
+| Rapport PDF | Export automatique |
+
+### Phase 3 (Vision Future)
+
+- Support TikTok, LinkedIn
+- Planification intelligente auto
+- Multi-comptes à grande échelle
+
+### Risk Mitigation Strategy
+
+#### Risques Techniques
+
+| Risque | Impact | Mitigation |
+|--------|--------|------------|
+| Token expiration non détectée | 🔴 Haut | CRON job de vérification quotidien + alertes |
+| Rate limits Facebook/Instagram | 🟡 Moyen | Cache des données, throttling des requêtes |
+| API Instagram change | 🟡 Moyen | Abstraction du service, logs détaillés |
+
+#### Risques Fonctionnels
+
+| Risque | Impact | Mitigation |
+|--------|--------|------------|
+| Instagram non lié à la page FB | 🔴 Haut | Message clair + guide de configuration |
+| Permissions insuffisantes | 🟡 Moyen | Vérification des permissions au login |
+
+### Token Renewal Strategy (Critique)
+
+**Workflow de renouvellement automatique :**
+
+1. **CRON Job quotidien** (3h du matin)
+2. Pour chaque page stockée :
+   - Vérifier `token_expires_at`
+   - Si expiration < 7 jours → renouveler via `/oauth/access_token?grant_type=fb_exchange_token`
+   - Mettre à jour le token en base
+3. Si renouvellement échoue :
+   - Marquer la page comme `token_expired`
+   - Afficher alerte dans l'UI
+
+---
+
+## Functional Requirements
+
+### Gestion des Tokens & Authentification
+
+- **FR1** : Le système peut stocker de manière sécurisée les tokens d'accès Facebook Page
+- **FR2** : Le système peut renouveler automatiquement les tokens Facebook avant leur expiration (CRON)
+- **FR3** : Le système peut détecter quand un token Facebook est devenu invalide
+- **FR4** : L'utilisateur est notifié (UI/Email) lorsqu'une reconnexion manuelle Facebook est requise
+
+### Dashboard Analytics & Recommandations
+
+- **FR5** : L'utilisateur peut voir les KPIs globaux de sa page (Followers, Reach hebdo, Engagement)
+- **FR6** : L'utilisateur peut voir l'historique d'évolution des followers
+- **FR7** : L'utilisateur peut voir la liste des posts avec leurs performances individuelles
+- **FR8** : Le système analyse les posts passés pour recommander le **meilleur format** (Vidéo vs Image)
+- **FR9** : Le système analyse les posts passés pour recommander le **meilleur jour/heure** (basé sur l'engagement)
+- **FR10** : Le système offre des insights textuels simples (ex: "Vos vidéos génèrent 2x plus d'engagement")
+
+### Gestion des Pages
+
+- **FR19** : L'administrateur peut assigner des pages (Facebook + Instagram) à des utilisateurs
+- **FR20** : L'utilisateur peut voir uniquement les pages qui lui sont assignées
+- **FR21** : L'administrateur peut révoquer l'accès d'un utilisateur à une page
+- **FR22** : Le système peut afficher le statut de connexion de chaque page (connectée, token expiré, erreur)
+
+### Publication Facebook (Existant - Confirmation)
+
+- **FR23** : L'utilisateur peut publier du contenu texte sur Facebook
+- **FR24** : L'utilisateur peut publier des photos sur le feed Facebook
+- **FR25** : L'utilisateur peut publier des vidéos sur le feed Facebook
+- **FR26** : L'utilisateur peut publier des stories Facebook
+- **FR27** : L'utilisateur peut programmer des publications Facebook
+
+### Gestion des Médias (Existant - Confirmation)
+
+- **FR28** : L'utilisateur peut uploader des médias (images/vidéos) via Cloudinary
+- **FR29** : L'utilisateur peut sélectionner des médias depuis la bibliothèque pour les publications
+- **FR30** : L'utilisateur peut éditer des images avant publication
+
+---
+
+## Non-Functional Requirements
+
+### Security & Data Protection
+
+- **NFR1 (Token Storage)** : Les tokens d'accès (Facebook/Instagram) doivent être chiffrés au repos dans la base de données.
+- **NFR2 (Data Isolation)** : Un utilisateur ne doit jamais pouvoir accéder aux données analytiques d'une page qui ne lui est pas assignée, même via manipulation d'API.
+- **NFR3 (Least Privilege)** : L'application ne doit demander que les permissions Facebook/Instagram strictement nécessaires (`pages_read_engagement`, `read_insights`, `instagram_content_publish`).
+
+### Performance & Responsiveness
+
+- **NFR4 (Dashboard Load)** : Le dashboard analytics doit s'afficher en moins de 2 secondes pour une page avec < 1 an d'historique.
+- **NFR5 (Async Processing)** : Les opérations longues (publication vidéo, récupération historique massif) doivent être traitées de manière asynchrone sans bloquer l'UI.
+- **NFR6 (Feedback)** : L'interface doit fournir un feedback visuel immédiat (< 200ms) lors d'une action utilisateur (ex: clic sur "Publier").
+
+### Reliability & Availability
+
+- **NFR7 (Token Monitor)** : Le processus de vérification des tokens doit s'exécuter quotidiennement avec un taux de succès > 99.9%.
+- **NFR8 (Error Recovery)** : En cas d'échec d'un appel API Facebook/Instagram (ex: timeout), le système doit réessayer automatiquement jusqu'à 3 fois avant d'échouer.
+- **NFR9 (Data Consistency)** : Les statistiques affichées doivent être synchronisées avec la source (Facebook) au moins une fois toutes les 24h.
+
+### API & Integration Constraints
+
+- **NFR10 (Rate Limiting)** : Le système doit respecter les quotas d'appels des APIs Graph API et gérer les headers `X-Page-Usage` pour éviter le blocage.
+- **NFR11 (Deprecation)** : Le code doit utiliser les versions d'API Facebook supportées au moins pour les 12 prochains mois.