# Gestion des utilisateurs — référence technique

## 1. Deux emplacements possibles pour un compte

| Emplacement | Fichier / système | Quand c’est utilisé |
|-------------|-------------------|---------------------|
| **Base SQLAlchemy** | Table `users` dans `data/translate.db` (SQLite par défaut) ou PostgreSQL | Inscription et authentification lorsque le module base est chargé (`services/auth_service.py`). |
| **Fichier JSON** | `data/users.json` | Ancien mode « fichier seul », ou compte créé avant migration, ou utilisateur présent uniquement ici (legacy). |

L’authentification (`get_user_by_email`, etc.) lit **d’abord la base**, puis **repli** sur `users.json` si l’utilisateur n’y est pas (`services/auth_service.py`).

## 2. Bug corrigé : liste admin vide alors qu’un compte existe

**Cause** : `GET /api/v1/admin/users` ne lisait **que** la table SQL `users`. Un compte présent **uniquement** dans `data/users.json` n’apparaissait **jamais**.

**Correction** : la route agrège :

1. Tous les utilisateurs de la base (ordre `created_at` décroissant).
2. Les entrées de `users.json` dont l’`id` **et** l’e-mail (normalisé) ne sont **pas** déjà couverts par la base (évite les doublons).

Chaque ligne comporte un champ **`storage`** : `database` ou `json_file`.

## 3. Endpoints admin concernés

| Méthode | Chemin | Rôle |
|---------|--------|------|
| `GET` | `/api/v1/admin/users` | Liste fusionnée (base + JSON-only). |
| `PATCH` | `/api/v1/admin/users/{user_id}` | Changement de plan (`plan`). |
| `POST` | `/api/v1/admin/users/{user_id}/password` | Corps JSON `{ "new_password": "..." }` (min. 8 caractères). Définit le hash en base **ou** dans `users.json` selon où vit le compte. |

Authentification : en-tête `Authorization: Bearer <token admin>` (pas le JWT utilisateur).

## 4. Réinitialisation du mot de passe (compte existant, mot de passe oublié)

1. Se connecter à l’**admin**.
2. Aller dans **Utilisateurs**.
3. Repérer la ligne (colonne **Stockage** : **Base** ou **JSON**).
4. Cliquer **MDP**, saisir le nouveau mot de passe deux fois, valider.

Il n’existe pas encore de flux « mot de passe oublié » par **e-mail** côté utilisateur final (pas d’envoi SMTP dans ce flux).

## 5. Statistiques admin (`GET /api/v1/admin/stats`)

Le total d’utilisateurs et la répartition par plan incluent désormais **base + utilisateurs JSON-only**, de façon cohérente avec la liste utilisateurs.

## 6. Fichiers de code principaux

- `routes/admin_routes.py` — `get_admin_users`, `admin_reset_user_password`, `get_admin_stats`.
- `services/auth_service.py` — `admin_set_user_password`, `load_users`, `get_user_by_email`.
- `database/repositories.py` — `UserRepository`.
- `frontend/src/app/admin/users/` — tableau, dialogue mot de passe, hooks.