diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index 6be64e3..5ac13a4 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -13,6 +13,7 @@ 9. [Validačné schémy](#9-validačné-schémy) 10. [Konfigurácia](#10-konfigurácia) 11. [Autentizácia a bezpečnosť](#11-autentizácia-a-bezpečnosť) +12. [Cron Jobs a Notifikácie](#12-cron-jobs-a-notifikácie) --- @@ -98,6 +99,13 @@ crm-server/ │ │ ├── search.js # JMAP vyhľadávanie │ │ └── sync.js # JMAP synchronizácia │ │ +│ ├── cron/ +│ │ ├── index.js # Hlavný cron entry point +│ │ └── calendar/ +│ │ ├── index.js # Kalendárny cron scheduler +│ │ ├── email-template.js # HTML email šablóna +│ │ └── event-notifier.js # Logika notifikácií +│ │ │ ├── routes/ │ │ ├── auth.routes.js │ │ ├── admin.routes.js @@ -516,6 +524,7 @@ Audit trail všetkých akcií. | PATCH | `/users/:userId/role` | Zmeniť rolu | Áno | Admin | | DELETE | `/users/:userId` | Zmazať usera | Áno | Admin | | GET | `/server-status` | Server status | Áno | Admin | +| POST | `/trigger-notifications` | Manuálne spustiť notifikácie | Áno | Admin | ### Companies (`/api/companies`) @@ -1299,6 +1308,11 @@ BCRYPT_ROUNDS=12 # CORS CORS_ORIGIN=http://localhost:5173 +# Notifikácie +NOTIFICATION_TIME=07:00 # Čas odosielania (HH:mm) +NOTIFICATION_SENDER_EMAIL=riso@slovensko.ai # Email odosielateľa (musí byť v DB) +NOTIFICATION_TEST_MODE=false # true = cron beží každú minútu + # Rate Limiting RATE_LIMIT_WINDOW_MS=900000 RATE_LIMIT_LOGIN_MAX=5 @@ -1387,6 +1401,150 @@ export default { --- +## 12. Cron Jobs a Notifikácie + +### Prehľad + +Systém obsahuje automatické cron joby pre odosielanie emailových notifikácií. Cron jobs sa spúšťajú automaticky pri štarte servera. + +### Štruktúra + +``` +src/cron/ +├── index.js # Hlavný entry point - spúšťa všetky cron jobs +└── calendar/ + ├── index.js # Kalendárny cron scheduler + ├── email-template.js # HTML email šablóna pre notifikácie + └── event-notifier.js # Logika pre odosielanie notifikácií +``` + +### Kalendárne notifikácie + +#### Ako to funguje + +1. **Cron beží každý deň** o čase nastavenom v `NOTIFICATION_TIME` (default: 07:00) +2. **Vyhľadá eventy** ktoré začínajú **zajtra** (00:00 - 23:59) +3. **Získa priradených používateľov** cez `eventUsers` junction tabuľku +4. **Zistí primárny email** každého používateľa z `userEmailAccounts` +5. **Odošle HTML email** cez JMAP z účtu nastaveného v `NOTIFICATION_SENDER_EMAIL` + +#### Kedy sa notifikácie posielajú + +| Event začína | Notifikácia | +|--------------|-------------| +| Včera / dnes (minulosť) | ❌ Nie | +| Zajtra | ✅ Áno | +| Pozajtra a neskôr | ❌ Nie | + +#### Konfigurácia + +```bash +# .env +NOTIFICATION_TIME=07:00 # Čas odosielania (formát HH:mm) +NOTIFICATION_SENDER_EMAIL=riso@slovensko.ai # Email účet v databáze +NOTIFICATION_TEST_MODE=false # true = cron beží každú minútu +``` + +**Dôležité:** `NOTIFICATION_SENDER_EMAIL` musí byť email účet uložený v tabuľke `email_accounts` s platným zašifrovaným heslom. + +#### Testovací mód + +Pre testovanie nastavte v `.env`: + +```bash +NOTIFICATION_TEST_MODE=true +``` + +Cron bude bežať **každú minútu** namiesto raz denne. Po dokončení testovania nastavte späť na `false`. + +#### Manuálne spustenie + +Admin môže manuálne spustiť notifikácie cez API: + +```bash +POST /api/admin/trigger-notifications +Authorization: Bearer +``` + +**Response:** +```json +{ + "success": true, + "data": { + "sent": 2, + "failed": 0, + "skipped": 1 + }, + "message": "Notifikácie odoslané: 2, neúspešné: 0, preskočené: 1" +} +``` + +- `sent` - Počet úspešne odoslaných emailov +- `failed` - Počet neúspešných odoslaní +- `skipped` - Počet preskočených (napr. používateľ nemá nastavený email) + +### Email šablóna + +Notifikačný email obsahuje: + +- **Header** s logom CRM +- **Pozdrav** s menom používateľa +- **Karta eventu** s: + - Typ (Stretnutie / Udalosť) - farebne odlíšené + - Názov eventu + - Popis (ak existuje) + - Dátum a čas +- **Footer** s informáciou o automatickom generovaní + +Email je responzívny a zobrazuje sa správne v rôznych email klientoch. + +### Logy + +Pri behu cron jobu sa zobrazujú logy: + +``` +[INFO] === Inicializujem cron jobs === +[INFO] Nastavujem cron pre kalendárne notifikácie: 00 07 * * * (07:00 každý deň) +[SUCCESS] Kalendárny notifikačný cron naplánovaný: 07:00 každý deň (Europe/Bratislava) +[INFO] === Všetky cron jobs inicializované === + +# Pri spustení jobu: +[INFO] Cron job spustený - kontrolujem zajtrajšie udalosti +[INFO] === Spúšťam kontrolu zajtrajších udalostí === +[INFO] Hľadám udalosti od 2025-12-16T00:00:00.000Z do 2025-12-16T23:59:59.999Z +[INFO] Nájdených 2 priradení udalostí na zajtra +[INFO] Unikátnych notifikácií na odoslanie: 2 +[INFO] Odosielam notifikáciu pre admin (riso@slovensko.ai) - udalosť: Team meeting +[SUCCESS] Email úspešne odoslaný na riso@slovensko.ai +[INFO] === Hotovo: odoslaných 2, neúspešných 0, preskočených 0 === +``` + +### Rozšírenie + +Pre pridanie nových cron jobs: + +1. Vytvorte nový folder v `src/cron/` (napr. `reminders/`) +2. Implementujte logiku podobne ako v `calendar/` +3. Exportujte start funkciu +4. Importujte a zavolajte v `src/cron/index.js` + +```javascript +// src/cron/index.js +import { startCalendarNotificationCron } from './calendar/index.js'; +import { startRemindersCron } from './reminders/index.js'; // nový + +export const startAllCronJobs = () => { + logger.info('=== Inicializujem cron jobs ==='); + + startCalendarNotificationCron(); + startRemindersCron(); // nový + + logger.info('=== Všetky cron jobs inicializované ==='); +}; +``` + +--- + ## Záver Táto dokumentácia poskytuje kompletný prehľad CRM Server backendu. Pre ďalšie informácie kontaktujte administrátora projektu.