docs: Add cron jobs and notifications documentation
- Add section 12: Cron Jobs a Notifikácie - Update project structure with cron/ folder - Add admin trigger-notifications endpoint to API docs - Add notification env variables to config section - Include examples, logs, and extension guide 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
richardtekula
158
DOCUMENTATION.md
158
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 <admin_token>
|
||||
```
|
||||
|
||||
**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.
|
||||
|
||||
Reference in New Issue
Block a user