iag-dev-evaluator/README.md

# IA Gen Maturity Evaluator

Application web de maturité IA/GenAI pour évaluer les candidats lors d'entretiens techniques. Développée par Peaksys pour Peaksys.

## Stack technique

- **Next.js 15** (App Router), **React 19**, **TypeScript**, **TailwindCSS**
- **NextAuth v5** — authentification JWT, bcrypt, rôles `admin` / `evaluator`
- **Prisma** + **SQLite** (dev) — basculer sur Postgres/Supabase en production
- **Recharts** — radar chart des scores
- **jsPDF** — export PDF
- **Vitest** — tests unitaires | **Playwright** — tests E2E

## Prérequis

- Node.js ≥ 20
- pnpm (`npm install -g pnpm`)

## Installation & démarrage local

```bash
pnpm install
cp .env.example .env       # puis remplir AUTH_SECRET
pnpm db:generate
pnpm db:push               # ou pnpm db:migrate pour une DB vide
pnpm db:seed
pnpm dev
```

Ouvrir [http://localhost:3000](http://localhost:3000).

**Note :** Si la DB existe déjà (créée avec `db push`), pour basculer sur les migrations :

```bash
pnpm prisma migrate resolve --applied 20250220000000_init
```

## Variables d'environnement

| Variable | Obligatoire | Description |
|----------|-------------|-------------|
| `DATABASE_URL` | Oui | `file:./dev.db` en local, URL Postgres en prod |
| `AUTH_SECRET` | Oui | Secret JWT NextAuth (générer avec `openssl rand -base64 32`) |
| `NEXTAUTH_URL` | Prod | URL publique de l'app (ex. `https://eval.peaksys.io`) |

## Docker

Trois configurations disponibles :

### Développement (hot-reload)

```bash
docker compose -f docker-compose.dev.yml up
```

### Production — SQLite (simple, port 3044)

```bash
AUTH_SECRET=$(openssl rand -base64 32) \
DB_VOLUME_PATH=/chemin/vers/data \
docker compose up -d
```

### Production — Postgres

```bash
docker compose -f docker-compose.postgres.yml up -d
```

> Le `Dockerfile` inclut le client Prisma compilé pour Linux (`debian-openssl-3.0.x`).
> La base est migrée automatiquement au démarrage via `docker-start.sh`.

## Architecture

### Flux de données (server-first)

1. **Server Page** → `src/lib/server-data.ts` (appelle `auth()` + Prisma)
2. La page passe les données sérialisées aux **Client Components** (`src/components/`)
3. Les composants clients appellent les **Server Actions** (`src/actions/`) pour les mutations
4. Les server actions appellent `revalidatePath()` pour invalider le cache

### Authentification & rôles

- `src/auth.ts` — NextAuth v5, Credentials provider (email + bcrypt), stratégie JWT
- Deux rôles : `evaluator` (défaut) et `admin`
- Inscription via `/auth/signup` (`POST /api/auth/signup`)
- `src/middleware.ts` — protège toutes les routes ; redirige les non-admins hors des routes admin

### Contrôle d'accès aux évaluations

`src/lib/evaluation-access.ts` — `canAccessEvaluation()` est la source de vérité unique :

- Utilisateur **admin** → accès total
- Utilisateur **evaluator** propriétaire → accès total
- Évaluation **partagée** (`EvaluationShare`) → accès lecture/écriture
- Évaluation **publique** (`isPublic = true`) → accès lecture seule

### Important : staleness du JWT

`session.user.name` est gelé au moment du login. Pour afficher le nom à jour, interroger Prisma via `session.user.id` — ne pas se fier à la session.

## Pages & fonctionnalités

| Route | Accès | Description |
|-------|-------|-------------|
| `/` | Tous | Redirect vers `/dashboard` |
| `/dashboard` | Auth | Liste des évaluations, groupement par équipe, vue carte ou tableau |
| `/evaluations/new` | Auth | Créer une évaluation (candidat, rôle, équipe, template) |
| `/evaluations/[id]` | Voir accès | Guide d'entretien, scores 1–5, justifications, radar chart, export |
| `/admin` | Admin | Gestion des templates et des utilisateurs |
| `/settings` | Auth | Modifier son nom et son mot de passe |
| `/auth/login` | Public | Connexion |
| `/auth/signup` | Public | Inscription |

### Fonctionnalités clés

- **Scoring** : note 1–5, justification, exemples observés, niveau de confiance
- **Questions de sondage** : affichées automatiquement quand score ≤ 2
- **Assistant IA (stub)** : suggestions de questions de relance (`/api/ai/suggest-followups`)
- **Export** : CSV (`/api/export/csv?id=`) et PDF (`/api/export/pdf?id=`)
- **Radar chart** : visualisation des scores par dimension
- **Partage** : partager une évaluation avec d'autres utilisateurs (`EvaluationShare`)
- **Visibilité publique** : `isPublic` rend une évaluation lisible sans authentification
- **Audit log** : toute modification post-soumission est tracée
- **Warning** : alerte si tous les scores = 5 sans justification

## Commandes utiles

```bash
pnpm dev          # Serveur de développement
pnpm build        # Build production
pnpm lint         # ESLint
pnpm typecheck    # tsc --noEmit

pnpm db:generate  # Régénérer le client Prisma après modif du schéma
pnpm db:push      # Synchroniser le schéma (dev, sans fichiers de migration)
pnpm db:migrate   # Appliquer les migrations (production)
pnpm db:seed      # Injecter les données de seed
pnpm db:studio    # Ouvrir Prisma Studio
```

## Tests

```bash
# Tests unitaires (Vitest)
pnpm test

# Tests E2E (Playwright) — nécessite le serveur dev lancé
pnpm exec playwright install  # une seule fois
pnpm test:e2e
```

## Déploiement (production)

1. Configurer `DATABASE_URL` vers Postgres (Supabase, Neon, etc.)
2. Générer `AUTH_SECRET` : `openssl rand -base64 32`
3. Appliquer les migrations : `pnpm db:migrate`
4. Seeder si besoin : `pnpm db:seed`
5. Build : `pnpm build && pnpm start`
6. Ou déployer sur Vercel (variables d'env à configurer, Vercel Postgres ou DB externe)

## Structure des fichiers

```
src/
├── app/
│   ├── api/               # Routes API (export CSV/PDF, auth, AI stub)
│   ├── auth/              # Pages login / signup
│   ├── dashboard/         # Dashboard principal
│   ├── evaluations/       # Pages évaluation (new, [id])
│   ├── admin/             # Administration (templates, utilisateurs)
│   ├── settings/          # Paramètres utilisateur
│   └── page.tsx           # Redirect vers /dashboard
├── actions/               # Server Actions (mutations)
│   ├── evaluations.ts
│   ├── share.ts
│   ├── admin.ts
│   └── password.ts
├── components/            # Composants UI (client + server)
└── lib/
    ├── server-data.ts     # Toutes les requêtes DB (server-side)
    ├── evaluation-access.ts
    ├── export-utils.ts
    └── ai-stub.ts
prisma/
├── schema.prisma
└── seed.ts
tests/e2e/                 # Tests Playwright
```

## Données de seed

- **Utilisateur admin** : `admin@peaksys.local` / `admin123`
- **3 évaluations** de démonstration (Alice Chen, Bob Martin, Carol White) avec équipes
- **2 templates** : Full 15 dimensions, Short 8 dimensions

## Critères d'acceptation

- [x] Auth bcrypt multi-utilisateurs, rôles admin/evaluator
- [x] Dashboard : liste et cartes d'évaluations, groupement par équipe
- [x] Créer/modifier une évaluation : candidat, rôle, équipe, date, template
- [x] Templates : Full 15 dim, Short 8 dim
- [x] Guide d'entretien : définition, rubrique 1→5, signaux, questions par dimension
- [x] Scoring : note 1–5, justification, exemples, confiance
- [x] Questions de sondage quand score ≤ 2
- [x] Assistant IA (stub) : suggestions de relance
- [x] Radar chart + findings/recommandations auto-générés
- [x] Export PDF et CSV
- [x] Administration : templates et gestion des utilisateurs
- [x] Partage d'évaluation avec d'autres utilisateurs
- [x] Visibilité publique (`isPublic`)
- [x] Alerte si tous les scores = 5 sans commentaires
- [x] Modification post-soumission avec audit log
- [x] Page paramètres : changer nom et mot de passe
- [x] Responsive mobile (Tailwind)