Skip to content

Commit 28b598b

Browse files
DayifourDayifour
committed
add: Great Readme.md
1 parent 21c270f commit 28b598b

1 file changed

Lines changed: 232 additions & 126 deletions

File tree

‎README.md‎

Lines changed: 232 additions & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -63,130 +63,236 @@ Depuis la refonte, le service est **strictement dépendant des coordonnées four
6363
- Le schéma Zod impose :
6464
- `type` = `"transfer"`.
6565
- `sender.email` / `sender.phone` obligatoires.
66-
- `receiver.email` / `receiver.phone` obligatoires.
67-
- `amount > 0`.
68-
- `content` non vide.
69-
- Le service crée **deux paires de notifications** (SMS + EMAIL) :
70-
- Pour l’expéditeur (role = `SENDER`).
71-
- Pour le destinataire (role = `RECEIVER`).
72-
- Les messages sont envoyés :
73-
- par SMS via Twilio sur `phone`.
74-
- par email via `mailService.sendEmail` sur `email`.
75-
- Le `context` des entités `Notification` contient notamment `montant` et `role`.
76-
77-
#### b) Notification simple (autres types)
66+
# Notification-Service
67+
68+
Service de notifications (e-mail & SMS & OTP) développé en Node.js, Express et TypeScript.
69+
70+
Ce README décrit l'installation, la configuration, les endpoints, les variables d'environnement et les bonnes pratiques pour déployer et tester le service.
71+
72+
Table des matières
73+
- Présentation
74+
- Prérequis
75+
- Installation
76+
- Variables d'environnement
77+
- Commandes utiles
78+
- Endpoints et exemples
79+
- Health checks
80+
- Docker / Compose
81+
- Débogage et logs
82+
- Notes de sécurité
83+
84+
---
85+
86+
Présentation
87+
------------
88+
Ce service reçoit des requêtes HTTP pour envoyer des notifications et générer/vérifier des OTP. Il s'intègre avec :
89+
- PostgreSQL (TypeORM)
90+
- RabbitMQ (échange partagé, queue privée)
91+
- Twilio (SMS)
92+
- Nodemailer (e-mail)
93+
94+
Le code organise les responsabilités en contrôleurs, services, entités, utilitaires et messaging (publisher/consumer).
95+
96+
Prérequis
97+
---------
98+
- Node.js >= 18
99+
- npm
100+
- PostgreSQL accessible (ou instance locale)
101+
- RabbitMQ accessible (ou instance locale)
102+
- Compte Twilio (si SMS en production) ou configuration de mock
103+
- Compte e-mail (Gmail ou SMTP compatible) pour envoi d'e-mails
104+
105+
Installation
106+
------------
107+
1. Cloner le dépôt et positionnez-vous dans le dossier du service :
108+
109+
```bash
110+
cd notification_service
111+
```
112+
113+
2. Installer les dépendances :
114+
115+
```bash
116+
npm install
117+
```
118+
119+
3. Compiler TypeScript :
120+
121+
```bash
122+
npm run build
123+
```
124+
125+
4. Lancer en développement (reload automatique) :
126+
127+
```bash
128+
npm run dev
129+
```
130+
131+
Variables d'environnement
132+
------------------------
133+
Les variables attendues par le service (fichier `.env` recommandé) :
134+
135+
- SERVICE_PORT: port d'écoute HTTP (ex: 8000)
136+
- SERVICE_VERSION: version déployée (optionnel)
137+
- COMMIT_SHA: sha du commit déployé (optionnel)
138+
139+
- PostgreSQL:
140+
- DB_HOST
141+
- DB_PORT (par défaut 5432)
142+
- DB_USER
143+
- DB_PASSWORD
144+
- DB_NAME
145+
146+
- RabbitMQ:
147+
- RABBITMQ_URL (ex: amqp://user:pass@host:5672)
148+
- RABBITMQ_EXCHANGE (nom de l'exchange partagé)
149+
- RABBITMQ_QUEUE (nom de la queue principale pour ce service)
150+
151+
- Twilio (si SMS) :
152+
- TWILIO_ACCOUNT_SID
153+
- TWILIO_AUTH_TOKEN
154+
- TWILIO_PHONE_NUMBER
155+
156+
- E-mail (Nodemailer) :
157+
- MAIL_USER
158+
- MAIL_PASS
159+
160+
- Health / diagnostics (optionnel) :
161+
- HEALTH_CHECK_TIMEOUT_MS (ms, défaut 1000)
162+
- HEALTH_CACHE_TTL_MS (ms, défaut 5000)
163+
- HEALTH_EXPOSE_ERRORS (true|false, défaut false)
164+
165+
Commandes utiles
166+
----------------
167+
- `npm run dev` — démarre avec `ts-node-dev` (dev hot-reload)
168+
- `npm run build` — compile TypeScript vers `dist/`
169+
- `npm start` — exécute `node src/server.ts` (production si compilé)
170+
171+
Endpoints et exemples
172+
---------------------
173+
Base URL: `http://{host}:{SERVICE_PORT}`
174+
175+
Health
176+
- `GET /health` — liveness minimal (retourne OK + uptime)
177+
- `GET /health/ready` — readiness : vérifie PostgreSQL et RabbitMQ, retourne 200 ou 503. Réponse contient `components.db` et `components.rabbitmq`.
178+
179+
Notifications
180+
- `POST /api/notifications/envoyer` — envoie une notification.
181+
- Corps possible (exemples) :
182+
183+
Transfer (expéditeur + destinataire envoyés sur SMS + email si fournis) :
184+
185+
```json
186+
{
187+
"type": "transfer",
188+
"sender": { "email": "a@ex.com", "phone": "+223xxxxxxxx" },
189+
"receiver": { "email": "b@ex.com", "phone": "+223yyyyyyyy" },
190+
"amount": 10000,
191+
"content": "Votre transfert de 10000 F CFA a été effectué"
192+
}
193+
```
194+
195+
Simple notification :
196+
197+
```json
198+
{
199+
"type": "alert_securite",
200+
"user": { "email": "u@ex.com", "phone": "+223zzzzzzzz" },
201+
"content": "Un événement important a eu lieu"
202+
}
203+
```
204+
205+
- Réponse : `201` + objet décrivant les enregistrements créés (sms / email)
206+
207+
- `POST /api/notifications/rabbitmq` — endpoint de test qui publie un message sur RabbitMQ (routingKey/message dans body)
208+
209+
OTP
210+
- `POST /api/notifications/otp/generate` — génère un OTP
211+
- Body example:
212+
```json
213+
{ "utilisateurId": "user-123", "canalNotification": "SMS", "phone": "+223..." }
214+
```
215+
216+
- `POST /api/notifications/otp/verify` — vérifie un OTP
217+
- Body example:
218+
```json
219+
{ "utilisateurId": "user-123", "code": "1234" }
220+
```
221+
222+
Health checks (détails)
223+
-----------------------
224+
- `/health` est une probe de liveness simple, utile pour Kubernetes readiness/liveness probes basiques.
225+
- `/health/ready` exécute des vérifications actives :
226+
- exécute `SELECT 1` sur PostgreSQL (avec timeout configurable)
227+
- vérifie que le channel RabbitMQ est initialisé
228+
- met en cache le résultat pendant `HEALTH_CACHE_TTL_MS` pour limiter la charge
229+
- renvoie `version` et `commit` si disponibles
230+
231+
Docker / Compose
232+
-----------------
233+
Le repo contient un `Dockerfile` et un `docker-compose.yml` :
234+
235+
Construction :
236+
237+
```bash
238+
docker build -t ricash/notification-service:latest .
239+
```
240+
241+
Compose (exemple très simple) :
242+
243+
```yaml
244+
version: '3.8'
245+
services:
246+
notification-service:
247+
image: ricash/notification-service:latest
248+
env_file: .env
249+
ports:
250+
- "8000:8000"
251+
depends_on:
252+
- db
253+
- rabbitmq
254+
255+
db:
256+
image: postgres:15
257+
environment:
258+
POSTGRES_USER: example
259+
POSTGRES_PASSWORD: example
260+
POSTGRES_DB: ricash
261+
262+
rabbitmq:
263+
image: rabbitmq:3-management
264+
ports:
265+
- "5672:5672"
266+
- "15672:15672"
267+
```
268+
269+
Débogage et logs
270+
---------------
271+
- Les logs sont écrits sur stdout.
272+
- Vérifier les erreurs de connexion à RabbitMQ et PostgreSQL au démarrage.
273+
- En cas d'erreurs d'envoi SMS/Email, les exceptions sont loggées et le statut de la notification est mis à `ECHEC`.
274+
275+
Sécurité et bonnes pratiques
276+
---------------------------
277+
- Ne pas exposer `HEALTH_EXPOSE_ERRORS=true` en production si les messages d'erreur contiennent des données sensibles.
278+
- Utiliser des secrets manager pour les identifiants (DB, Twilio, MAIL_PASS).
279+
- Désactiver `synchronize: true` (TypeORM) en production et utiliser des migrations contrôlées.
280+
281+
Contribution
282+
------------
283+
Pour proposer des améliorations :
284+
1. Créer une branche feature
285+
2. Ajouter tests / valider localement
286+
3. Ouvrir une Pull Request vers `develop`
287+
288+
Support
289+
-------
290+
Si tu veux, je peux :
291+
- ajouter des exemples Postman
292+
- créer un `docker-compose.dev.yml` complet pour démarrer la stack locale
293+
- ajouter des tests unitaires pour `NotificationService` / `OtpService`
294+
295+
---
296+
297+
Fait avec ❤️ — Notification-Service
78298

79-
```json
80-
{
81-
"type": "ALERT_SECURITE",
82-
"user": {
83-
"email": "client@mail.com",
84-
"phone": "+22322222222"
85-
},
86-
"content": "Connexion suspecte détectée."
87-
}
88-
```
89-
90-
- `type` peut être l’une des valeurs de `TypeNotification` (sauf `"transfer"` qui utilise le schéma dédié).
91-
- `user.email` et `user.phone` sont obligatoires.
92-
- Le service envoie systématiquement la notification **à la fois par SMS et par email**.
93-
94-
En cas de JSON invalide (champ manquant / mauvais type), le contrôleur renvoie :
95-
96-
```json
97-
{
98-
"success": false,
99-
"message": "Corps de requête invalide",
100-
"errors": { ...détail Zod... }
101-
}
102-
```
103-
104-
### 2. Génération d’OTP
105-
106-
`POST /api/notifications/otp/generate`
107-
108-
Le service génère un code OTP (4 chiffres), l’enregistre en base avec une expiration (5 minutes) puis publie un événement `otp.verification` sur RabbitMQ. Désormais, il dépend **strictement** des coordonnées envoyées dans le JSON.
109-
110-
```json
111-
{
112-
"utilisateurId": "user-otp-1",
113-
"canalNotification": "SMS",
114-
"email": "userotp@mail.com",
115-
"phone": "+22300000000"
116-
}
117-
```
118-
119-
- `utilisateurId`: identifiant métier (user id).
120-
- `canalNotification`: `"SMS"` ou `"EMAIL"`.
121-
- `email`: email du destinataire (obligatoire).
122-
- `phone`: numéro du destinataire (obligatoire).
123-
124-
│ │ ├── Notification.ts # Modèle de données pour les notifications
125-
126-
L’événement publié (contrat inter-services) contient :
127-
128-
```json
129-
{
130-
"utilisateurId": "user-otp-1",
131-
"typeNotification": "VERIFICATION_TELEPHONE",
132-
"canal": "SMS",
133-
"context": { "code": "1234" },
134-
"email": "userotp@mail.com",
135-
"phone": "+22300000000",
136-
"metadata": {
137-
"service": "notification-service:otp",
138-
"correlationId": "otp-<id>"
139-
}
140-
}
141-
```
142-
143-
Les templates de message utilisent ce `context` pour produire des textes explicites, par exemple :
144-
145-
- `VERIFICATION_TELEPHONE` :
146-
> « Votre code OTP de vérification téléphone est : {code}. Ce code est valable 5 minutes. Ne le partagez jamais avec un tiers. »
147-
148-
### 3. Vérification d’un OTP
149-
150-
`POST /api/notifications/otp/verify`
151-
152-
Body JSON :
153-
154-
```json
155-
{
156-
"utilisateurId": "user-otp-1",
157-
"code": "1234"
158-
}
159-
```
160-
161-
Réponses possibles :
162-
163-
```json
164-
{ "success": true, "message": "OTP validé" }
165-
{ "success": false, "message": "Code invalide" }
166-
{ "success": false, "message": "Code expiré" }
167-
{ "success": false, "message": "Ce code a déjà été utilisé" }
168-
```
169-
170-
---
171-
172-
│ │ ├── Otp.ts # Modèle de données pour les OTP (code, expiration, utilisateur)
173-
│ │
174-
│ ├── routes/
175-
│ │ ├── notificationRoutes.ts # Définition des routes Express pour les notifications et OTP
176-
│ │
177-
│ ├── services/
178-
│ │ ├── notificationService.ts # Logique métier liée aux notifications
179-
│ │ ├── otpService.ts # Logique métier liée aux OTP
180-
│ │
181-
│ ├── utils/
182-
│ │ ├── mailService.ts # Gère l’envoi des e-mails (transporteur, configuration…)
183-
│ │ ├── messageTemplates.ts # Contient les templates des messages
184-
│ │
185-
│ ├── app.ts # Configuration principale de l’application Express
186-
│ ├── data-source.ts # Configuration et connexion à la base de données
187-
│ ├── index.ts # Point d’entrée pour la déclaration des routes
188-
│ ├── server.ts # Lancement du serveur Express
189-
│
190-
├── .env # Variables d’environnement (PORT, DB_URL, etc.)
191-
├── package.json # Dépendances et scripts du projet
192-
├── tsconfig.json # Configuration TypeScript

0 commit comments

Comments
 (0)