# 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)

```bash
# 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)

```bash
# 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 :
```javascript
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.)