Les tableaux d'analyse

« Combien d’œuvres, combien d’exemplaires, lesquelles ne sortent jamais » : la question revient dans tous les modules, avec la même forme d’écran. Une rangée de cartes, un tableau cliquable en dessous. Le noyau fournit l’écran ; votre module fournit les chiffres.

from kewos.insights import (
    InsightCard, InsightColumn, InsightRow, InsightsState,
    has_insights_provider, register_insights_provider,
)


class TitleInsights:
    def state(self, session, classes) -> InsightsState:
        title = classes["library_title"]
        titles = list(session.execute(select(title).order_by(title.name)).scalars())
        return InsightsState(
            title="insights.library.title",
            cards=(
                InsightCard(key="titles", label="insights.library.titles", value=str(len(titles))),
            ),
            columns=(InsightColumn(key="name", label="library_title.name"),),
            rows=tuple(
                InsightRow(record_id=int(t.id), cells={"name": t.name}) for t in titles
            ),
        )


def register_library_insights() -> None:
    if not has_insights_provider("library_title"):        # le boot réimporte
        register_insights_provider("library_title", TitleInsights())

Un point d’entrée générique sert le tout :

GET /api/v1/insights/library_title

{"title":"insights.library.title",
 "cards":[{"key":"titles","value":"8"},{"key":"copies","value":"8"},
          {"key":"orphans","value":"1","token":"destructive"}],
 "columns":[{"key":"name","label":"library_title.name","kind":"text"}, ...],
 "rows":[{"record_id":2,"cells":{"name":"A Brief History of Time","copies":1}}, ...]}

Aucun écran n’est écrit. Les libellés sont des clés i18n, les colonnes ont un kind (text, progress, badge) qui choisit le rendu de la cellule, et record_id fait de chaque ligne un lien vers la fiche. Un modèle sans fournisseur répond 404 : la surface n’invente rien.

Le piège : un chiffre filtré n’est pas un chiffre faux, mais votre phrase peut l’être

Le session que vous recevez est la session filtrée. Elle ne montre que ce que l’appelant a le droit de voir, ce qui est exactement ce qu’on veut pour un décompte. Mais une conclusion tirée de deux décomptes peut devenir un mensonge.

Le fournisseur ci-dessus compte les œuvres, compte les exemplaires, et en déduit les œuvres « sans exemplaire ». Exécuté par deux utilisateurs sur la même base :

responsable :   8 œuvres,  8 exemplaires,  1 sans exemplaire
visiteur    :   8 œuvres,  0 exemplaire,   8 sans exemplaire

Le visiteur a le droit de lire le catalogue, pas les exemplaires. Ses deux décomptes sont justes. La phrase construite avec, elle, est fausse : ces huit œuvres ont bien des exemplaires, il ne les voit pas. Et la carte est en rouge, ce qui donne à un chiffre absent l’apparence d’un problème.

Deux façons de s’en sortir, à choisir explicitement :

• ne pas déduire : afficher ce qu’on compte, pas ce qu’on en conclut ;
• réserver le tableau à un rôle qui voit l’ensemble des données dont il dépend, et le dire dans les droits du modèle plutôt que d’espérer.

Ce qu’il ne faut surtout pas faire, c’est contourner la session filtrée pour « avoir le vrai chiffre » : ce serait révéler par un agrégat ce que la liste refuse de montrer.

Quatre modules du produit livrent un fournisseur d’analyse : la formation, le pipeline commercial, la signature électronique et le marketing.