# AuditShield

## Projet
Outil d'audit infrastructure et sécurité pour clients MSP. Permet de lancer des scans réseau, vulnérabilités et pentest automatisés, avec suivi des actions et génération de rapports exportables (PDF + dashboard web) compréhensibles pour des clients non-techniques.

## Stack
- Frontend : Next.js 14 + Tailwind + shadcn/ui
- Backend : FastAPI (Python 3.11)
- Base de données : PostgreSQL
- ORM : SQLAlchemy + Alembic (migrations)
- Auth : JWT + bcrypt
- PDF : WeasyPrint
- Déploiement : Docker → Synology NAS ou VPS (rigolet.tech)

## Structure
```
frontend/
  app/
    (auth)/login/       # Page login (pas de layout dashboard)
    (dashboard)/        # Pages protégées avec sidebar
      layout.tsx        # Guard auth + layout sidebar+main
      dashboard/        # Stats globales
      clients/          # CRUD clients
      audits/           # CRUD audits
  components/
    layout/             # Sidebar, Header
    ui/                 # shadcn/ui : Button, Card, Input, Badge, Label
  lib/
    api.ts              # Client fetch typé (authApi, clientsApi, auditsApi)
    auth.ts             # Helpers JWT localStorage
    utils.ts            # cn() (tailwind-merge + clsx)
backend/
  api/                  # Routes FastAPI (auth, clients, audits)
  core/                 # config.py, database.py, security.py
  models/               # SQLAlchemy ORM (base.py + TimestampMixin)
  schemas/              # Pydantic v2 (séparés des modèles)
  scanners/             # Placeholder Phase 2 (Nmap, OpenVAS...)
  reports/              # Placeholder Phase 4 (WeasyPrint PDF)
  tests/                # pytest async avec SQLite in-memory
  alembic/              # Migrations (env.py configuré)
  main.py               # App FastAPI : CORS, rate limiting, routers
docker/
  docker-compose.yml      # Dev : postgres, redis, backend, frontend
  docker-compose.prod.yml # Prod : images registry + labels Traefik
```

## Commandes
```bash
# Frontend
cd frontend && npm install && npm run dev

# Backend (lancer depuis la racine du projet, pas depuis backend/)
pip install -r backend/requirements.txt
uvicorn backend.main:app --reload

# Docker complet
docker compose -f docker/docker-compose.yml up -d

# Migrations BDD (depuis la racine, pas depuis backend/)
alembic -c backend/alembic.ini upgrade head
# Créer une migration :
alembic -c backend/alembic.ini revision --autogenerate -m "description"

# Tests
pytest backend/tests/

# Typecheck frontend
cd frontend && npm run typecheck
```

## Modèle de données
- Client : id, nom, contact, créé_le
- Audit : id, client_id, statut, date_début, date_fin, score_global
- Cible : id, audit_id, type (IP/domaine/subnet), valeur
- Vulnérabilité : id, audit_id, criticité (critique/important/modéré/faible), titre, description, recommandation
- Action : id, vulnérabilité_id, statut (ouvert/en_cours/résolu), assigné_à, note

## Sécurité IMPORTANT
- Jamais de credentials dans le code, toujours via .env
- Les scans ne se lancent QUE sur des cibles validées par l'utilisateur
- Logs de toutes les actions de scan en BDD
- Rate limiting sur toutes les routes API

## Code style
- ES modules (import/export), jamais CommonJS
- Functional components + hooks uniquement
- TypeScript strict sur le frontend
- Type hints Python obligatoires sur le backend
- IMPORTANT : typecheck après chaque série de modifications

## Git
- Branches : main (prod) → dev → feature/xxx
- Commits : feat: / fix: / docs: / refactor: / chore:
- IMPORTANT : toujours créer une branche pour chaque tâche
- IMPORTANT : ne jamais pusher directement sur main

## Déploiement
Gitea Actions → Docker → NAS ou VPS selon le client
Voir @docker/docker-compose.yml et @.gitea/workflows/deploy.yml

## Ce que Claude doit savoir sur CE projet

### Domaine métier
- Les scans sont des opérations longues → utiliser des jobs asynchrones (Celery ou BackgroundTasks FastAPI)
- Le rapport PDF doit être compréhensible par un dirigeant non-technique
- Toujours traduire les CVE en langage clair dans les rapports
- La BDD utilise snake_case, le frontend TypeScript utilise camelCase
- Les criticités : critique (CVSS 9-10), important (7-8.9), modéré (4-6.9), faible (0-3.9)
- Un scan ne peut se lancer que sur des cibles dont `validee = True` (sécurité obligatoire)

### Conventions de code établies en Phase 1

**Backend :**
- Imports toujours en `backend.xxx` (ex: `from backend.models.user import User`), jamais en relatif — le module s'appelle `backend`
- Uvicorn se lance avec `uvicorn backend.main:app`, pas `uvicorn main:app`
- Alembic se lance depuis la racine avec `-c backend/alembic.ini`
- Les enums Python sont aussi `str` (`class Criticite(str, enum.Enum)`) pour sérialisation JSON automatique
- Pydantic v2 : utiliser `model_dump()` (pas `.dict()`), `model_config = {"from_attributes": True}` (pas `orm_mode`)
- Pattern PATCH : `payload.model_dump(exclude_unset=True)` pour ne pas écraser les champs non fournis
- `get_current_user` est une dépendance FastAPI — toujours l'injecter sur les routes protégées
- `selectinload()` pour les relations dans les endpoints "detail" (évite le N+1)
- `TimestampMixin` à hériter sur tous les nouveaux modèles
- `pool_pre_ping=True` sur l'engine SQLAlchemy pour les connexions longues durée

**Frontend :**
- Les types TypeScript sont en camelCase même si l'API renvoie du snake_case (mapping à faire côté fetch)
- `"use client"` obligatoire sur toutes les pages/composants utilisant des hooks React ou des effets
- Guard auth dans `(dashboard)/layout.tsx` via `useEffect` + `getToken()` — pas de middleware Next.js
- Le client API (`lib/api.ts`) passe toujours le token en paramètre explicite — pas de contexte global
- Les nouvelles pages du dashboard vont dans `app/(dashboard)/[section]/page.tsx`
- Les nouveaux composants UI shadcn vont dans `components/ui/`, les composants métier dans `components/`
- Les rewrites `next.config.ts` proxifient `/api/*` vers le backend — en dev, définir `NEXT_PUBLIC_API_URL=http://localhost:8000`
- JWT stocké dans localStorage (simple pour MVP, à migrer vers HttpOnly cookie plus tard)

**Infrastructure :**
- Le service `backend` dans docker-compose dépend de `postgres` avec `condition: service_healthy`
- Le build frontend Next.js utilise `output: "standalone"` → le Dockerfile copie `.next/standalone`
- Les variables d'env préfixées `NEXT_PUBLIC_` sont embarquées au build (pas au runtime)
- `docker-compose.prod.yml` attend des images pré-buildées depuis `${REGISTRY}` — pas de build local

### Pièges à éviter
- Ne pas lancer `uvicorn main:app` depuis `backend/` — toujours depuis la racine avec le module complet
- Ne pas oublier `"use client"` sur les pages avec `useEffect`, `useState`, `useRouter`
- Ne pas utiliser `.dict()` Pydantic v1 — c'est `.model_dump()` en v2
- Ne pas faire de scans sans vérifier `cible.validee == True` côté backend
- Ne pas commiter `.env` — seulement `.env.example`
- Alembic `env.py` importe les modèles depuis `backend.models` — ajouter tout nouveau modèle dans `backend/models/__init__.py`