# Multi-role Support Guide

Ce guide explique comment le module multi-rôles permet d'associer plusieurs responsabilités à un utilisateur KoproGo.

---

## Objectifs

- Autoriser plusieurs rôles actifs pour un même utilisateur (ex. syndic & comptable).
- Permettre de choisir le rôle actif et de l'inclure dans le JWT.
- Documenter l'API, la base de données et les parcours BDD associées à l'issue #28.

---

## Modèle de données

```
users
└── user_roles (jonction)
    • user_id (FK users.id)
    • role (ENUM: superadmin, syndic, accountant, owner)
    • organization_id (FK organizations.id, nullable)
    • is_primary (bool)
    • created_at / updated_at
```

### Invariants

- Au moins une entrée `user_roles` par utilisateur (migration de rétrocompatibilité).
- Un seul rôle `is_primary = true` par utilisateur (`idx_user_roles_primary_per_org`).
- Les tokens JWT portent `role`, `organization_id`, `role_id`.

---

## API

| Endpoint | Méthode | Description |
|----------|---------|-------------|
| `/auth/login` | POST | Retourne `roles[]`, `active_role` et tokens. |
| `/auth/switch-role` | POST | Sélectionne un rôle secondaire (JWT mis à jour). |
| `/auth/me` | GET | Renvoie l'utilisateur courant avec la liste des rôles. |

### Exemple de réponse `login`

```jsonc
{
  "token": "…",
  "refresh_token": "…",
  "user": {
    "id": "…",
    "email": "alice@example.com",
    "role": "syndic",
    "organization_id": "…",
    "roles": [
      { "id": "…", "role": "syndic", "organization_id": "…", "is_primary": true },
      { "id": "…", "role": "accountant", "organization_id": "…", "is_primary": false }
    ],
    "active_role": { "id": "…", "role": "syndic", "organization_id": "…", "is_primary": true }
  }
}
```

---

## Tests et couverture

- **Unitaires** : validations `UserRoleAssignment`, conversions DTO, `AuthUseCases`.
- **Intégration** : `PostgresUserRoleRepository` (création, switch primary).
- **E2E Backend** : `tests/e2e_auth.rs` (ajout de second rôle, switch via use-case).
- **BDD** : `auth.feature` (scénario multi-rôles) aligne l'issue #28.
- **Frontend** : store `auth.ts` + composant `Navigation.svelte` (sélecteur de rôle).

---

## Flux métier type (Gherkin)

```
Given a coproperty management system
And a user with multiple roles
When I switch to the secondary role
Then my active role should be "accountant"
And the user response should list multiple roles
And the JWT claims should use role "accountant"
And the JWT claims should reference the selected role
```

---

## Migrations et seeds

- Migration `20250130000000_add_user_roles.sql` :
  - crée la table `user_roles`
  - backfill les utilisateurs existants avec `is_primary = true`
- `DatabaseSeeder` :
  - garantit l'assignation du rôle superadmin
  - les utilisateurs de démonstration reçoivent un enregistrement `user_roles`

---

## Frontend

- `authStore.switchRole` appelle `/auth/switch-role` avec JWT.
- `Navigation.svelte` rend le sélecteur (badge de rôle + redirection).
- Les informations `roles` / `activeRole` sont persistées offline.

---

## Migration

1. Déployer la migration SQL.
2. Redémarrer l'API (reconstruit AppState avec `PostgresUserRoleRepository`).
3. Vidanger les sessions (les nouveaux tokens incluent `role_id`).
4. Vérifier la nouvelle BDD BDD (`make test` inclut le scénario multi-rôles).

---

🎯 Alignement Issue #28

- ✅ Table `user_roles`
- ✅ `AuthenticatedUser` expose `role_id`
- ✅ Use case `switch_active_role`
- ✅ UI rôle-switcher
- ✅ Tests BDD + e2e démontrant le parcours métier