Wiki/docs/11-uml-use-cases.md

# UML — Use Cases

> Vue UML des acteurs et de leurs cas d'usage. Scope B (CFA + Agence + Pivot Personne).
> Methodologie : Merise pour les donnees, UML pour les comportements et acteurs.

## 1. Acteurs

| Acteur | Role(s) Personne | Privileges principaux |
|--------|------------------|----------------------|
| **Admin** (direction, Yan, Corentin) | `admin`, `direction` | Plein controle CFA + Agence + Operations |
| **Formateur** | `formateur` (peut cumuler `developpeur`) | Vue ses attributions, saisit heures realisees, edite pages wiki |
| **Developpeur** | `developpeur` (peut cumuler `formateur`) | Vue ses interventions, saisit heures sur taches, edite docs technique |
| **Etudiant** | (hors modele Baserow) | Acces space personnel Docmost + lecture supports formation publies |
| **Client** (guest) | (hors modele Baserow) | Lecture lien partage uniquement |
| **System** | (acteur secondaire) | Calculs auto, notifications, backups |

**Note PERSONNE pivot** : un meme individu peut cumuler plusieurs roles (ex: Yan = formateur + developpeur + admin). Sa capacite annuelle est splittee.

## 2. Diagrammes use case (par domaine)

Splitte en 4 sous-diagrammes pour eviter le spaghetti : CFA, Agence, Cross/Wiki, System.

### 2.1 Use cases CFA

```mermaid
graph LR
    Admin([Admin])
    Formateur([Formateur])

    Admin --> UC01[Creer formation]
    Admin --> UC02[Decomposer blocs/modules]
    Admin --> UC03[Attribuer module formateur]
    Admin --> UC04[Reattribuer/annuler]
    Admin --> UC05[Consulter heures formation]
    Admin --> UC06[Consulter capacite formateur]
    Admin --> UC07[Rapport formation]

    Formateur --> UC03
    Formateur --> UC13[Saisir heures realisees]
    Formateur --> UC14[Consulter ses attributions]
```

### 2.2 Use cases Agence

```mermaid
graph LR
    Admin([Admin])
    Dev([Developpeur])

    Admin --> UCA01[Creer client]
    Admin --> UCA02[Creer projet]
    Admin --> UCA03[Decomposer en taches]
    Admin --> UCA04[Attribuer tache dev]
    Admin --> UCA05[Consulter avancement projet]
    Admin --> UCA06[Cloturer projet et facturer]

    Dev --> UCA07[Saisir intervention]
    Dev --> UCA08[Consulter ses taches]
    Dev --> UCA09[Marquer tache done]
```

### 2.3 Use cases Cross / Wiki

```mermaid
graph LR
    Admin([Admin])
    Formateur([Formateur])
    Dev([Developpeur])
    Etudiant([Etudiant])
    Client([Client guest])

    Admin --> UCX01[Lier projet a formation pedagogique]
    Admin --> UCX02[Consulter capacite totale Personne]
    Admin --> UCX03[Ajuster split formation/agence]
    Admin --> UCW01[Gerer wiki + droits]
    Admin --> UCW02[Inviter client par lien partage]
    Admin --> UCW03[Creer space etudiant]

    Formateur --> UCW04[Editer pages wiki]
    Dev --> UCW04

    Etudiant --> UCW05[Acces space personnel]
    Etudiant --> UCW06[Lire supports formation]
    Etudiant --> UCW07[Editer ses notes]

    Client --> UCW08[Lire page partagee]
```

### 2.4 Use cases System (auto)

```mermaid
graph LR
    System([System])

    System --> UCS01[Recalculer rollups]
    System --> UCS02[Notifier depassement capacite]
    System --> UCS03[Cloturer modules/projets auto]
    System --> UCS04[Backup quotidien]
```

## 3. Use cases CFA detailles (top prioritaires)

### UC-01 — Creer une formation

- **Acteur** : Admin
- **Pre-conditions** : Admin authentifie
- **Scenario** :
  1. Admin ouvre vue "Formations"
  2. Clique "Nouvelle formation"
  3. Renseigne nom, filiere, heures totales, dates, statut = `draft`
  4. Sauvegarde
- **Post-condition** : Formation creee, `heures_attribuees = 0`, statut `draft`

### UC-03 — Attribuer module a un formateur

- **Acteur** : Admin (ou Formateur acceptant attribution proposee)
- **Pre-conditions** : Module existe (`module_statut != annule`), Personne avec role `formateur` et statut `actif`
- **Scenario** :
  1. Admin selectionne un module dans kanban "a attribuer"
  2. Choisit Personne dans la liste (filtre par `roles contient formateur` et `heures_restantes_formation >= heures_required`)
  3. Saisit heures + dates
  4. Confirme → ATTRIBUTION creee statut `planifie`
  5. System recalcule rollups (module, bloc, formation, personne)
- **RG** : RG-01 module heures, RG-02 capacite formateur (warning), RG-PERSONNE-02 role formateur requis

### UC-13 — Saisir heures realisees (cours)

- **Acteur** : Formateur (Personne avec role `formateur`)
- **Pre-conditions** : Formateur authentifie, attribution active (`planifie` ou `en_cours`)
- **Scenario** :
  1. Formateur ouvre app mobile-friendly "Mes attributions"
  2. Selectionne attribution du jour
  3. Saisit `attribution_heures_realisees`
  4. Confirme

## 4. Use cases AGENCE detailles (nouveau)

### UCA-02 — Creer un projet client

- **Acteur** : Admin
- **Pre-conditions** : Admin authentifie. Client existe (sinon UCA-01 d'abord).
- **Scenario** :
  1. Admin ouvre vue "Projets" filtree par client
  2. Clique "Nouveau projet"
  3. Renseigne nom, type (site_web/app/api/...), description, charge estimee, dates
  4. Optionnel : lie a une FORMATION si projet pedagogique
  5. Statut = `devis`
  6. Sauvegarde
- **Post-condition** : Projet cree, `heures_realisees = 0`

### UCA-04 — Attribuer une tache a un developpeur

- **Acteur** : Admin (ou developpeur s'auto-attribuant si modele permissif)
- **Pre-conditions** : Tache existe statut `todo`, Personne avec role `developpeur` actif
- **Scenario** :
  1. Admin ouvre kanban projet, vue par statut
  2. Drag tache de `todo` vers une swimlane Personne
  3. (Pas d'INTERVENTION cree a l'attribution — l'INTERVENTION sera creee a chaque saisie d'heures)
- **Post-condition** : Tache associee informellement a un dev (via property "assignee" sur la tache), prete pour saisie INTERVENTION

> Note : la tache n'a pas de FK directe vers la personne — le lien dev-tache se fait via les INTERVENTIONS. L'assignment "logique" peut etre une property optionnelle sur tache (`tache_assignee_id`) si on veut tracer une assignation avant saisie d'heures.

### UCA-07 — Saisir une intervention

- **Acteur** : Developpeur
- **Pre-conditions** : Developpeur authentifie, tache existe
- **Scenario** :
  1. Dev ouvre app mobile-friendly "Mes taches"
  2. Selectionne tache du jour
  3. Saisit nombre d'heures + date + notes optionnelles (commit ref, lien PR)
  4. Confirme → INTERVENTION creee statut `realise`
  5. System recalcule rollups (tache, projet, personne)
- **RG** : `intervention_heures > 0`, RG-PERSONNE-03 role developpeur requis

### UCA-09 — Marquer une tache comme done

- **Acteur** : Developpeur (ou Admin)
- **Scenario** :
  1. Dev marque tache comme `review` ou `done`
  2. Si admin valide review, tache passe `done`
- **Workflow** : optionnel d'avoir un statut intermediate `review` pour validation admin

## 5. Use cases CROSS (Personne pivot)

### UCX-02 — Consulter capacite totale d'une Personne

- **Acteur** : Admin
- **Pre-conditions** : Personne existe
- **Scenario** :
  1. Admin ouvre fiche Personne
  2. Voit dashboard :
     - Capacite totale annuelle : 1500h
     - Split formation/agence : 50/50
     - Heures attribuees formation : 400h (sur 750 alloues)
     - Heures attribuees agence : 600h (sur 750 alloues)
     - Heures restantes total : 500h
     - Liste de ses attributions formation
     - Liste de ses interventions agence
- **Post-condition** : vue 360 sur la charge d'une personne

### UCX-03 — Ajuster split formation/agence

- **Acteur** : Admin
- **Scenario** :
  1. Admin edite fiche Personne
  2. Modifie `split_formation_pct` / `split_agence_pct`
  3. CHECK : somme = 100
  4. Sauvegarde → recalcul `heures_restantes_formation` et `heures_restantes_agence`
- **Cas d'usage typique** : Yan a 60% formation, 40% agence en periode peda intense, puis 30% formation, 70% agence pendant les vacances scolaires.

## 6. Diagramme de sequence — UCA-07 (saisir intervention)

```mermaid
sequenceDiagram
    actor Dev as Developpeur
    participant UI as Bridge UI mobile
    participant API as Bridge API
    participant Baserow
    participant DB as Baserow Engine

    Dev->>UI: Saisit heures sur tache T
    UI->>API: POST /interventions
    API->>API: Valide heures > 0, role dev OK
    API->>Baserow: POST /database/rows/intervention
    Baserow->>DB: INSERT intervention
    DB->>DB: Recalcul rollups (tache, projet, personne)
    DB-->>Baserow: ok
    Baserow-->>API: 201 row
    API-->>UI: 201 ok
    UI-->>Dev: Toast confirmation + nouvelle capacite restante
```

## 7. Cas d'usage hors-scope (a trancher)

- Workflow d'approbation des heures realisees par admin avant facturation
- Notification automatique formateur/dev quand tache attribuee
- Generation de feuilles de presence PDF
- Integration calendrier (iCal export attributions/taches)
- Gestion des conges/indispos qui reduisent la capacite (calendrier integre)
- API publique pour clients (visualiser leurs projets en mode auto-service)