adastra_api/.github/copilot-instructions.md

Instructions pour les agents Copilot / AI

But : fournir à un agent IA les informations essentielles pour être immédiatement productif dans ce workspace.

Vue d'ensemble des projets

• adastra_api/ : API Express/Node.js avec Sequelize (MySQL) + Mongoose (Mongo)
• adastra_app/ : Frontend Angular 17

Entrées principales de l'application

API (adastra_api)

• Point d'entrée : app.js (racine du projet)

  • Charge les variables d'environnement via APP_ENV (.env.${APP_ENV})
  • Initialise les middlewares (CORS, Morgan, session, etc.)
  • Connecte MongoDB et MySQL
  • Lance le serveur sur le port (défaut : 3200)

• Routage Express : src/app.js et src/routes/

  • Toutes les routes API sont sous /api/v1
  • Exemple : GET /api/v1/articles → src/controllers/article.controller.js

• Contrôleurs : src/controllers/

  • Gèrent la logique métier, validations, réponses JSON
  • Suivent le pattern : controller → service → utils → database

Frontend (adastra_app)

• Point d'entrée : src/main.ts (bootstrap Angular)
• Configuration : angular.json (builds, configurations, assets)
• Routes : src/app/app.routes.ts
• Composants : src/app/components/
• Styles globaux : src/styles/

Architecture et patterns clés

Structure des données

• Sequelize (MySQL) : modèles dans src/database/models/

  • Utilise sequelize-cli pour les migrations (si applicable)
  • Auto-généré avec sequelize-auto

• Mongoose (MongoDB) : modèles dans src/database/models/mongo

  • Initialisé avec require('./src/database/models/mongo')

Gestion des erreurs

Middleware centralisé dans src/middlewares/exceptions.handler :

• notFoundErrorHandler : capture 404
• logErrorHandler : log des erreurs
• fianlErrorHandler : réponse finale au client

Authentification & configuration

• Passport : src/config/passport-local.js, passport-headerapikey.js
• Config générale : src/config/index.js (secrets, session lifetime, DB)
• Variables d'environnement : .env.${APP_ENV} (local, development, production)

Commandes essentielles

API (adastra_api)

# Installation
cd adastra_api && npm install

# Développement (avec hot reload via nodemon)
npm run local        # APP_ENV=local nodemon ./app.js (port 3200)

# Production/Staging
npm run dev          # APP_ENV=development node ./app.js
npm run start        # APP_ENV=production node ./app.js

# Tests
npm test             # Newman : exécute tests/adastra-api-tests.postman_collection.json

# Arrêter le serveur
npm run stop         # Tue le processus sur le port 3200

# MongoDB (Docker)
npm run mongo:start  # Lance le conteneur Mongo (port 27017)
npm run mongo:stop   # Arrête et nettoie le conteneur

Frontend (adastra_app)

# Installation
cd adastra_app && npm install

# Développement
npm run local        # ng serve --configuration local --port 4400
npm start            # ng serve (port 4200 par défaut)
npm run dev          # ng serve --configuration local --port 4200

# Build
npm run build        # Production build (dist/)
npm run watch        # Watch mode

# Linting
npm run lint         # ESLint

Conventions et bonnes pratiques

Ajout d'une nouvelle route API

1. Créer/modifier la route dans src/routes/ (ex. src/routes/api/v2/articles.routes.js)
2. Implémenter le contrôleur dans src/controllers/article.controller.js
3. Ajouter validation dans src/validations/ si nécessaire
4. Tester via Postman → exporter en tests/adastra-api-tests.postman_collection.json

Ajout d'un modèle de données

• Sequelize : créer le fichier dans src/database/models/, utiliser sequelize-cli si migrations
• Mongoose : créer le schéma dans src/database/models/mongo/, importer dans src/database/models/mongo/index.js

Structure de réponse API

Vérifier src/controllers/ pour le format des réponses — généralement :

res.status(200).json({ data: [...], message: 'Success' });
res.status(400).json({ error: 'Validation failed', details: [...] });

Variables d'environnement essentielles

À définir dans .env.local, .env.development, .env.production :

• SERVER_PORT : port du serveur (défaut 3200)
• APP_ENV : local, development, ou production
• DB_HOST, DB_USER, DB_PASS, DB_NAME : configuration MySQL
• MONGO_URI : URI de MongoDB
• Clés API externes (SendGrid, etc.)

Points d'attention

• Ne pas modifier directement l'ordre des middlewares dans app.js sans tester l'intégralité du flow
• Versions Node : respecter engines dans package.json (^16.20.2 || ^18.19.1 || ^20.11.1)
• Dépendances critiques : express, sequelize, mongoose, passport, jsonwebtoken

Ressources utiles pour un agent

Si tu dois ajouter/modifier du code, consulte d'abord :

1. Contrôleur similaire existant : ex. src/controllers/member.controller.js pour le pattern
2. Route similaire existante : src/routes/ pour voir comment router
3. Config/Middleware : vérifier si logique centralisée existe déjà (src/middlewares/, src/config/)
4. Tests Postman : tests/adastra-api-tests.postman_collection.json pour valider les endpoints et tests/adastra-api-tests.postman_environment.json pour les variables d'environnement

---

Questions manquantes ? Demande-moi les détails sur :

• Structure exacte des schémas Sequelize/Mongoose
• Authentification et système d'autorisations
• Workflows de déploiement ou CI/CD
• Intégration frontend/backend (headers, tokens, etc.)