docs: README complet + RUNBOOK + CHANGELOG + export openapi.json

2026-06-20 13:06:59 +02:00
parent af00ab36cc
commit 66436629af
4 changed files with 184 additions and 23 deletions
@@ -1,34 +1,85 @@
 # Api-DataSentinel

-API FastAPI pour Data Sentinel.
+API **FastAPI** de monitoring de la qualité des données — Data Sentinel (XEFI).
+Backend en lecture seule sur SQL Server, sécurisé par authentification JWT.

-## Installation
+## Stack

-1. Ouvrir un terminal dans le dossier du projet :
-   ```powershell
-   cd "c:\Users\antho\Desktop\Projet de fin d'année\Projet fin d_année\DataSentinel\Api-DataSentinel"
-   ```
-2. Créer et activer l'environnement virtuel (si nécessaire) :
-   ```powershell
-   python -m venv .venv
-   .\.venv\Scripts\Activate.ps1
-   ```
-3. Installer les dépendances :
-   ```powershell
-   pip install -r requirements.txt
-   ```
+- Python 3.12 · FastAPI 0.136 · uvicorn
+- SQL Server 2022 via `pyodbc` (ODBC Driver 18)
+- Auth : JWT (`python-jose`) + bcrypt (`passlib`), rate-limit (`slowapi`)

-## Lancement de l'API
-
-Utiliser la commande suivante pour démarrer le serveur :
+## Lancement en local (dev)

 ```powershell
-.\.venv\Scripts\python.exe -m uvicorn main:app --reload --port 8000
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+python -m uvicorn main:app --reload --port 8000
 ```

-> Important : si le lanceur `\.venv\Scripts\uvicorn.exe` est cassé après un déplacement de dossier, utilisez toujours `python -m uvicorn`.
+- Swagger : `http://127.0.0.1:8000/docs`  ·  Santé : `http://127.0.0.1:8000/health`

-## Vérification
+Sans variables d'environnement, l'API se connecte en authentification Windows
+(`LaptopCA\SQLEXPRESS`) — comportement de dev d'origine, inchangé.

- Swagger : `http://127.0.0.1:8000/docs`
- Santé : `http://127.0.0.1:8000/health`
+## Configuration (variables d'environnement)
+
+| Variable | Rôle | Défaut |
+|----------|------|--------|
+| `DB_SERVER` | hôte SQL Server (active l'auth SQL si défini) | — (sinon Windows local) |
+| `DB_PORT` / `DB_NAME` | port / base | `1433` / `DataSentinel` |
+| `DB_USER` / `DB_PASSWORD` | compte applicatif | — |
+| `DB_DRIVER` | pilote ODBC | `ODBC Driver 18 for SQL Server` |
+| `CORS_ORIGINS` | origines autorisées (séparées par `,`) | `localhost:5173,localhost:3000` |
+| `JWT_SECRET` | clé de signature JWT | placeholder (à définir en prod) |
+| `JWT_ALGORITHM` / `JWT_EXPIRE_MINUTES` | algo / durée du token | `HS256` / `60` |
+
+## Authentification & rôles
+
+- `POST /auth/login` (form `username`/`password`) → `{access_token, token_type, user}`. Rate-limité **5/min**.
+- `GET /auth/me` → profil courant.
+- **Tous les endpoints de données exigent** `Authorization: Bearer <token>` (401 sinon). Seul `/health` est public.
+- Rôles : `Admin`, `Superviseur`, `Consultant`. Les routes `/admin/*` exigent `Admin` (403 sinon).
+
+### Comptes de démo
+
+| Identifiant | Mot de passe | Rôle |
+|-------------|--------------|------|
+| `admin` | `Admin2026!` | Admin |
+| `superviseur` | `Super2026!` | Superviseur |
+| `consultant` | `Conseil2026!` | Consultant |
+
+## Endpoints (résumé)
+
+- **Données** (protégés) : `/categories`, `/services`, `/contacts`, `/monitorings[...]`,
+  `/dashboard[...]`, `/historique[...]`, `/evolution/*`.
+- **Admin** (`Admin`) : `GET/POST /admin/users`, `PUT/DELETE /admin/users/{id}`,
+  `POST /admin/users/{id}/reset-password`, `GET /admin/journal`.
+- **RGPD** : `GET /me/data-export` (portabilité), `DELETE /me` (droit à l'oubli + anonymisation).
+
+Spécification complète : `GET /openapi.json` (export dans `docs/openapi.json`).
+
+## Sécurité
+
+- En-têtes : `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, `Strict-Transport-Security`.
+- CORS restreint aux origines `CORS_ORIGINS`, tous verbes + credentials.
+- Requêtes SQL **paramétrées** (noms de tables/colonnes whitelistés) ; le compte applicatif
+  n'est pas `sa`. Tables d'auth : `[USER]` + `JOURNAL_AUDIT` (`sql/data_sentinel_auth.sql`).
+- Journal d'audit alimenté à chaque login + action admin.
+
+## Tests
+
+```bash
+pip install pytest httpx && pytest -q
+```
+Curseur SQL simulé (aucune vraie BDD) : santé, auth (succès/échec), protection 401, RBAC 403, 404.
+
+## Docker & CI/CD
+
+- `Dockerfile` : image Python 3.12 + `msodbcsql18`.
+- CI Gitea Actions (`.gitea/workflows/build.yml`) : **build → pytest (dans l'image) → push**
+  vers `git.nfteam.ovh/neckfire/datasentinel-api` + notification ntfy. Déclenché sur push `main`.
+- Déploiement, exploitation, sauvegarde : voir `RUNBOOK.md` et le stack d'hébergement
+  (`homelab/dev/datasentinel/`). La base tourne sur un **SQL Server partagé** (`dev-mssql`),
+  pas dédiée à l'app.