geo/api/docs/DELETE_PASSAGE_PERMISSIONS.md

# API DELETE /passages/{id} - Documentation des permissions

## 📋 Endpoint
```
DELETE /api/passages/{id}
```

## 🔒 Authentification
- **Requise** : OUI (Bearer token)
- **Session** : Doit être valide

## 📊 Logique de permissions

### Règles par rôle :

| fk_role | Description | Peut supprimer ? | Conditions |
|---------|------------|------------------|------------|
| 1 | Membre | ✅ Conditionnel | Si `entites.chk_user_delete_pass = 1` |
| 2 | Admin amicale | ✅ OUI | Toujours autorisé |
| 3+ | Super admin | ✅ OUI | Toujours autorisé |

### Détail du contrôle pour les membres (fk_role = 1) :

```sql
-- L'API vérifie :
SELECT chk_user_delete_pass 
FROM entites 
WHERE id = {user.fk_entite}

-- Si chk_user_delete_pass = 0 → Erreur 403
-- Si chk_user_delete_pass = 1 → Continue
```

## 🔄 Flux de vérification

```mermaid
graph TD
    A[DELETE /passages/{id}] --> B{Utilisateur authentifié ?}
    B -->|Non| C[Erreur 401]
    B -->|Oui| D{Récupérer fk_role}
    D --> E{fk_role = 1 ?}
    E -->|Non| F[Autorisé - Admin]
    E -->|Oui| G{Vérifier chk_user_delete_pass}
    G -->|= 0| H[Erreur 403 - Non autorisé]
    G -->|= 1| F
    F --> I{Passage existe ?}
    I -->|Non| J[Erreur 404]
    I -->|Oui| K{Passage appartient à l'entité ?}
    K -->|Non| L[Erreur 404]
    K -->|Oui| M[Soft delete : chk_active = 0]
    M --> N[Succès 200]
```

## 📝 Réponses

### ✅ Succès (200)
```json
{
    "status": "success",
    "message": "Passage supprimé avec succès"
}
```

### ❌ Erreur 401 - Non authentifié
```json
{
    "status": "error",
    "message": "Vous devez être connecté pour effectuer cette action"
}
```

### ❌ Erreur 403 - Permission refusée (membre sans autorisation)
```json
{
    "status": "error",
    "message": "Vous n'avez pas l'autorisation de supprimer des passages"
}
```

### ❌ Erreur 404 - Passage non trouvé
```json
{
    "status": "error",
    "message": "Passage non trouvé"
}
```

## 📊 Logging

L'API enregistre :

### En cas de tentative non autorisée :
```php
LogService::log('Tentative de suppression de passage non autorisée', [
    'level' => 'warning',
    'userId' => $userId,
    'userRole' => $userRole,
    'entiteId' => $entiteId,
    'passageId' => $passageId,
    'chk_user_delete_pass' => 0
]);
```

### En cas de succès :
```php
LogService::log('Suppression d\'un passage', [
    'level' => 'info',
    'userId' => $userId,
    'passageId' => $passageId
]);
```

## 🎯 Exemple d'utilisation

### Requête
```bash
curl -X DELETE https://api.geosector.fr/api/passages/19500576 \
  -H "Authorization: Bearer {session_token}" \
  -H "Content-Type: application/json"
```

### Scénarios

#### Scénario 1 : Membre avec permission ✅
- Utilisateur : fk_role = 1
- Entité : chk_user_delete_pass = 1
- **Résultat** : Suppression autorisée

#### Scénario 2 : Membre sans permission ❌
- Utilisateur : fk_role = 1
- Entité : chk_user_delete_pass = 0
- **Résultat** : Erreur 403

#### Scénario 3 : Admin amicale ✅
- Utilisateur : fk_role = 2
- **Résultat** : Suppression autorisée (pas de vérification chk_user_delete_pass)

## ⚠️ Notes importantes

1. **Soft delete** : Le passage n'est pas supprimé physiquement, seulement `chk_active = 0`
2. **Traçabilité** : `updated_at` et `fk_user_modif` sont mis à jour
3. **Contrôle entité** : Un utilisateur ne peut supprimer que les passages de son entité
4. **Log warning** : Toute tentative non autorisée est loggée en niveau WARNING

## 🔧 Configuration côté amicale

Pour autoriser les membres à supprimer des passages :

```sql
UPDATE entites 
SET chk_user_delete_pass = 1 
WHERE id = {entite_id};
```

Cette modification ne peut être faite que par un administrateur (fk_role > 1) via l'endpoint :
```
PUT /api/entites/{id}
{
    "chk_user_delete_pass": 1
}
```

---
**Version API** : 3.1.4
**Date** : 20/08/2025