Gabarit de spécification de package

Statut documentaire : guide — voir Maturité et preuves.

Objet du package

Décrire ici l’intention fondamentale du package. Le texte doit expliciter quel problème de connaissance le package résout, ce qu’il stabilise du point de vue sémantique et pourquoi ce package mérite d’exister indépendamment des écrans, des workflows ou des tables techniques qui l’utiliseront. Il faut préciser s’il s’agit d’un package fondationnel, transverse métier ou sectoriel, et rappeler ce que cela implique sur ses dépendances et sur sa gouvernance.

Positionnement ontologique

Expliquer ici dans quel niveau se situe le package et justifier ce positionnement. Le texte doit préciser de quels concepts plus fondamentaux le package dépend, et si le package spécialise des patterns existants ou définit des abstractions nouvelles. Lorsque le package est sectoriel, il faut indiquer explicitement quelles spécialisations sont introduites et à partir de quels concepts des niveaux inférieurs elles dérivent.

Concepts structurants

Décrire ici les concepts principaux du package en paragraphes rédigés. Pour chacun, préciser son identité, ses propriétés essentielles, sa relation avec les autres concepts du package et les raisons pour lesquelles il existe comme concept distinct. Il faut éviter les descriptions purement tabulaires ; le lecteur doit comprendre le sens métier du concept avant d’en voir l’implémentation.

Invariants et règles métier structurelles

Documenter ici les propositions qui doivent rester vraies dans tout le cycle de vie du package. Il faut distinguer les invariants portés par une entité isolée, les invariants d’agrégat, les invariants temporels et les contraintes inter-concepts. Lorsque certaines règles sont imposées aussi par la persistance, il faut le signaler, sans pour autant remplacer la formulation métier par une simple contrainte technique.

Cycle de vie et événements de domaine

Décrire les états métier structurants du package, les transitions autorisées et les conditions associées. Ensuite, préciser les événements publiés par le package et leur signification. Il faut également documenter les événements consommés en provenance d’autres packages lorsque ceux-ci influencent le comportement interne. L’objectif est de rendre lisible la dynamique métier du package.

Frontières transactionnelles et agrégats

Expliquer ici quelle est la racine d’agrégat ou quelles sont les racines d’agrégat du package, quels invariants elles protègent et pourquoi cette découpe a été retenue. Lorsque certains concepts sont volontairement externalisés en entités satellites ou en projections, il faut justifier ce choix en termes de volumétrie, de fréquence de modification, de cohérence transactionnelle ou d’historisation.

Projection technique

Présenter ici la manière dont les concepts sont projetés en classes, objets XML, facettes, tables, collections, actions et services. Le texte doit montrer que l’implémentation reste fidèle à la structure ontologique. Si des compromis techniques existent, ils doivent être rendus explicites, notamment lorsqu’une optimisation de persistance, d’indexation ou de recherche conduit à introduire des structures dérivées.

Règles d’extension

Documenter ici la manière correcte d’étendre le package. Il faut préciser quels éléments peuvent être paramétrés, lesquels peuvent être spécialisés dans des packages sectoriels et lesquels relèvent du noyau non modifiable sans revue d’architecture. Cette section est cruciale pour éviter les dérives futures et préserver la réutilisabilité du package.