157 lines
5.5 KiB
Markdown
157 lines
5.5 KiB
Markdown
# 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.)
|