trafficanalytics

## Aperçu Traffic Analytics est un proxy d'analyse web conçu pour les sites Ghost. Il intercepte les appels `POST /api/v1/page_hit` effectués par le script `ghost-stats.js` de Ghost, enrichit la charge utile (analyse de l'user-agent, analyse du referrer, génération de signature utilisateur) et transmet les données à l'API `/v0/events` de Tinybird, où elles sont stockées dans une base de données ClickHouse. ## Architecture et modes d'exécution - **Mode Batch (par défaut)** – Le service d'ingestion valide les requêtes, filtre les bots et publie les événements bruts vers un topic Google Cloud Pub/Sub. Un worker distinct consomme l'abonnement, enrichit chaque événement, les regroupe et les transmet à Tinybird. Cela découple la gestion des requêtes de l'ingestion et améliore le débit. - **Mode Proxy (synchrone)** – Lorsqu'aucun topic Pub/Sub n'est configuré, le service d'ingestion effectue l'enrichissement en ligne et proxy la requête directement vers Tinybird dans le même cycle HTTP. Le mode est sélectionné via la variable d'environnement `WORKER_MODE` et la présence de `PUBSUB_TOPIC_PAGE_HITS_RAW`. ## Fonctionnalités clés - Analyse de l'user-agent pour la détection de l'OS, du navigateur et de l'appareil. - Analyse et catégorisation de l'URL du referrer. - Signatures utilisateur respectueuses de la vie privée avec des sels tournants quotidiennement. - En-tête `x-ghost-bot-detected: true` optionnel pour le trafic bot filtré. ## Configuration Copiez `.env.example` vers `.env` et ajustez les valeurs. Les variables importantes incluent : - `WORKER_MODE` – `worker` ou `ingest`. - `PUBSUB_TOPIC_PAGE_HITS_RAW` – définit le mode batch. - `ENABLE_BOT_DETECTION_HEADER` – active ou désactive l'en-tête de réponse de détection des bots. ## Flux de développement 1. **Prérequis** – Docker (Desktop ou Orbstack) et Docker Compose. 2. Clonez le dépôt et exécutez `pnpm dev` pour démarrer tous les services ; l'API d'analyse sera accessible à l'adresse `http://localhost:3000`. 3. Pour l'intégration locale avec une version de Ghost, exécutez `pnpm dev:ghost` dans ce dépôt et `pnpm dev:analytics:local` dans le dépôt Ghost. Cela relie les deux conteneurs via un réseau Docker partagé. ### Support Multi-Worktree Le projet peut exécuter plusieurs worktrees Git simultanément. Chaque worktree utilise son propre fichier `.env` pour définir des ports uniques, des noms de projet Docker compose et des volumes isolés, permettant un développement parallèle sans conflits de ports. ## Tests et Linting - `pnpm test:types` – Vérifications de types TypeScript. - `pnpm test:unit` – Tests unitaires. - `pnpm test:integration` – Tests d'intégration. - `pnpm test:e2e` – Tests de bout en bout avec WireMock. - `pnpm lint` – Linting ESLint. Toutes les commandes de test s'exécutent à l'intérieur de conteneurs Docker pour garantir la cohérence de l'environnement. ## Pipeline de déploiement - **Flux de branche** – Ouvrez une PR, ajoutez éventuellement le label `deploy-staging` pour déclencher un déploiement en staging. - **Actions de fusion** – Incrémentation automatique de la version patch, création de tag Git, publication de l'image Docker Hub, déploiements Cloud Run vers le staging et la production, vérifications de santé et notifications Slack. - **Déclencheur manuel** – Utilisez l'interface GitHub Actions pour exécuter le flux "Deploy" via `workflow_dispatch`. Les détails complets du CI/CD se trouvent dans `docs/deployment.md`. ## Documentation - `docs/architecture.md` – Diagrammes détaillés des modes batch vs proxy, pipeline Pub/Sub, OpenTelemetry et conception du worker. - `docs/deployment.md` – Pipeline CI/CD, flux staging/production et procédures de rollback. ## Licence MIT © Ghost Foundation (2013‑2026).