85 lines
4.6 KiB
Markdown
85 lines
4.6 KiB
Markdown
# 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`.
|