CLAUDE.md

1# Claude.md — Guide pour Claude Code (📦 projet: <anaylseur web>)
2 
3> But: permettre à Claude Code (claude.ai/code) d’intervenir efficacement sur ce repo **sans contexte superflu**, avec sorties en **diffs appliquables**, **tests**, et **docs à jour**.
4 
5---
6 
7## 1) Aperçu Projet (à compléter rapidement)
8 
9Si des infos manquent, pose-moi exactement 3 questions ciblées pour compléter :
10 
11- **Objectif produit** : …
12- **Fonctions clés** : …
13- **Public cible / plans** : …
14 
15---
16 
17## 2) Stack & Contraintes
18 
19- **Framework**: Next.js **15** (App Router) • **TypeScript strict**
20- **UI**: Tailwind CSS v4 • shadcn/ui
21- **Auth**: Better Auth (multi-organisation, rôles)
22- **Billing**: Stripe (abos/quotas)
23- **DB**: PostgreSQL + Prisma (auth/billing) • Supabase (domaine métier) _(si utilisé ici)_
24- **Email**: React Email + Resend
25- **Tests**: Vitest (unit) • Playwright (e2e)
26- **Queue**: Redis _(si workflows async)_
27- **Workflows**: n8n (webhooks HMAC, sync<5s / async≥5s)
28- **Contraintes**: responsive, idempotence, rate-limit, logs corrélés (runId), zéro secret en clair
29 
30---
31 
32## 3) Conventions d’IO pour Claude Code
33 
34Toujours produire des **fichiers** et **diffs unifiés**:
35 
36```txt
37path: <chemin/vers/fichier.ext>
38<contenu complet du fichier>
39 
40diff
41--- a/<chemin/ancien>
42+++ b/<chemin/nouveau>
43@@
44<patch>
45```
46 
47**Exigé pour chaque tâche de code** :
48 
491. Fichiers modifiés/créés ✅
502. **Tests** (unit/integration/e2e selon le scope) ✅
513. **Mise à jour docs** (README concerné / Claude.md si specs changent) ✅
52 
53Interdits : commandes shell réelles, secrets, tokens, clés `service_role`.
54 
55---
56 
57## 4) Points chauds du repo (où regarder/écrire)
58 
59- `app/` : pages & routes (App Router)
60- `src/components/` : UI (shadcn/ui dans `ui/`, customs dans `nowts/`)
61- `src/features/` : logique par feature
62- `src/lib/` : configs, services, clients API
63- `src/hooks/` : hooks React
64- `emails/` : templates React Email
65- `prisma/` : `schema.prisma`, migrations, seed
66- `__tests__/` : unit
67- `e2e/` : e2e (Playwright)
68 
69---
70 
71## 5) Intégration n8n & Supabase — _Context packs_
72 
73Quand tu touches un workflow, charge **uniquement** son pack minimal :
74 
75```
76/workflows/<slug>/
77  workflow.json            # export n8n SANITISÉ (aucun credential)
78  input.schema.json        # schéma d’entrée (Zod/JSON Schema)
79  output.schema.json       # schéma de sortie
80  README.md                # Trigger, I/O, SLA (sync/async), erreurs
81/workflows/index.yml       # mapping → routes API, SLA, webhooks
82```
83 
84Accès BD métier via **Supabase** (si présent) :
85 
86```
87/supabase/migrations/*.sql  # schéma
88/supabase/rls/*.sql         # policies RLS + tests
89/docs/erd.md                # diagramme tables
90```
91 
92**Garde-fous** : jamais de headers `Authorization`/API keys dans `workflow.json`. Remplacer par `PLACEHOLDER_*`.
93 
94---
95 
96## 6) Contrats API & Sécurité (exemple)
97 
98**Routes type** :
99 
100```
101POST /api/orgs/[orgSlug]/audits/single
102POST /api/orgs/[orgSlug]/audits/batch
103GET  /api/orgs/[orgSlug]/audits/status        # nouveauté Phase 4
104GET  /api/orgs/[orgSlug]/audits/status/[runId]
105POST /api/orgs/[orgSlug]/audits/webhook/n8n  # callbacks
106```
107 
108**Validation** : Zod côté server.
109 
110```ts
111export const SingleAuditSchema = z.object({
112  url: z.string().url(),
113  email: z.string().email(),
114  deliveryMethod: z.enum(["email", "dashboard"]),
115});
116 
117export const BatchAuditSchema = z.object({
118  csvData: z.string().min(10, 'CSV trop court'),
119  batchName: z.string().optional(),
120});
121```
122 
123**API Status (Phase 4)** : Récupération du statut des audits d'une organisation.
124 
125```ts
126// GET /api/orgs/[orgSlug]/audits/status
127// Réponse format:
128{
129  success: true,
130  audits: FormattedAudit[],  // Liste des audits formatés
131  stats: AuditStats,         // Statistiques agrégées
132  quota: QuotaInfo,          // Informations quota
133  organization: OrgInfo,     // Infos organisation
134  meta: MetaInfo            // Métadonnées
135}
136```
137 
138**HMAC pour webhooks** :
139 
140```ts
141import { createHmac, timingSafeEqual } from "crypto";
142export function isValidHMAC(payload: string, signature: string) {
143  const h = createHmac("sha256", process.env.N8N_WEBHOOK_SECRET!)
144    .update(payload)
145    .digest("hex");
146  return timingSafeEqual(Buffer.from(signature), Buffer.from(h));
147}
148```
149 
150**Idempotence** : header `Idempotency-Key` + store (clé = userId+route+hash(payload)).
151 
152---
153 
154## 7) Auth, Billing & Quotas (exigences)
155 
156- Better-Auth : helpers `getUser()`/`getRequiredUser()`, organisations, rôles.
157- Stripe : produits/plans, webhooks `invoice.paid`/`customer.subscription.updated`.
158- Quotas : middleware server (bloque si limite atteinte), compteur mensuel par org.
159- UI : afficher quota restant, erreurs “quota_exceeded”, retries guidés.
160 
161---
162 
163## 8) UX & États (shadcn/ui)
164 
165États standard pour toute feature :
166 
167- `idle` | `loading` | `success` | `error` | `quota_exceeded`
168- Async : barre de progression + ETA, suivi par `runId`, mise à jour par polling (2s) ou WebSocket/SSE.
169 
170---
171 
172## 9) Commandes Dév (pnpm)
173 
174**Core**
175 
176- `pnpm dev` • `pnpm build` • `pnpm start`
177- `pnpm ts` (type-check) • `pnpm lint` • `pnpm lint:ci`
178- `pnpm clean` • `pnpm format`
179 
180**Tests**
181 
182- `pnpm test:ci` (unit) • `pnpm test:e2e:ci` (e2e)
183 
184**DB / Auth**
185 
186- `pnpm prisma:seed` • `pnpm better-auth:migrate`
187 
188**Outils**
189 
190- `pnpm email` • `pnpm stripe-webhooks` • `pnpm knip`
191 
192_(ajoute tes scripts custom si besoin)_
193 
194---
195 
196## 10) Règles & Checklist avant code
197 
198**Toujours** vérifier avant un CCODE.\* :
199 
200- [ ] Trigger, Inputs, Outputs, Durée (sync/async) clairs
201- [ ] Schémas I/O (Zod) alignés avec `workflow.json` (n8n)
202- [ ] Auth/Idempotence/HMAC/Rate-limit traités
203- [ ] Tables & RLS Supabase (si concerné) précisées
204- [ ] Cas d’erreurs + messages UX définis
205- [ ] Variables d’env présentes dans `.env.example`
206 
207**Sécurité**
208 
209- ❌ Pas de secrets, tokens, `service_role` ou credentials dans le code/JSON
210- ❌ Pas de commandes shell exécutées
211- ✅ Placeholder uniquement + doc mise à jour
212 
213---
214 
215## 11) Tests & Observabilité (minimum)
216 
217- **Unit** : logique (schémas, quotas, mappers)
218- **Intégration** : routes API ↔ n8n (mocks), Prisma
219- **E2E** : parcours clé (single, batch, affichage rapport)
220- **Logs** : structurés (JSON), corrélation par `runId`
221- **Métriques** : temps d’exécution, taux d’échec, quotas
222 
223---
224 
225## 12) Variables d’Environnement (placeholders)
226 
227```bash
228# n8n
229N8N_BASE_URL=&lt;https://n8n.example.com&gt;
230N8N_WEBHOOK_SECRET=&lt;REQUIRED&gt;
231 
232# Supabase (si utilisé côté serveur uniquement)
233SUPABASE_URL=&lt;...&gt;
234SUPABASE_ANON_KEY=&lt;...&gt;
235SUPABASE_SERVICE_KEY=&lt;SERVER_ONLY&gt;
236 
237# Stripe
238STRIPE_SECRET_KEY=&lt;...&gt;
239STRIPE_WEBHOOK_SECRET=&lt;...&gt;
240 
241# Redis (si file d’attente)
242REDIS_URL=&lt;redis://...&gt;
243```
244 
245---
246 
247## 13) Tâches types pour Claude Code
248 
249- **Implémenter une route audit**
250  1. Créer handler Next.js + schémas Zod
251  2. Appel n8n (HMAC + idempotence)
252  3. Tests unit + intégration (mocks n8n)
253  4. Doc (README workflow + cette section si specs changent)
254 
255- **Brancher un workflow n8n async**
256  1. Endpoint POST + création `runId`
257  2. Polling/WebSocket pour suivi
258  3. Webhook callback + MAJ statut
259  4. UI états + tests e2e
260 
261_(Toujours livrer en fichiers + diff + tests + docs.)_
262 
263```
264 
265---
266 
267Si tu préfères passer par **Claude Code**, dis-le et je te fournis la **version “path: Claude.md”** (même contenu, prêt pour un coller-coller direct dans l’outil).
268```
269