API

Les routes sont servies sous /za/api/projects. Le routeur du core applique la session, la permission, la limite de débit et la vérification d'origine. Seule la route de désabonnement se passe de cette dernière : un client de messagerie la sollicite sans en-tête d'origine, et la signature de son lien en tient lieu. Un refus que la personne peut corriger répond un message en français, et parfois un code pour les cas qu'un appelant traite à part.

Le projet d'une requêteCopier le lien de la section

Une route d'admin qui travaille dans un projet le nomme dans son chemin : /admin/projects/:project/items. :project se lit d'abord comme un slug, puis comme un identifiant : un projet nommé « 2026 », de slug 2026, s'ouvre par son slug. Un projet inconnu répond 404.

Les routes qui visent une fiche, une mise à jour, une colonne, une étiquette ou un jalon par son :id n'en ont pas besoin : l'objet connaît son projet.

Une route publique lit ?projet=<slug>. Sans lui, c'est le projet mis en avant, ou le premier projet public et actif, dans l'ordre, quand il est interne. Un projet inconnu, interne ou archivé répond 404.

Admin : projetsCopier le lien de la section

Admin : fichesCopier le lien de la section

Un projet archivéCopier le lien de la section

Les fiches d'un projet archivé sont en lecture. Créer une fiche, la modifier, changer ses responsables, publier, modifier ou supprimer une de ses mises à jour, ou déplacer une fiche vers ce projet répond 409 avec le code project_archived : « Ce projet est archivé : le restaurer pour modifier ses fiches. » Déplacer une fiche hors d'un projet archivé reste possible, comme la supprimer.

Les courriels comptésCopier le lien de la section

announced compte les courriels mis dans la file d'envoi. Jusqu'à cinquante destinataires, ils y entrent avant la réponse, et le compte est exact : une adresse déjà prévenue ne compte pas. Au-delà, ils y entrent après la réponse, et announced est le nombre de destinataires, avant que la file écarte ceux déjà prévenus.

Filtrer et trier les fichesCopier le lien de la section

Une valeur inconnue répond 400 « Filtre invalide. ».

Une ficheCopier le lien de la section

Chaque fiche de l'admin porte id, slug, title, description, isPublic, kind, priority, dueDate, tasks ({ total, done }), project ({ id, slug, name, isPublic, isArchived }), column ({ id, key, name, isPublic, isDone, announce }), milestone ({ id, name, dueDate, isClosed } ou null), tag ({ id, name } ou null), shippedNote, voteCount, position (sa place au tableau, ou null), statusChangedAt, createdAt, updatedAt, createdBy, assignees (des comptes { id, name, email, image }), visible (la page publique la montre) et isOverdue. Dans la liste d'un projet, elle porte aussi reportCount (0 sans le module Rétroaction).

Un évènement de l'historique : { id, itemId, kind, actor, data, createdAt }, actor étant un compte ou null. Dans data, added et removed sont des comptes. Les types d'évènements sont listés dans Modèle de données.

Fusionner deux fichesCopier le lien de la section

POST /admin/items/:id/merge fait tout dans une transaction :

1. les votes de :id sont copiés vers intoId ; la copie d'un votant, compte ou navigateur, qui avait voté pour les deux est écartée ;
2. ses abonnés sont copiés de même ;
3. ses mises à jour passent à intoId, à leur date ;
4. vote_count de intoId est recompté, son updated_at avancé, et l'évènement merged ({ from, votes, updates }) écrit dans son historique ;
5. :id est supprimée, avec son historique, ses responsables et ce qui n'a pas été copié.

Quand intoId est publique, le module Rétroaction est d'abord interrogé par checkItemChange(:id, { isPublic: true }) : ses rapports vont se retrouver sur une fiche publique. Après la transaction, il entend onItemsMerged(:id, intoId), ou onItemDeleted(:id) s'il ne connaît pas ce crochet. Aucun courriel ne part.

Admin : jalons, colonnes, étiquettesCopier le lien de la section

PublicCopier le lien de la section

La feuille de route, la colonne, le journal, la fiche, le vote et le suivi lisent ?projet=<slug>. Les budgets des limites sont dans Configuration. Une fiche publique n'expose ni ses responsables, ni son échéance, ni sa priorité. Les fonctions serveur et les composants pour le site sont décrits dans Intégrer au site.

L'intégration projectsCopier le lien de la section

Le module publie, par @fraza/core/integrations, un objet de fonctions serveur sous le nom projects. Un autre module le lit par getIntegration('projects'), sans importer ce paquet, et reçoit null quand Projets est absent ou désactivé. Voir Intégrations entre modules. Le module Rétroaction s'en sert pour reprendre les projets et lier ses rapports aux fiches.

C'est un contrat : sa forme ne change qu'avec les modules qui l'appellent. L'objet porte contract, le numéro de ce contrat. Un module qui en parle un autre ignore l'intégration, comme si Projets était absent, avec un avertissement unique dans le journal.

Aucune de ces fonctions ne rend la description, les responsables, l'échéance ni la priorité d'une fiche. Seule similarItems rend le nombre de votes.

Ce que le module lit de l'intégration feedbackCopier le lien de la section

Dans l'autre sens, Projets appelle les fonctions que le module Rétroaction publie sous feedback, quand elles existent. Il vérifie d'abord son contract : une intégration feedback qui ne déclare pas le contrat 1 est ignorée, avec un avertissement unique dans le journal. Chaque fonction est facultative : absente, Projets fait sans. Une erreur dans l'une d'elles est journalisée, et le changement, déjà enregistré, reste.

onItemsMerged est venu après le contrat 1 : facultatif, il ne change pas son numéro.

Ce que fait Rétroaction de chacune est décrit dans Avec Rétroaction.