diff --git a/docs/superpowers/specs/2025-05-12-daily-summary-design.md b/docs/superpowers/specs/2025-05-12-daily-summary-design.md new file mode 100644 index 0000000..f28efd3 --- /dev/null +++ b/docs/superpowers/specs/2025-05-12-daily-summary-design.md @@ -0,0 +1,96 @@ +# Dagelijkse WhatsApp samenvatting — Design + +## Doel + +Elke dag om 10:00 uur een WhatsApp-bericht sturen naar de admin (31620248011) met het totaal aantal dienstaanvragen van de vorige dag (00:00 t/m 23:59). + +## Requirement samenvatting + +| Item | Keuze | +|------|-------| +| Inhoud bericht | Alleen totaal aantal | +| Periode | Vorige kalenderdag (00:00-23:59) | +| Persistentie | In-memory (geen disk) | +| Verzendtijd | 10:00 elke ochtend | +| Ontvanger | `ADMIN_NUMBER` uit `.env` (31620248011@c.us) | + +## Architectuur + +### Nieuwe module: `src/dailyStats.js` + +Houdt twee tellers bij in memory: + +- `dailyTotal` — aantal aanvragen vandaag (lopende dag) +- `yesterdayTotal` — aantal aanvragen van gisteren (voor verzending om 10:00) + +Publieke API: + +- `increment()` — verhoogt `dailyTotal` met 1 +- `getYesterdayTotal()` — returned `yesterdayTotal` +- `resetDay()` — zet `yesterdayTotal = dailyTotal`, dan `dailyTotal = 0` + +### Scheduling: `node-cron` + +Cron expressie `0 10 * * *` triggert exact om 10:00 elke dag een callback die: + +1. `dailyStats.resetDay()` aanroept (snapshot van gisteren) +2. `sendTextMessage(adminNumber, bericht)` aanroept om het totaal te versturen +3. Bij falen van verzending: error loggen, maar reset blijft van kracht + +### Bestaande modules — wijzigingen + +**`src/index.js`** +- Importeert `node-cron` en `dailyStats` +- Registreert cron job bij server startup +- Huidige `express` setup blijft ongewijzigd + +**`src/messageHandler.js`** +- Importeert `dailyStats` +- Roept `dailyStats.increment()` aan na de bestaande `increment(author)` (rate limiter) + +### Data flow + +``` +webhook POST /webhook + → messageHandler.handleWebhook() + → rateLimiter.increment(author) [bestaand] + → dailyStats.increment() [nieuw, 1 regel] + +om 10:00 (node-cron trigger): + → dailyStats.resetDay() + → whatsappApi.sendTextMessage(admin, "Aantal dienstaanvragen gisteren: N") +``` + +### Foutafhandeling + +- Verzending faalt → error wordt gelogd, geen retry, reset is al gedaan +- Server herstart voor 10:00 → `dailyTotal` en `yesterdayTotal` zijn 0, cron start opnieuw, om 10:00 wordt bericht met "0" verstuurd (verlies van telling geaccepteerd conform in-memory keuze) +- Server draait niet om 10:00 → geen bericht die dag + +### Afhankelijkheden + +- `node-cron` toevoegen aan `package.json` +- Geen nieuwe `.env` variabelen — `ADMIN_NUMBER` wordt hergebruikt + +### Berichtformaat + +``` +Aantal dienstaanvragen gisteren: N +``` + +Waar `N` het totaal aantal is van 00:00 tot 23:59 van de vorige kalenderdag. + +## Teststrategie + +1. **`dailyStats` unit tests** + - `increment()` verhoogt `dailyTotal` correct + - `resetDay()` kopieert `dailyTotal` naar `yesterdayTotal` en zet `dailyTotal` op 0 + - `getYesterdayTotal()` returned gecachte waarde + +2. **Integratietest** + - Cron callback handmatig aanroepen → verifieer dat `sendTextMessage` wordt aangeroepen met juiste admin nummer en bericht + +## Scope & grenzen + +- Binnen scope: teller bijhouden, cron trigger, WhatsApp verzending +- Buiten scope: persistentie op disk, uitsplitsingen per gebruiker/dienst, herstel van gemiste data na crash, historische rapportages \ No newline at end of file