ordinarthur/rubis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
rubis/CLAUDE.md
ordinarthur b0e6f83655
All checks were successful
Build & Deploy Landing / build-and-deploy (push) Successful in 1m19s
Details
Build & Deploy API / build-and-deploy (push) Successful in 1m44s
Details
Build & Deploy Web / build-and-deploy (push) Successful in 41s
Details
feat(billing): essai 14 j Pro avec CB à l'inscription (Stripe trial_period_days) 
Implémente le chantier #6 de docs/tech/landing-optimisations.md. Le
funnel signup propose maintenant un essai 14 j Pro avec carte demandée
mais non prélevée — prélèvement automatique à J+14 avec rappel à J+11
(webhook customer.subscription.trial_will_end de Stripe).

Couverture tests : 60 tests unitaires sur la couche billing
  - billing.spec.ts          (25) — quota Free, bypass trial, inTrial state
  - stripe_billing.spec.ts   (24) — handlers webhook, idempotence, dispatcher
  - trial_recap_job.spec.ts  (11) — stats aggregation, formatRubisToHoursFr
+ 3 nouveaux tests vitest côté SPA (useTrialDaysRemaining,
useIsAtFreeLimit bypass trial).

Backend :
  - Migration 1779000000000_add_trial_ends_at_to_organizations
  - PLAN_CAPS bypass quand status=trialing AND trial_ends_at futur
  - getOrgSubscriptionState expose inTrial + trialEndsAt
  - Refactor handlers webhook en service stripe_billing.ts (pures,
    testables) — extraction depuis le controller. dispatchWebhookEvent
    routeur typé également extrait pour les tests.
  - createTrialCheckoutSession avec subscription_data.trial_period_days=14,
    garde-fou TrialAlreadyConsumedError contre re-trial.
  - handleTrialWillEnd → enqueue job recap (BullMQ jobId déterministe
    basé sur subscriptionId, idempotent contre re-delivery Stripe).
  - Endpoint POST /api/v1/billing/start-trial.
  - Email template trial_recap (React Email, branding Rubis figé) avec
    stats: factures importées, relances envoyées, € récupérés, rubis +
    heures libérées.

Infra de test :
  - tests/helpers/stripe_mock.ts : __setStripeForTests injection +
    factories fakeSubscription / fakeCheckoutSession / fakeInvoice.
  - __setTrialRecapEnqueueForTests : permet de spy l'enqueue sans Redis.

Frontend :
  - /onboarding/billing.tsx (opt-in, pas encore forcé dans le flow) :
    bouton primaire essai 14j + fallback "Free 2 factures".
  - PlanLimitBanner : nouveau état "Essai Pro · X jours restants" qui
    prime sur les autres bandeaux. Discret rubis-glow, non blocant.
  - useStartTrial hook + useTrialDaysRemaining (arrondi sup).
  - SubscriptionState typé avec inTrial + trialEndsAt.

Landing :
  - Sous-texte CTA réactivé : « CB demandée, non prélevée avant J+14 »
    (Hero + FinalCTA), maintenant promesse véridique.

Notes ouvertes (à décider ultérieurement) :
  - Tunnel /onboarding/billing FORCÉ entre signup et /onboarding/compte :
    guard reste à activer (risque cassage du signup actuel sinon).
    Pour l'instant l'écran est accessible mais opt-in.
  - Cron de redondance trial-recap : pas encore implémenté (le
    jobId déterministe BullMQ couvre déjà la double-livraison Stripe).
    À ajouter si on observe des trial sans recap en prod.
  - Tests E2E avec Stripe test mode à faire avant le go-live (cartes
    3DS 4000 0027 6000 3184, declined 4000 0000 0000 0341).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-18 12:04:41 +02:00

145 lines
8.8 KiB
Markdown
Raw Blame History

# Rubis Sur l'Ongle
> **SaaS de relance de factures impayées pour TPE-PME françaises.** Drag-and-drop, OCR, plans de relance automatiques.
Contexte top-level — court, dense, scannable. Détails dans `/docs/`.
## État actuel (mai 2026)
Produit shippé, landing live sur `rubis.pro`, **0 client payant**. Focus 30 jours : acquisition (réseau direct + experts-comptables + SEO), **pas de nouvelle feature avant 1er client demandeur**. Audit landing en cours, cf. `/docs/tech/landing-optimisations.md`.
## Promesse
*Vos factures se relancent toutes seules pendant que vous travaillez.* On vend du temps libéré (5h/semaine récupérées), pas de la trésorerie.
**Cible** : TPE-PME 5-50 salariés, 10-200 factures/mois, sans crédit manager dédié. Le décideur teste lui-même (pas de cycle de vente long).
## Principes produit
1. **3 clics max** pour lancer une relance sur une facture neuve.
2. **Mobile et desktop** — la photo de facture depuis le téléphone est un usage clé.
3. **La relance est l'âme du produit.** L'édition native de factures (V1.1, ADR-025) est une *extension douce*, pas un pivot. On reste sous-positionnés vs Pennylane/Sellsy, jamais frontaux.
4. **Respect du client final** — le ton monte avec le retard, jamais avant.
5. **Le rubis est une vraie devise** — tangible, défendable, métrique-héros (pas le DSO).
## Pas de (produit)
Pas de CRM, pas de comptabilité, pas de gestion RH, pas de marketplace marketing, pas de scoring crédit, pas de chasse multi-pays. Si une feature ressemble à ça, c'est OUT.
## Identité de marque
| | |
|---|---|
| **Logo** | Direction A — gem facetté géométrique. Le ◆ est un symbole produit. |
| **Primaire** | `#9F1239` rubis profond légèrement violacé (*anti-Coca-Cola*) |
| **Secondaires** | `#771328` deep · `#C9415C` light · `#FBE4EA` glow |
| **Neutres** | Crème `#FAF7F2` · encre chaude `#1A1410`. **Jamais** de blanc/noir purs. |
| **Typo display** | Bricolage Grotesque 500-800 (`@fontsource-variable/bricolage-grotesque`) |
| **Typo body** | Inter 400-700 (`@fontsource-variable/inter`) |
| **Icônes** | Lucide regular |
| **Pas de** | or, bleu, vert, violet, emojis joaillerie 💎💰, mot « recouvrement » en com publique |
Détails : `/docs/marque.md` · visuel : `/docs/brand-identity.html`.
## Voix
Direct, concret, chaleureux, précis, empathique. *Comme un bon associé, pas comme une DAF.*
- ✓ "Vos factures relancées toutes seules."
- ✗ "Optimisez votre processus de recouvrement amiable."
## Glossaire
- **Rubis** : unité de gamification. **1 rubis = 10 minutes libérées** = 1 relance évitée à la main.
- **Plan de relance** : cadence d'emails automatisés (J+3, J+10, J+20...). 4 plans par défaut : *Standard B2B*, *Rapide*, *Patient*, *Ferme*.
- **Confirmation** *(ex « check-in »)* : email envoyé **à l'utilisateur** pour confirmer paiement avant la relance suivante. Remplace l'intégration banking en V1.
- **Mise en demeure** : étape ferme, **toujours sous validation manuelle** via modale. Jamais auto.
- **Facture native** : facture créée dans Rubis via `/factures/nouvelle` (vs OCR/saisie). PDF généré côté serveur via `@react-pdf/renderer`. Snapshots client + émetteur immuables figés à l'émission. Drapeau `invoices.is_native = true`. Numérotation **strict séquentielle par org** via verrou row-level (conforme art. 242 nonies A du CGI).
- **Factur-X** : PDF/A-3 + XML CII embarqué, format obligatoire B2B FR au 1er sept 2027. **Roadmap V1.5**.
- **DSO** : Days Sales Outstanding. Métrique secondaire dans l'app, jamais dans la com publique.
- **LME** : loi 2008, plafonne les délais de paiement à 60j (ou 45j fin de mois). Sanctions DGCCRF jusqu'à 2 M€.
## Périmètre V1
**IN** — Auth email/password + Google/Microsoft SSO · Onboarding 3 étapes · Upload OCR (PDF/PNG/JPG) + saisie manuelle · **Édition native factures** (V1.1, cf. ADR-025) · Bibliothèque de plans + éditeur · Confirmation par email · Dashboard rubis + KPIs · Liste filtrable · Timeline relances · Stripe billing + période de grâce · Mode démo · Web responsive · Blog `rubis.pro/blog` (SSR Astro, contenu DB, IA hebdo + review humaine) · Changelog `rubis.pro/changelog` (SSG, content collections, toast SPA via `apps/web/src/version.ts`).
**OUT V2+** — SMS (plan le plus cher) · Multi-utilisateurs (plans payants) · Intégration banking (archi V1 doit l'anticiper) · Multi-langues/devises (FR/EUR only en V1) · Intégrations ERP/compta (Sage, Pennylane, Quickbooks).
## Pricing
| Plan | Prix | Limite |
|---|---|---|
| **Free** | 0 € | 2 factures actives, 1 utilisateur (cf. ADR-023, mai 2026) |
| **Pro** | 19 €/mois | Factures illimitées, OCR illimité, 1 utilisateur |
| **Business** | 49 €/mois | + multi-users + branding email + SMS (V2) |
Argument : *"moins cher qu'une heure de votre temps mensuel"*. Funnel signup : essai 14 j Pro avec **CB à l'inscription** (Stripe `trial_period_days`), prélèvement auto à J+14 avec rappel à J+12. Fallback Free pour les sans-CB. Cf. `/docs/tech/stripe-trial-with-card.md`.
## Stack technique
| Couche | Choix | Source |
|---|---|---|
| API | **AdonisJS v7** (Lucid, auth Bearer, jobs BullMQ, mail) | ADR-014 |
| SaaS `app.rubis.pro` | **React 19 + Vite + TanStack Router/Query** | ADR-014 |
| Landing+blog `rubis.pro` | **Astro 6 SSR** | — |
| Design system | **`@rubis/ui`** — Tailwind v4 + composants TSX | — |
| DB | **PostgreSQL** (LXC Proxmox existant) | ADR-014, ADR-016 |
| Storage | **MinIO** (LXC Proxmox existant) | ADR-018 |
| Hosting | **Proxmox + K3s + Traefik** | ADR-014 |
| PDF natif | **`@react-pdf/renderer`** côté API, templates `apps/api/app/pdf-templates/` | ADR-025 |
| OCR / Email | à benchmarker | ADR-020 / ADR-021 |
**Repo** : monorepo Turborepo (`apps/api`, `apps/web`, `apps/landing`, `packages/shared` Zod, `packages/ui`). API REST Bearer-auth (ADR-017). Détails : `/docs/tech/architecture.md`.
**Convention cross-cutting — UUID partout.** PK et FK applicatives en UUID v4 (`gen_random_uuid()`). **Jamais d'`increments`/`serial`**, même pour les tables internes. Protège de l'énumération, simplifie la fédération multi-tenant, évite les fuites par incrément.
## Comment bosser avec moi (Arthur)
1. **Acquisition avant produit.** Quand je propose une feature, vérifier qu'un user réel l'a demandée. Si c'est une hypothèse, me ramener au plan acquisition.
2. **Lire l'ADR avant de toucher un sous-système** (`/docs/decisions.md`). Si décision absente, écrire un nouvel ADR.
3. **Pas de personal brand sur les réseaux.** LinkedIn propre + GitHub OK, pas de mise en scène. Pour le copy public, ton direct sans posture.
4. **Réutiliser l'infra existante** (PG, MinIO, K3s, Traefik) plutôt que provisionner du neuf.
5. **Réponses en français**, prose dense, peu de bullets sauf si liste vraiment nécessaire. Pushback bienvenu, pas de flatterie.
## Documents associés
| Fichier | Rôle |
|---|---|
| `/docs/produit.md` | Spec produit (features, IN/OUT V1, flow native) |
| `/docs/flow.md` | Cycle de vie facture, statuts, transitions, edge cases |
| `/docs/marque.md` | Référence marque écrite |
| `/docs/decisions.md` | Log ADR (rationale par décision) |
| `/docs/tech/architecture.md` | Architecture technique (composants, topologie) |
| `/docs/tech/frontend.md` | Guide implémentation frontend |
| `/docs/tech/backend.md` | Guide backend (jobs, mail, conventions Adonis) |
| `/docs/tech/landing-optimisations.md` | Audit landing + plan d'exécution (mai 2026) |
| `/docs/marketing/playbook.md` | Playbook acquisition : ICP, Dream 100, outreach |
| `/docs/munitions-marketing.md` | Stats marché, concurrents, copy, positionnement |
| `/docs/tech/stripe-trial-with-card.md` | Funnel signup essai 14j + CB à l'inscription |
| `/.claude/deploy-memory.md` | Procédure de déploiement |
| `/.claude/skills/push/SKILL.md` | Skill `/push` — bump version + changelog + commit |
## Déploiement
Domaines : **`rubis.pro`** (landing+blog) · **`app.rubis.pro`** (SaaS). Compat 301 depuis `rubis.arthurbarre.fr` / `app.rubis.arthurbarre.fr`. Images : `git.arthurbarre.fr/ordinarthur/rubis-{landing,api,web}:latest`. Détails : `.claude/deploy-memory.md`.
## Email infrastructure
| Flux | Provider | Adresse | DNS |
|---|---|---|---|
| **Sortant** (relances, auth) | Resend | `relances@rubis.pro` | `send.rubis.pro` MX+SPF, `resend._domainkey` DKIM, `_dmarc` |
| **Entrant** (humain) | OVH MX Plan | `contact@rubis.pro`, `dev@rubis.pro` | MX `@` → `mx*.mail.ovh.net.` |
Détails : `/docs/tech/backend.md` §12.5.
## Questions ouvertes
- **Pricing Free** à réarbitrer (cf. landing-optimisations.md §2)
- **Provider OCR** à benchmarker (Mindee / Document AI / Textract / Tesseract) — ADR-020
- **Conversion 1 rubis = 10 min** à confirmer en user testing après premiers clients
- **Analytics RGPD** (Plausible self-hosted vs Umami) — futur ADR
---
*Dernière mise à jour : 2026-05-17 · Maintenu par Arthur + Claude.*
Reference in New Issue View Git Blame Copy Permalink