Référence API — Work (Projets & Support)

Work est le moteur commun de deux modules du Hub : Projets (tâches) et Support (tickets). Un même type d'objet, le WorkItem, porte type = task | ticket.

• Base URL — prod : https://work.puwapi.com · dev : http://localhost:5500
• Auth : JWT (Authorization: Bearer). Gating : Projets = Business+, Support = Scale+.

Concepts¶

• Projet — porte une clé courte et unique (ex. WEB, APP) et un compteur. Chaque item reçoit un numéro séquentiel par projet → une référence WEB-1, WEB-2…
• Tout item a un projet. Sans projet précisé à la création, un projet par défaut GEN est créé automatiquement.
• Position — un flottant qui ordonne les cartes dans une colonne (glisser-déposer).
• Statuts — vocabulaire fixe (ex. todo, in_progress, done pour les tâches ; file de statuts pour les tickets).

Projets¶

Base : /api/work/projects

Méthode	Route	Rôle
GET	/api/work/projects	Lister les projets
POST	/api/work/projects	Créer un projet (key, color…)
PATCH	/api/work/projects/{id}	Modifier (renommer, archiver)
DELETE	/api/work/projects/{id}	Supprimer — refusé si des items existent (archivez plutôt)

La clé est normalisée en majuscules, unique par organisation, motif [A-Z0-9]{2,10}.

Items (tâches & tickets)¶

Base : /api/work/items

Méthode	Route	Rôle
GET	/api/work/items	Lister (filtre projectId, status…)
GET	/api/work/items/board	Vue Kanban (groupée par statut, triée par position)
GET	/api/work/items/{id}	Détail d'un item
POST	/api/work/items	Créer un item (résout le projet, réserve le numéro, calcule la position)
PATCH	/api/work/items/{id}	Modifier (titre, description, échéance…)
POST	/api/work/items/{id}/status	Changer le statut
POST	/api/work/items/{id}/move	Déplacer (statut + position) — pour le glisser-déposer
POST	/api/work/items/{id}/assign	Assigner à un membre
POST	/api/work/items/{id}/link-appointment	Lier à un rendez-vous
DELETE	/api/work/items/{id}	Supprimer

Move (MoveRequest { status, position? }) déplace un item en une opération : statut + position, avec journal d'activité moved.

Commentaires¶

Méthode	Route
GET	/api/work/items/{itemId}/comments
POST	/api/work/items/{itemId}/comments

Connecteurs¶

Base : /api/work/connectors — sources d'entrée d'items (manuel, formulaire web…).

Méthode	Route
GET / POST	/api/work/connectors
PATCH / DELETE	/api/work/connectors/{id}
POST	/api/work/connectors/{connectorId} (ingestion)

Intégration GitHub¶

Base : /api/work — lier des items à des issues/PR GitHub et refléter leur statut.

Méthode	Route	Rôle
GET/PUT/DELETE	/api/work/github/config	Configurer le dépôt + jeton (PAT) + secret webhook (par organisation)
GET	/api/work/items/{id}/github	Lien GitHub de l'item
POST	/api/work/items/{id}/github/issue	Créer une issue (titre préfixé de la référence KEY-N)
POST	/api/work/items/{id}/github/link	Lier une issue/PR existante (URL)
POST	/api/work/github/webhook	Webhook GitHub (anonyme, signé HMAC SHA-256)

Le webhook vérifie la signature X-Hub-Signature-256 sur le corps brut ; sur issues/pull_request fermée/rouverte, il mappe le statut de l'item (closed → done / resolved, reopened → in_progress). Idempotent ; dépôt inconnu ou signature absente = 200 silencieux ; signature invalide = 403.

Route interne (M2M)¶

POST /api/work/internal/ingest — crée une tâche/ticket depuis un autre module (ex. Forms). [AllowAnonymous], protégée par X-Internal-Secret, tenant porté par le corps. Voir Ponts M2M.

Temps réel¶

Après écriture, Work notifie Convex (/work/notify) : item_created, status_changed, assigned, item_deleted, github_linked, comment_added.