Nocron Backend

NestJStypescriptRESTfulAPINocron


🔗 Ver en GitHub

Résumé du Projet Nocron Backend - API d’Automatisation

🎯 Produit

Nocron Backend est une API RESTful robuste et évolutive pour l’automatisation des tâches et la planification des flux de travail. C’est le moteur central de la plateforme Nocron, conçu pour éliminer la complexité des cron jobs traditionnels tout en fournissant des fonctionnalités de niveau entreprise.

Caractéristiques principales:

  • Planification de tâches basée sur cron et événements
  • Plusieurs types de déclencheurs (Schedule, Webhook, Email, API)
  • Exécution en temps réel avec surveillance en direct via WebSockets
  • Système de modèles pour les cas d’usage courants
  • Authentification JWT avec refresh tokens et rotation automatique
  • Contrôle d’accès basé sur les rôles (User, Admin, SuperAdmin)
  • Gestion des clés API avec permissions granulaires
  • Analytics avancé avec métriques d’engagement et de performance
  • Système de notifications multi-canal (Email, Push, In-App, SMS, Webhook)
  • Intégration avec Stripe pour les abonnements et les paiements
  • Intégration avec Notion API pour la synchronisation des workspaces
  • Audit complet avec suivi de toutes les actions
  • Alertes de sécurité automatiques avec détection de patterns

🛠️ Stack Technologique

Framework Backend

  • NestJS 11.0.1 - Framework progressif de Node.js
  • Node.js 18.17.0+ - Runtime JavaScript
  • TypeScript 5.7.3 - Superset typé de JavaScript

Base de Données

  • PostgreSQL 15+ - Base de données relationnelle (Neon Cloud)
  • Prisma ORM 6.15.0 - ORM moderne avec type-safety

Authentification et Sécurité

  • Passport.js - Middleware d’authentification
  • JWT (jsonwebtoken v9.0.2) - Tokens d’accès et de rafraîchissement
  • Argon2 (v0.44.0) - Hachage de mots de passe (recommandé)
  • Bcrypt (v6.0.0) - Hachage alternatif de mots de passe

Validation et Transformation

  • class-validator (v0.14.2) - Validation des DTOs
  • class-transformer (v0.5.1) - Transformation d’objets

Intégrations Externes

  • @notionhq/client v5.1.0 - Intégration Notion API
  • Stripe v18.5.0 - Traitement des paiements
  • Nodemailer v7.0.6 - Envoi d’emails
  • Socket.io v4.8.1 - WebSockets pour le temps réel

Planification et Tâches

  • node-cron v3.0.3 - Planificateur de tâches style cron
  • @nestjs/schedule v4.1.2 - Module de planification de NestJS

Documentation

  • @nestjs/swagger v7.4.2 - Documentation OpenAPI/Swagger
  • swagger-ui-express v5.0.1 - Interface interactive Swagger

Tests

  • Jest v30.0.0 - Framework de tests
  • ts-jest v29.2.5 - Preset Jest pour TypeScript
  • Supertest v7.0.0 - Tests d’API HTTP

Outils de Développement

  • ESLint v9.18.0 - Linter de code
  • Prettier v3.4.2 - Formateur de code
  • Husky v9.1.7 - Git hooks
  • ts-node v10.9.2 - Exécution de TypeScript dans Node.js
  • tsx v4.19.2 - Exécuteur TypeScript rapide

🏗️ Architecture

Structure des Dossiers

nocron/backend/
├── src/                          # Code source
│   ├── auth/                     # Authentification et autorisation
│   ├── users/                    # Gestion des utilisateurs
│   ├── tasks/                    # Système central de tâches
│   ├── api/v1/                   # API REST version 1
│   ├── admin/                    # Panneau administratif
│   ├── analytics/                # Moteur d'analytics
│   ├── billing/                  # Stripe et abonnements
│   ├── dashboard/                # Métriques en temps réel
│   ├── email/                    # Service d'emails
│   ├── notifications/            # Système de notifications
│   ├── reports/                  # Rapports et analytics
│   ├── notion/                   # Intégration Notion
│   ├── health/                   # Contrôles de santé
│   ├── monitoring/               # Surveillance du système
│   ├── auditLog/                 # Logs d'audit
│   ├── sessions/                 # Gestion des sessions
│   ├── webhooks/                 # Gestion des webhooks
│   ├── queue/                    # File d'attente de tâches
│   ├── retry/                    # Système de réessais
│   ├── scheduler/                # Planificateur de tâches
│   ├── alerts/                   # Alertes de sécurité
│   ├── realtime/                 # WebSockets
│   ├── common/                   # Guards, interceptors, pipes
│   ├── config/                   # Configuration
│   ├── prisma/                   # Service Prisma
│   ├── utils/                    # Utilitaires
│   ├── app.module.ts             # Module racine
│   ├── app-minimal.module.ts     # Module minimal
│   ├── main.ts                   # Bootstrap principal
│   └── main-minimal.ts           # Bootstrap minimal
│
├── prisma/                       # Prisma ORM
│   ├── schema.prisma             # Schéma de base de données
│   └── seed.ts                   # Données initiales
│
├── test/                         # Tests E2E
│   ├── jest-e2e.json             # Configuration Jest E2E
│   └── jest-smoke.json           # Configuration smoke tests
│
├── docs/                         # Documentation
│   ├── README.md
│   ├── ARCHITECTURE.md
│   ├── DECISIONS.md
│   ├── ROADMAP.md
│   └── nocron_backend_roadmap.md
│
├── .github/                      # Configuration GitHub
│   ├── workflows/                # CI/CD workflows
│   └── ISSUE_TEMPLATE/           # Templates d'issues
│
├── sdk/                          # SDKs client
│   └── javascript/               # SDK JavaScript/TypeScript
│
├── issues/                       # Suivi des audits
│   ├── GITHUB-ISSUES-CREATED-SUMMARY.md
│   ├── GITHUB-PROJECT-MANAGEMENT.md
│   ├── SPRINT-PLANNING.md
│   └── PROJECT-WORKFLOW-GUIDE.md
│
├── package.json                  # Dépendances et scripts
├── tsconfig.json                 # Configuration TypeScript
├── nest-cli.json                 # Configuration Nest CLI
├── .env                          # Variables d'environnement
├── .env.test                     # Variables pour les tests
├── .gitignore                    # Git ignore
├── .prettierrc                   # Configuration Prettier
├── eslint.config.mjs             # Configuration ESLint
├── README.md                     # Documentation principale
├── CLAUDE-BACKEND-STATE.md       # État du projet
└── CONTRIBUTING.md               # Guide de contribution

🔧 Modules et Services

Module Auth (src/auth/)

Fichiers clés:

  • auth.service.ts - Logique d’authentification (inscription, connexion, rafraîchissement, déconnexion)
  • auth.controller.ts - Points de terminaison d’authentification
  • roles.service.ts - Gestion des rôles et permissions
  • admin-roles.controller.ts - Points de terminaison administratifs des rôles
  • strategies/jwt.strategy.ts - Stratégie JWT de Passport
  • dto/register.dto.ts, login.dto.ts, change-password.dto.ts - DTOs de validation

Fonctionnalités:

  • Inscription des utilisateurs avec hachage Argon2/Bcrypt
  • Connexion avec JWT access + refresh tokens
  • Refresh token avec rotation automatique
  • Système de rôles (User, Admin, SuperAdmin)
  • Guards d’authentification et d’autorisation
  • Version de token pour invalidation globale des tokens

Module Users (src/users/)

Fonctionnalités:

  • CRUD complet des utilisateurs
  • Gestion des profils
  • Changement de mot de passe
  • Gestion des tokens Notion
  • Relations avec les tâches et abonnements

Module Tasks (src/tasks/)

Fonctionnalités:

  • Création et gestion des tâches
  • Support pour plusieurs types d’actions:
    • HTTP_REQUEST
    • EMAIL_SEND
    • DATABASE_QUERY
    • API_CALL
    • CUSTOM_SCRIPT
    • NOTION_SYNC
  • Planification avec expressions cron
  • Exécution immédiate des tâches
  • Logs d’exécution
  • États: ACTIVE, PAUSED, STOPPED, FAILED

Module API v1 (src/api/v1/)

Points de terminaison publics:

  • /api/v1/tasks - CRUD de tâches avec authentification API Key
  • /api/v1/analytics - Métriques et analytics
  • Documentation Swagger à /api/docs

Module Billing (src/billing/)

Fonctionnalités:

  • Intégration complète avec Stripe
  • Gestion des abonnements (BASIC, PRO, ENTERPRISE)
  • Gestion des webhooks pour les événements Stripe
  • Suivi des paiements et factures
  • Limites d’utilisation par plan
  • Annulation et renouvellement des abonnements

Module Notifications (src/notifications/)

Fonctionnalités:

  • Système multi-canal (Email, Push, In-App, SMS, Webhook)
  • Modèles de notifications avec variables
  • Préférences utilisateur par type et canal
  • Suivi de l’envoi, la livraison, la lecture et les clics
  • File d’attente de notifications
  • Logique de réessai pour les échecs

Module Email (src/email/)

Fonctionnalités:

  • Intégration avec Nodemailer (SMTP Gmail configuré)
  • Modèles avec Handlebars
  • Variables dynamiques
  • Suivi des ouvertures et clics
  • Limitation de débit
  • Logs d’envoi

Module Analytics (src/analytics/)

Fonctionnalités:

  • Suivi des événements utilisateur
  • Métriques d’engagement
  • Analyse de cohortes
  • Analytics d’entonnoir
  • Métriques de rétention
  • Événements personnalisés

Module Dashboard (src/dashboard/)

Fonctionnalités:

  • Métriques en temps réel
  • Aperçu des tâches actives
  • Statistiques d’exécution
  • Graphiques de performance
  • Alertes et notifications récentes

Module Reports (src/reports/)

Fonctionnalités:

  • Rapports exécutifs
  • Rapports personnalisables
  • Export en plusieurs formats
  • Planification des rapports
  • Historique des exécutions
  • Analytics avancé

Module Admin (src/admin/)

Fonctionnalités:

  • Gestion des utilisateurs
  • Analytics administratifs
  • Contrôle des abonnements
  • Révision des logs d’audit
  • Gestion des alertes de sécurité
  • Configuration du système

Module Notion (src/notion/)

Fonctionnalités:

  • Intégration avec Notion API (@notionhq/client)
  • Synchronisation des workspaces
  • Flux OAuth
  • Accès aux bases de données et pages
  • Webhooks Notion

Module Health (src/health/)

Points de terminaison:

  • /health - Contrôle de santé basique
  • Vérification de connectivité de base de données
  • Statut des services externes

Module Monitoring (src/monitoring/)

Fonctionnalités:

  • Métriques système
  • Surveillance de performance
  • Suivi des erreurs
  • Surveillance de la disponibilité

Module AuditLog (src/auditLog/)

Fonctionnalités:

  • Logging automatique de toutes les requêtes
  • Intercepteur global
  • TransactionId unique par requête
  • Capture complète de request/response
  • Métadonnées de sécurité (IP, User-Agent)
  • Classification par type d’action
  • Drapeaux pour actions critiques

Module Sessions (src/sessions/)

Fonctionnalités:

  • Gestion des refresh tokens
  • Suivi des sessions actives
  • Révocation des sessions
  • Nettoyage des sessions expirées
  • Informations sur les appareils

Module Webhooks (src/webhooks/)

Fonctionnalités:

  • Gestion des webhooks Stripe
  • Logique de réessai avec backoff exponentiel
  • Vérification des signatures
  • Idempotence
  • Logging des événements

Module Queue (src/queue/)

Fonctionnalités:

  • File d’attente de tâches asynchrones
  • Traitement en arrière-plan
  • Files de priorité
  • Logique de réessai
  • File de lettres mortes

Module Retry (src/retry/)

Fonctionnalités:

  • Système de réessais configurable
  • Backoff exponentiel
  • Tentatives maximales
  • Gestion des erreurs

Module Scheduler (src/scheduler/)

Fonctionnalités:

  • Planification de tâches avec node-cron
  • Évaluation d’expressions cron
  • Support des fuseaux horaires
  • Calcul de la prochaine exécution

Module Alerts (src/alerts/)

Fichiers:

  • security-alerts.service.ts - Détection de patterns suspects
  • alert-email.service.ts - Envoi d’alertes par email
  • alert-webhook.service.ts - Envoi d’alertes par webhook
  • alert-coordinator.service.ts - Coordination des alertes
  • alerts.controller.ts - Points de terminaison de gestion des alertes

Fonctionnalités:

  • Détection automatique de:
    • Multiples tentatives de connexion échouées
    • Accès depuis des IPs inhabituelles
    • Rafale d’accès admin
    • User agents suspects
  • Niveaux de gravité (LOW, MEDIUM, HIGH, CRITICAL)
  • Notifications multi-canal
  • Reconnaissance et résolution des alertes
  • Marquage des faux positifs

Module Realtime (src/realtime/)

Fonctionnalités:

  • WebSockets avec Socket.io
  • Notifications en temps réel
  • Mises à jour des tâches en cours d’exécution
  • Mises à jour en direct du dashboard

Module Common (src/common/)

Composants:

  • Guards: JwtAuthGuard, RolesGuard, ApiKeyGuard
  • Interceptors: AuditLogInterceptor, TransformInterceptor
  • Pipes: ValidationPipe personnalisé
  • Decorators: @Roles(), @Public(), @ApiKey()
  • Filters: HttpExceptionFilter

Module Config (src/config/)

Configuration:

  • Configuration de base de données
  • Configuration JWT
  • Configuration email
  • Configuration Stripe
  • Validation d’environnement

🔐 Sécurité

Protections Implémentées

  • Hachage de mots de passe - Argon2 (recommandé) + Bcrypt
  • Validation des entrées - class-validator sur tous les DTOs
  • Protection contre l’injection SQL - Prisma ORM avec requêtes paramétrées
  • Protection XSS - Sanitisation des entrées
  • CORS - Configuré pour les domaines autorisés
  • Limitation de débit - Par point de terminaison et par clé API
  • Logging d’audit - Toutes les actions enregistrées
  • Alertes de sécurité - Détection automatique de patterns suspects

📡 Points de Terminaison API

Authentification

POST   /auth/register          - Inscription utilisateur
POST   /auth/login             - Connexion JWT
POST   /auth/refresh           - Refresh token
POST   /auth/logout            - Déconnexion et révocation de session
POST   /auth/change-password   - Changement de mot de passe

Utilisateurs

GET    /users                  - Lister les utilisateurs (Admin)
GET    /users/:id              - Obtenir un utilisateur
PATCH  /users/:id              - Mettre à jour un utilisateur
DELETE /users/:id              - Supprimer un utilisateur

Tâches (API v1)

GET    /api/v1/tasks              - Lister les tâches de l'utilisateur
POST   /api/v1/tasks              - Créer une nouvelle tâche
GET    /api/v1/tasks/:id          - Obtenir les détails d'une tâche
PUT    /api/v1/tasks/:id          - Mettre à jour une tâche
DELETE /api/v1/tasks/:id          - Supprimer une tâche
POST   /api/v1/tasks/:id/execute  - Exécuter une tâche immédiatement
GET    /api/v1/tasks/:id/logs     - Obtenir les logs d'exécution

Dashboard

GET    /dashboard/overview        - Aperçu général
GET    /dashboard/metrics         - Métriques en temps réel
GET    /dashboard/recent-tasks    - Tâches récentes

Analytics

GET    /analytics/dashboard       - Dashboard analytics
GET    /analytics/summary         - Résumé des métriques
GET    /analytics/cohorts         - Analyse de cohortes
GET    /analytics/engagement      - Métriques d'engagement

Rapports

GET    /reports/executive-summary - Rapport exécutif
GET    /reports/custom            - Rapports personnalisés
POST   /reports/custom            - Créer un rapport personnalisé
GET    /reports/:id/execute       - Exécuter un rapport

Admin

GET    /admin/users               - Gestion des utilisateurs
GET    /admin/analytics           - Analytics administratifs
GET    /admin/audit-logs          - Logs d'audit
GET    /admin/security-alerts     - Alertes de sécurité
POST   /admin/roles/:userId       - Attribuer un rôle à un utilisateur
DELETE /admin/roles/:userId/:role - Retirer un rôle d'un utilisateur

Facturation

GET    /billing/subscription      - Obtenir l'abonnement actuel
POST   /billing/subscription      - Créer un abonnement
PUT    /billing/subscription      - Mettre à jour un abonnement
DELETE /billing/subscription      - Annuler un abonnement
POST   /webhooks/stripe           - Webhook Stripe

Notifications

GET    /notifications             - Lister les notifications
GET    /notifications/:id         - Obtenir une notification
PATCH  /notifications/:id/read    - Marquer comme lue
GET    /notifications/preferences - Obtenir les préférences
PUT    /notifications/preferences - Mettre à jour les préférences

Santé & Statut

GET    /health                    - Contrôle de santé
GET    /api/status                - Statut de l'API

Documentation

GET    /api/docs                  - Interface Swagger
GET    /api-json                  - Spécification OpenAPI JSON

Types de Tests

  1. Tests Unitaires - *.spec.ts dans chaque module
  2. Tests E2E - test/*.e2e-spec.ts contre une vraie base de données
  3. Smoke Tests - test/jest-smoke.json pour validation rapide

Tests Contre une Vraie Base de Données

Le projet utilise une base de données PostgreSQL sur Neon pour les tests E2E, pas de mocks. Cela garantit que les tests reflètent le comportement réel.

📊 Audit et Assurance Qualité

Système de Suivi

Issues Critiques Identifiés

  1. #1 - Incohérence du hachage de mot de passe (auth vs users)
  2. #2 - Dépendances circulaires entre users et auth
  3. #3 - Problèmes de type safety avec les casts ‘as any’
  4. #4 - Gestion de file d’attente manquante pour les notifications
  5. #5 - Vulnérabilité d’injection de commande dans la génération PDF

Issues Majeurs

  1. #6 - Implémenter le point de terminaison duplicateTask
  2. #7 - Remplacer les implémentations mock dans les rapports
  3. #8 - Suivi réel de la durée des tâches
  4. #9 - Champs de base de données manquants (tags, status)
  5. #10 - Limitation de débit pour le service email

Audit Complet (2025-09-27)

  • Modules audités: 12
  • Issues identifiés: 35 (8 critical, 7 major, 20 minor)
  • Préparation à la production: 75%
  • Score général: ✅ Architecture excellente, issues gérables

🔗 Liens et Ressources

Développement

GitHub

Base de Données

  • Fournisseur: Neon PostgreSQL (cloud)

Documentation Externe

📄 Licence

Licence MIT - Voir le fichier LICENSE pour les détails

📞 Support

État actuel: ✅ Backend complet et fonctionnel avec 15 issues identifiés en attente pour la production

Dernière mise à jour: 2025-10-17 Version du document: 1.0

Créé avec ❤️ par l’équipe NoCron