Lesstime/docs/superpowers/specs/2026-05-22-mcp-absence-crud-tools-design.md

Spec — Extension des outils MCP : module Absences + trous CRUD

Date : 2026-05-22 Branche : feat/absence-management

Contexte & objectif

Le serveur MCP Lesstime (src/Mcp/Tool/) expose aujourd'hui les projets, tâches, métadonnées de tâches, time tracking et workflows. Le nouveau module Absences (AbsenceRequest, AbsencePolicy, AbsenceBalance) n'est pas exposé, et plusieurs entités existantes n'ont qu'une couverture partielle (souvent list sans create/update/delete).

Objectif : permettre de piloter l'app via MCP (assistant) sur ces domaines, en respectant strictement la logique métier déjà en place.

Conventions reprises de l'existant

• Une classe par outil, attribut #[McpTool(name, description)] sur la classe.
• Discovery automatique : config/packages/mcp.yaml scanne src/ (exclut DataFixtures). Aucune config à ajouter — créer la classe suffit.
• Constructeur : injection de repos/services + Security.
• __invoke(...) : check de rôle en première ligne (AccessDeniedException sinon), validation des IDs (InvalidArgumentException si introuvable), retour json_encode(...).
• Sérialisation centralisée dans App\Mcp\Tool\Serializer.
• Rôle : ROLE_USER pour la lecture/écriture courante ; ROLE_ADMIN pour les opérations sensibles (déjà le cas pour list-clients/list-users, et pour les opérations admin du module absences).

Décision clé — réutilisation de la logique métier (pas les Processors)

Les Processors API Platform (AbsenceRequestProcessor, AbsenceReviewProcessor, AbsenceCancelProcessor) sont liés à Security::getUser() (l'utilisateur courant) et à l'Operation HTTP. En MCP, l'utilisateur courant est le propriétaire du token (admin), or on veut pouvoir agir au nom d'un employé.

→ Les outils MCP n'appellent pas les Processors ; ils répliquent leur orchestration en réutilisant les services partagés qui portent la vraie règle métier :

• AbsenceDayCalculator::countWorkingDays(...) — calcul des jours décomptés.
• AbsenceBalanceService — reservePending, applyApproval, release, periodFor.
• AbsencePolicyRepository::findOneByType(...) — politique active du type.
• AbsenceRequestRepository::hasOverlap(...) — règle anti-chevauchement.

create-absence-request prend un userId explicite (l'employé cible) ; review/cancel posent reviewedBy = utilisateur du token MCP.

Ainsi soldes (pending/taken/acquired) et statuts restent cohérents avec ce que produit l'UI.

Inventaire des outils

Module Absences — src/Mcp/Tool/Absence/ (10 outils)

Outil	Rôle	Paramètres	Logique
list-absence-requests	USER	userId?, status?, type?, from?, to?	Filtre ; sans userId renvoie tout (token admin).
get-absence-request	USER	id	—
create-absence-request	USER	userId, type, startDate, endDate, startHalfDay?, endHalfDay?, reason?	Vérifie policy active + overlap, calcule countedDays, refuse si ≤ 0, statut Pending, reservePending.
review-absence-request	ADMIN	id, decision (approve|reject), rejectionReason?	Seulement si Pending. Approve → applyApproval ; reject → rejectionReason requis + release(false). Pose reviewedAt/reviewedBy.
cancel-absence-request	USER	id	Pending → release(false) ; Approved → ADMIN requis + release(true) ; sinon conflit. Statut Cancelled.
delete-absence-request	ADMIN	id	Suppression définitive.
list-absence-policies	USER	—	Toutes les policies (ordre type).
update-absence-policy	ADMIN	id, daysPerYear?, daysPerEvent?, justificationRequired?, noticeDays?, countWorkingDaysOnly?, active?	Seuls les champs fournis changent.
list-absence-balances	USER	userId?, type?, period?	Soldes filtrés.
update-absence-balance	ADMIN	id, acquired?, acquiring?, taken?	Ajustement manuel (régularisation).

type et status acceptés en valeur d'enum string (ex. cp, maladie, pending) ; erreur de validation explicite si invalide. startDate/endDate au format YYYY-MM-DD.

Trous CRUD sur l'existant

Projets / groupes

• delete-project (ADMIN) — id.
• delete-group (USER) — id.

Métadonnées de tâches — src/Mcp/Tool/TaskMeta/

• create-tag / update-tag / delete-tag (USER) — label, color?.
• create-effort / update-effort / delete-effort (USER) — label (+ ordre éventuel).
• create-priority / update-priority / delete-priority (USER) — label, color?.
• create-status / update-status / delete-status (ADMIN) — workflowId requis
  • category (todo|in_progress|blocked|review|done), label, color?, position?, isFinal?. (Les statuts ne sont PAS globaux : ils appartiennent à un workflow.)

Clients — src/Mcp/Tool/Reference/ (ADMIN, aligné sur list-clients)

• get-client — id.
• create-client — name (+ email?, phone?, street?, city?, postalCode?).
• update-client — id + champs optionnels.
• delete-client — id.

Utilisateurs — src/Mcp/Tool/Reference/ (ADMIN)

• get-user — id (profil complet RH).
• update-user — id + champs RH/profil : isEmployee?, hireDate?, endDate?, contractType?, workTimeRatio?, annualLeaveDays?, referencePeriodStart?, initialLeaveBalance?, familySituation?, nbChildren?. Hors périmètre (décision utilisateur) : pas de create-user, pas de modification de password ni roles via MCP.

Sérialisation — ajouts à Serializer.php

• absenceRequest(AbsenceRequest) : id, user{id,username}, type{value,label}, startDate, endDate, startHalfDay, endHalfDay, countedDays, reason, status{value,label}, rejectionReason, createdAt, reviewedAt, reviewedBy, justificationFileName.
• absencePolicy(AbsencePolicy) : id, type{value,label}, daysPerYear, daysPerEvent, justificationRequired, noticeDays, countWorkingDaysOnly, active.
• absenceBalance(AbsenceBalance) : id, user, type{value,label}, period, acquired, acquiring, taken, pending, acquiredTotal, available.
• client(Client) : id, name, email, phone, street, city, postalCode.
• userFull(User) : id, username, roles, isEmployee, hireDate, endDate, contractType, workTimeRatio, annualLeaveDays, referencePeriodStart, initialLeaveBalance, familySituation, nbChildren.

Mise à jour de la doc MCP

config/packages/mcp.yaml — bloc instructions :

• corriger la mention « statuses … are GLOBAL » (faux : par workflow) ;
• ajouter une phrase sur le domaine Absences (requests/policies/balances, lifecycle approve/reject/cancel, userId pour agir au nom d'un employé).

Découpage du plan d'implémentation (jalons)

1. Absences : Serializer + 10 outils + tests de cohérence des soldes.
2. Métadonnées tâches : delete-project/group, CRUD tag/effort/priority/status.
3. Clients & users : CRUD clients, get/update user + maj mcp.yaml.

Chaque jalon est livrable et testable indépendamment.

Tests

Tests fonctionnels MCP (si une infra de test MCP existe) ou tests unitaires sur la réplication de la logique de solde : créer → review(approve) → cancel et vérifier pending/taken à chaque étape ; vérifier le refus sur chevauchement et sur plage sans jour ouvré.

Hors périmètre

• Mail, BookStack, Gitea, Zimbra, Notifications, TaskDocument (non demandés).
• Création d'utilisateurs et gestion mot de passe/rôles via MCP.
• Upload de justificatif d'absence via MCP.