# Contrat API

Toutes les routes métier exigent un JWT. Les listes de pointages et les routes
de détail sont limitées au propriétaire ; les administrateurs peuvent consulter
et gérer les pointages de tous les utilisateurs. Les événements restent privés
à leur créateur, comme auparavant.

## Pointages

- `GET /api/time/entries/` renvoie une liste de lignes journalières, avec
  `start_date`, `end_date`, `start_time`, `end_time`, `group_id` et `duration` en heures.
- `POST /api/time/entries/create/` accepte ces dates/heures et, pour un
  administrateur, `user_id`. Une entrée sans sortie est permise sur une journée.
- `PATCH /api/time/entries/{id}/` modifie un pointage simple. Une période sur
  plusieurs jours est découpée côté serveur. L'ancienne route `.../{id}/update/`
  reste un alias avec les mêmes validations ; `PUT` accepte aussi les champs partiels.
- `PATCH /api/time/groups/{uuid}/` modifie une période entière en transaction.
  Les dates/heures omises conservent les bornes existantes. La réponse est la
  première ligne, au même format que la création.
- `DELETE /api/time/groups/{uuid}/` supprime toutes les lignes du groupe en
  transaction. Une ligne d'un groupe ne peut pas être modifiée/supprimée isolément.
- `group_id` est attribué exclusivement par le serveur. Les chevauchements et
  les entrées ouvertes concurrentes sont refusés.

Le front recharge la liste après une mutation. Il utilise `duration` fourni par
le serveur et additionne les lignes d'un groupe pour afficher sa durée.

Le scan conserve les conflits HTTP 409. Pour les résoudre, le client renvoie
`resolution`, `time`, `scan_date` et, selon le conflit, `entry_id` ou `scan_time`.
Une résolution devenue obsolète ou chevauchant un autre pointage est refusée.

## Événements et comptes

La création et la modification d'événements renvoient le même objet complet
que la lecture. Dates, heures et couleurs sont validées côté serveur.

Un administrateur standard peut gérer les comptes ordinaires et les promouvoir
administrateurs. Seul un superutilisateur peut gérer les comptes superutilisateurs
ou accorder ce rôle. Un compte ne peut pas se supprimer, se désactiver ou retirer
son propre accès administrateur.

## Tâches, informations et mémos

L'espace Entreprise → Tâches et mémos est partagé entre tous les utilisateurs
authentifiés. Le destinataire désigne la personne concernée ; ce n'est pas une
publication privée.

- Table `notes_note` : titre, contenu, type (`task`, `info`, `memo`), auteur,
  destinataire facultatif, date de clôture et dates de création/modification.
- `GET /api/notes/` : liste paginée (`count`, `next`, `previous`, `results`,
  24 éléments par page). Filtres : `kind`, `scope=all|mine|to_me`,
  `state=all|pending|done`, `search`, `page`.
- `POST /api/notes/` : `title`, `content` facultatif, `kind`, `recipient_id`
  facultatif ou `null` pour toute l'équipe. L'auteur est fixé par le serveur.
- `GET|PATCH|DELETE /api/notes/{id}/` : consulter, modifier ou supprimer.
  Seuls l'auteur et les administrateurs peuvent modifier ou supprimer.
- `PATCH /api/notes/{id}/completion/` : `{ "is_done": true|false }`.
  L'auteur, le destinataire et les administrateurs peuvent terminer ou rouvrir
  une tâche. Une tâche destinée à toute l'équipe peut être terminée par chacun.
- `GET /api/notes/recipients/` : annuaire des comptes actifs limité à
  `id`, `username`, `first_name`, `last_name` et `color`.

Les réponses comprennent `can_edit` et `can_complete` pour l'interface ; les
mêmes permissions sont contrôlées à chaque écriture côté serveur. La suppression
d'un compte conserve ses publications en retirant la référence au compte.

## Session et migrations

Le client renouvelle un accès expiré avec `/api/auth/refresh/`, mutualise les
renouvellements concurrents dans le même onglet, puis rejoue la requête une fois.
Le nouveau refresh token remplace l'ancien, qui est placé sur liste noire.
Les erreurs de réseau ne suppriment pas la session ; un refresh invalide la ferme.

Exécuter `python manage.py migrate` à chaque déploiement. La migration 0005
réconcilie les contraintes physiques des pointages avec l'état Django. Elle
refuse les anciens pointages sans heure d'entrée et les doublons : ces données
doivent être corrigées explicitement, elles ne sont ni inventées ni supprimées.

## Vérification

- Backend : `python manage.py test time_tracking events users notes --noinput` avec
  une instance MySQL de test et un utilisateur autorisé à créer la base de test.
  Ne pas pointer `DATABASE_URL` vers une base de production pour ces tests.
- Frontend : `npm test`, `npm run lint`, `npm run build` dans `frontend`.