a6b35dfe7a
Migrations :
- relance_tasks (uuid id, organization_id FK CASCADE [scope direct sans join], invoice_id FK CASCADE, plan_step_id FK RESTRICT, send_at, status ENUM scheduled/sent/cancelled/failed, sent_at, queue_job_id pour cancel via BullMQ.remove). Indexes (org,status), (invoice_id), (send_at).
- checkin_tasks (uuid id, org_id, invoice_id, send_at, token_hash unique [SHA-256 du HMAC, TTL 24h], status ENUM scheduled/sent/answered/expired, answer 'paid'|'still_pending'). Pas encore branché — flow check-in arrivera dans un commit séparé (cf. backend.md §13.3).
Schema rules : status enums + answer typés.
Models RelanceTask + CheckinTask avec belongsTo Invoice / PlanStep.
Service relance_scheduler.ts :
- scheduleRelancesForInvoice(invoice) : pour chaque step du plan, calcule sendAt = dueDate + offsetDays. Si sendAt < now (facture importée en retard), on programme à `now + 1min` plutôt que skip — l'utilisateur "rattrape" une dette de relance, l'envoi immédiat est cohérent. Crée la RelanceTask + enqueue BullMQ avec delay, retry 5x exponential, jobId = `relance:<taskId>` pour idempotency. Cancelle les tasks scheduled existantes avant de re-programmer (gestion changement de plan).
- cancelFutureRelances(invoiceId, trx) : appelé par mark-paid pour stopper la chaîne.
Service queue.ts :
- getQueue(name) singleton lazy par queue
- registerWorker(name, handler) avec concurrency 5, log failed/completed
- shutdownQueue() pour le terminating hook Adonis
start/queue.ts (preload) : registerWorker('relances', sendRelanceJob) seulement quand `app.getEnvironment() === 'web'` (pas en tests/REPL — pas de connexion Redis pendant Japa).
Job send_relance_job.ts :
- Idempotent : si task.status !== 'scheduled', no-op
- Hook critique : si invoice paid/cancelled entre-temps, task.status = cancelled
- Mise en demeure (step.requiresManualValidation) : on n'envoie PAS, on log un activity_event 'warning_drafted' (cf. CLAUDE.md → Principes : validation manuelle obligatoire)
- Sinon : sendRelanceEmail + task.status=sent + invoice.rubisEarned+1 + organizations.rubis_count+1 + activity_event 'relance_sent'. Si invoice.status='pending', passe en 'in_relance' (sortie de l'état silencieux).
Service mail_dispatcher.ts : sendRelanceEmail interpole step.subject/body via mini moteur Mustache-like (renderTemplate, services/template.ts) avec {{client.name}}/{{numero}}/{{amount}}/{{dueDate}}/{{signature}}, puis @adonisjs/mail.use(MAIL_DRIVER) → Mailpit en dev, Resend en prod. Texte brut V1.
Triggers branchés :
- InvoicesController.store : si planId, scheduleRelancesForInvoice après création
- ImportBatchesController.validateDraft : pareil
- InvoicesController.markPaid : cancelFutureRelances dans la même tx que le paiement
#jobs/* ajouté aux imports package.json. Adonisrc preload start/queue.ts.
Bruno : doc 05-Invoices/04 Create maj avec instructions pour tester l'envoi immédiat (dueDate dans le passé → relance à now+1min → email visible dans Mailpit http://localhost:8025).
Rubis API — Collection Bruno
Collection Bruno qui répertorie toutes les routes de l'API et permet de les tester en suivant un parcours réaliste (signup → onboarding → création client → facture → encaissement).
Installation
- Installe Bruno : https://www.usebruno.com/downloads
- Dans Bruno, Open Collection → sélectionne le dossier
bruno/à la racine du repo. - Sélectionne l'environnement local dans le sélecteur en haut à droite.
Démarrer l'API
pnpm dev:up # Postgres, Redis, MinIO, Mailpit
pnpm dev:api # API sur http://localhost:3333
Si la DB est neuve : pnpm -F api exec node ace migration:run
Variables d'environnement
Définies dans environments/local.bru. Les valeurs vides (token, userId, etc.) sont remplies automatiquement par les script:post-response :
| Variable | Source | Utilisée par |
|---|---|---|
baseUrl |
en dur (http://localhost:3333) |
toutes |
email / password / fullName |
en dur (login fixture) | Signup, Login |
token |
rempli après Signup/Login | toutes les routes auth |
userId |
rempli après Signup/Login | (info) |
organizationId |
rempli après Signup/Login | (info, debug) |
clientId |
rempli après Create client | détail/update client, création facture |
planSlug |
en dur (standard-30j) |
détail/update plan |
invoiceId |
rempli après Create invoice OU Validate draft | détail/mark-paid |
batchId / draftId |
remplis après Upload (mock) | Get batch / Validate / Skip / Cancel |
Parcours recommandé (premier run)
- Auth → 01 Signup (récupère un token + crée l'org + provisionne les 4 plans)
- Account → 01 Get profile (vérifie l'auth)
- Organizations → 02 Update my org (onboarding step 2)
- Clients → 04 Create (crée un client, capture
clientId) - Plans → 01 List (vérifie les 4 plans pré-fournis)
- Invoices → 04 Create (crée une facture liée au client)
- Invoices → 05 Get detail (vérifie la timeline)
- Invoices → 06 Mark paid (encaisse + bonus rubis)
- Organizations → 01 Get my org (vérifie
rubisCountincrémenté) - Clients → 02 List with stats (vérifie les compteurs)
- Imports → 01 Upload (mock) (capture
batchId+draftId) - Imports → 02 Get batch (review des drafts pending)
- Imports → 03 Validate draft (transforme le draft en facture)
Flow refresh (silent re-login)
Une fois Signup ou Login passé, Bruno a stocké le cookie rubis_refresh dans sa cookie jar. Tu peux vider token dans l'env actif (pour simuler une expiration), puis appeler Auth → 04 Refresh : tu reçois un nouveau access token sans devoir re-saisir email/password. C'est ce que le SPA fera silencieusement quand une requête revient en 401.
Reset entre runs
L'email alice@bruno.test est unique en DB → 2e signup retourne 422 email_taken.
Pour repartir propre :
docker exec rubis-postgres psql -U rubis -d rubis_dev -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"
pnpm -F api exec node ace migration:run
Ou change email dans l'environnement local pour forcer un nouveau signup à chaque run.