94263c6447
Le check-in remplace l'intégration banking V1 (cf. CLAUDE.md → Glossaire) :
avant que la 1re relance ne parte, on demande à l'user "as-tu été payé ?"
via email, et il clique sur l'un des 2 liens publics.
Service checkin_token.ts : génération + hash SHA-256. 32 bytes random base64url, plain dans le mail, hash en DB (CheckinTask.token_hash unique).
Service checkin_scheduler.ts :
- scheduleCheckinForInvoice(invoice) : crée 1 CheckinTask à dueDate (now+1min si dueDate dans le passé). Idempotent par invoice — cancel les scheduled précédents avant.
- cancelCheckinForInvoice(invoiceId) : appelé par mark-paid pour stopper.
Job send_checkin_job.ts : worker queue 'checkins', skip si invoice paid/cancelled (no-op), construit l'URL avec le plain token (passé dans le payload du job, pas relu DB), appelle sendCheckinEmail.
mail_dispatcher.ts : sendCheckinEmail() — texte brut, destinataire = user (pas client !), 2 URLs (paid / pending), TTL 24h annoncé.
Controller CheckinController :
- GET /api/v1/checkin/:token/paid : status=answered + answer=paid + mark invoice paid (mêmes effets que POST /invoices/:id/mark-paid : rubis +1, ActivityEvent invoice_paid avec label "via check-in", cancelFutureRelances). Idempotent : 2e click → redirect "already_answered".
- GET /api/v1/checkin/:token/pending : status=answered + answer=still_pending. Les relances suivent leur cours.
- Validation : lookup hash, expiry (sentAt + 24h), redirects propres pour invalid / expired / already_answered.
Routes : nouveau group public `checkin` (PAS de middleware.auth) à côté du group auth, sous /api/v1.
Triggers branchés :
- InvoicesController.store et ImportBatchesController.validateDraft → scheduleCheckinForInvoice après création
- InvoicesController.markPaid → cancelCheckinForInvoice dans la tx
start/queue.ts : registerWorker('checkins', sendCheckinJob).
env : nouveau WEB_URL (URL du SPA pour redirects), default localhost:5173 en dev.
Bruno : nouveau dossier 08-Checkin avec doc complète du flow + 2 requêtes (paid / pending). var d'env `checkinToken` à remplir manuellement après avoir reçu l'email dans Mailpit.
41 lines
1.4 KiB
Plaintext
41 lines
1.4 KiB
Plaintext
meta {
|
|
name: Checkin
|
|
seq: 9
|
|
}
|
|
|
|
docs {
|
|
## Check-in — endpoints PUBLICS (pas d'auth Bearer)
|
|
|
|
Le check-in est l'email envoyé à **l'utilisateur** (pas au client) pour
|
|
confirmer qu'une facture a été payée AVANT que la première relance ne
|
|
parte (cf. CLAUDE.md → Glossaire). Remplace l'intégration banking V1.
|
|
|
|
## Flow
|
|
|
|
1. Quand une facture avec un plan est créée, `scheduleCheckinForInvoice`
|
|
enqueue un BullMQ job à `dueDate` (pile à l'échéance).
|
|
2. À l'exécution, `SendCheckinJob` envoie un email à l'user avec 2
|
|
liens : "C'est payé" et "Toujours en attente".
|
|
3. L'user clique → endpoint public ci-dessous → DB update + redirect SPA.
|
|
|
|
## Token
|
|
|
|
- 32 bytes random base64url, généré au schedule.
|
|
- Stocké hashé (SHA-256) en DB (CheckinTask.token_hash).
|
|
- TTL 24h après envoi (sentAt + 24h).
|
|
- Une seule réponse possible (idempotent : 2e click → already_answered).
|
|
|
|
## Pourquoi pas d'auth Bearer ?
|
|
|
|
L'utilisateur clique depuis sa boîte mail — pas de session JS active.
|
|
Le token est l'authentification : sa connaissance vaut autorisation
|
|
(avec TTL 24h pour limiter la fenêtre de risque).
|
|
|
|
## Pour tester
|
|
|
|
Crée une facture avec dueDate dans le passé (Invoices → 04 Create) :
|
|
le check-in est programmé à `now + 1min`. ~1min plus tard, regarde
|
|
Mailpit http://localhost:8025 → tu vois l'email avec les 2 liens.
|
|
Copie le token de l'URL et utilise les requêtes Bruno ci-dessous.
|
|
}
|