# CLAUDE.md — leperelion.fr

Guide de développement pour ce site. **À lire en premier** à chaque session.

## Objet du site

Outil personnel **multi-utilisateur à compte partagé** : il y a **un seul compte Google et un seul
téléphone suivi — ceux du Super Admin (Guillaume.Lion)**. Les autres comptes (admin/user)
consultent (et, selon leurs droits, modifient) **les données du Super Admin**. Briques :

- **L'agenda / la prise de RDV** (Google Calendar du Super Admin)
- **La boîte mail** (Gmail du Super Admin)
- **Les documents** (Google Drive du Super Admin)
- **La localisation du téléphone** (OwnTracks → carte ; appareil du Super Admin)

**Modèle « compte partagé »** : le « propriétaire des données » = le super_admin
(`backend/src/lib/data-owner.ts` → `getDataOwnerId`). Agenda/mail/Drive utilisent
`getOwnerGoogleClient()`. La **connexion Google** (`/settings`) et la **gestion des appareils** de
localisation sont **réservées au super_admin**.

**Rôles (3 niveaux)** : `super_admin` (Guillaume.Lion — connexion Google + config + comptes +
appareils + tout), `admin` (lecture **et écriture** agenda/mail/Drive sur le compte partagé),
`user` (lecture seule). Autorisation par **capacités** dans `backend/src/lib/permissions.ts`
(`requireCapability`). Gestion des comptes = `super_admin` uniquement (`/admin/users`), avec
fonction **« Se connecter en tant que »** (impersonation). Détails :
[01_ROLES_ET_DROITS.md](01_ROLES_ET_DROITS.md).

Documentation complète : voir les fichiers numérotés `00_` à `08_` + [AVANCEMENT.md](AVANCEMENT.md).

## ⚠️ Règle d'or : ne pas perturber les autres sites

Ce serveur héberge **plusieurs sites** (`woogalf.fr`, `planifik.fr`, `glamz`, `html`).
Tout changement doit être **strictement isolé** à leperelion.fr.

- **Ports** : ce site utilise **3002** (frontend) et **4002** (backend). Ne jamais réutiliser
  3000/3001 (woogalf/planifik front) ni 4000/4001 (woogalf/planifik back).
- **Base de données** : base dédiée `leperelion`, rôle `leperelion`. **Interdiction absolue**
  de toucher aux bases `woogalf`, `planifik`, `glamz` (ni leurs tables/rôles).
- **Apache** : ajouter uniquement un vhost `leperelion.fr*.conf` dédié. Ne jamais éditer les
  vhosts des autres sites. Toujours `apache2ctl configtest` avant tout `reload`.
- **PM2** : processus nommés `leperelion-backend` / `leperelion-frontend` uniquement.
  Ne jamais `restart`/`stop`/`delete` les process des autres sites.

## Stack technique (identique aux autres sites)

| Couche      | Techno                                                        | Port  |
|-------------|---------------------------------------------------------------|-------|
| Frontend    | Next.js 16 + React 19 + Tailwind 4 (TypeScript)               | 3002  |
| Backend     | Express 5 + TypeScript + Prisma 7 (adapter-pg)                | 4002  |
| Base        | PostgreSQL 17 (base `leperelion`)                             | 5432  |
| Reverse proxy | Apache2 (mod_proxy_http, proxy_wstunnel, rewrite, ssl, headers) | 80/443 |
| Process     | PM2 (`leperelion-backend`, `leperelion-frontend`)            | —     |
| TLS         | Let's Encrypt (certbot, plugin apache)                        | —     |

Routage Apache (comme woogalf) : `/backend/*` → `http://localhost:4002/`, `/` → frontend
`http://localhost:3002/`, `/uploads` servi en statique.

## Arborescence cible

```
leperelion.fr/
├── CLAUDE.md                 ← ce fichier
├── 00_VISION_PROJET.md
├── 01_ROLES_ET_DROITS.md
├── 02_FONCTIONNALITES_MVP.md
├── 03_FONCTIONNALITES_V2_V3.md
├── 04_ARCHITECTURE_TECHNIQUE.md
├── 05_INTEGRATION_GOOGLE.md
├── 06_MODELE_DONNEES.md
├── 07_DEPLOIEMENT_INFRA.md
├── 08_QUESTIONS_RESTANTES.md
├── AVANCEMENT.md             ← état d'avancement (à mettre à jour à chaque session)
├── CHANGELOG.md              ← journal détaillé des changements
├── backend/                  ← API Express + Prisma
├── frontend/                 ← app Next.js
└── uploads/                  ← fichiers servis en statique par Apache
```

## Commandes utiles

```bash
# Backend (dev)
cd backend && npm run dev
# Backend (build + prod via PM2)
cd backend && npm run build && pm2 restart leperelion-backend

# Frontend (dev)
cd frontend && npm run dev
# Frontend (build + prod via PM2)
cd frontend && npm run build && pm2 restart leperelion-frontend

# Prisma
cd backend && npx prisma migrate dev    # crée/applique une migration (dev)
cd backend && npx prisma generate

# Apache (toujours tester avant reload)
sudo apache2ctl configtest && sudo systemctl reload apache2
```

## Conventions de travail

- **Mobile-first (impératif)** : toute l'interface est conçue d'abord pour mobile, puis enrichie
  pour les écrans plus grands. En pratique avec Tailwind : styles de base = mobile, et on ajoute
  les variantes `sm:` / `md:` / `lg:` pour le desktop (jamais l'inverse). Navigation = **sidebar
  gauche** (tiroir coulissant sur mobile via un bouton ☰, fixe à partir de `md`). Le layout
  authentifié vit dans `frontend/app/(app)/` (`layout.tsx` + `Sidebar.tsx`).
- **Rien n'est supposé** : en cas de choix structurant non tranché, le noter dans
  [08_QUESTIONS_RESTANTES.md](08_QUESTIONS_RESTANTES.md) et demander à l'utilisateur.
- **Secrets** : jamais commités. `.env` est en `.gitignore`. Les tokens OAuth Google et les
  secrets de configuration (Client Secret) sont **chiffrés au repos** en base
  (voir [05_INTEGRATION_GOOGLE.md](05_INTEGRATION_GOOGLE.md)).
- **Configuration des connexions** : la page Super Admin `/admin/config` édite les réglages
  (ex. identifiants Google OAuth) stockés en base (`AppSetting`) ; le `.env` n'est qu'un repli.
  Service : `backend/src/lib/config-store.ts`. Toute nouvelle connexion externe se branche ici.
- **Journalisation** : à chaque session de travail, mettre à jour [AVANCEMENT.md](AVANCEMENT.md)
  et ajouter une entrée datée dans [CHANGELOG.md](CHANGELOG.md).
- **Langue** : code et commentaires en français/anglais cohérents avec le projet ; doc en français.