kavaa-kcge-viewmodels

Contrats TypeScript purs pour le Kavaa Committee Governance Engine.

Ce package contient uniquement les ViewModels et payloads échangés entre le backend/BFF KCGE, les tests et kavaa-kcge-ui-angular. Il ne dépend pas d'Angular, ne contient pas d'appel HTTP, ne contient pas de logique de calcul métier et ne doit pas recalculer quorum, décision, droits ou options de vote.

Sommaire

• Responsabilité du package
• Installation
• Utilisation
• Contrats exportés
• Règles métier et sécurité
• Évolution des contrats
• Développement dans ce monorepo
• Dépannage
• Checklist d'intégration

Responsabilité du package

kavaa-kcge-viewmodels est le socle partagé entre:

| Consommateur | Usage | | --- | --- | | Backend/BFF KCGE | Produit les projections front-facing. | | kavaa-kcge-ui-angular | Rend les données sans recalcul métier. | | Applications hôtes | Typent les providers, handlers et mappings API. | | Tests | Fabriquent des stubs et valident les invariants. |

Le package est volontairement limité à TypeScript:

• zéro import Angular;
• zéro HttpClient;
• zéro Observable;
• zéro DOM;
• zéro logique de calcul de quorum ou décision;
• zéro inférence IAM ou rôle front.

Installation

Depuis le registre npm configuré

npm install kavaa-kcge-viewmodels

Pour une application Angular utilisant le UI Kit:

npm install kavaa-kcge-viewmodels kavaa-kcge-ui-angular

Le package dépend uniquement de:

| Package | Version | | --- | --- | | tslib | ^2.3.0 |

Dans ce monorepo Nx

Le package est résolu localement via tsconfig.base.json:

{
  "paths": {
    "kavaa-kcge-viewmodels": ["./libs/kcge-viewmodels/src/index.ts"]
  }
}

Utilisation

Importer les types avec import type lorsque le code ne les utilise qu'au typage.

import type {
  CastVoteRequest,
  CommitteeSessionWorkspaceViewModel,
  DecisionResultViewModel,
  KcgeIntent
} from 'kavaa-kcge-viewmodels';

Exemple de mapping dans un provider hôte:

import type { CommitteeSessionWorkspaceViewModel } from 'kavaa-kcge-viewmodels';

export function mapWorkspaceDto(dto: KcgeWorkspaceDto): CommitteeSessionWorkspaceViewModel {
  return {
    meta: {
      contractVersion: dto.contractVersion,
      viewType: 'CommitteeSessionWorkspace',
      generatedAt: dto.generatedAt,
      tenantId: dto.tenantId,
      correlationId: dto.correlationId
    },
    sessionHeader: dto.sessionHeader,
    sessionStatus: dto.sessionStatus,
    agendaSummary: dto.agendaSummary,
    agendaItems: dto.agendaItems,
    attendanceSummary: dto.attendanceSummary,
    decisionSummary: dto.decisionSummary,
    auditSummary: dto.auditSummary,
    logisticsSummaryFromKmme: dto.logisticsSummaryFromKmme ?? null,
    votePanels: dto.votePanels ?? [],
    agendaReviews: dto.agendaReviews ?? [],
    allowedActions: dto.allowedActions ?? []
  };
}

Exemple de handler:

import type { KcgeIntent } from 'kavaa-kcge-viewmodels';

function handleKcgeIntent(intent: KcgeIntent): void {
  switch (intent.type) {
    case 'openAgendaItemRequested':
      openAgendaItem(intent.agendaItemId);
      break;
    case 'addAgendaItemRequested':
      openAgendaCreation(intent.sessionId);
      break;
    case 'sessionActionRequested':
      auditSessionAction(intent.sessionId, intent.action);
      break;
  }
}

Contrats exportés

Métadonnées, statuts et actions

| Type | Description | | --- | --- | | KcgeAllowedAction | Code action serveur autorisée. Exemple: castVote, computeDecision, generateMinutes. | | KcgeActorRenderMode | Mode de rendu UI: secretary, voter, observer, admin. | | VoteOption | Option de vote serveur: Approve, Reject, Abstain, Defer ou extension backend. | | KcgeMeta | Version de contrat, type de vue, date, tenant et correlation. | | UiErrorState | Erreur affichable par le UI Kit. | | StatusViewModel | Code, libellé, tonalité et raison optionnelle. | | DecisionRuleViewModel | Code, libellé et description de règle de décision. |

Comités

| Type | Description | | --- | --- | | CommitteeListViewModel | Ligne de liste des comités avec statut, compteurs, dernière décision et actions. | | CommitteeDetailViewModel | Projection détaillée d'un comité avec règles, membres et sessions récentes. | | CommitteeMemberViewModel | Membre de comité, droit de vote et poids éventuel. | | RecentSessionViewModel | Session récente affichée dans le détail comité. | | CommitteeReadOnlyViewModel | Projection lecture seule, sans contrôle d'écriture. |

Session et workspace

| Type | Description | | --- | --- | | SessionHeader | Identité et dates d'une session. | | SessionStatusInfo | Statut de gouvernance de session. | | CommitteeSessionWorkspaceViewModel | Agrégat principal rendu par kavaa-committee-session-workspace. | | LogisticsSummaryFromKmme | Projection logistique optionnelle venant de KMME. | | KcgeIntent | Union des intentions émises par le UI Kit. |

CommitteeSessionWorkspaceViewModel contient:

• meta;
• sessionHeader;
• sessionStatus;
• agendaSummary;
• agendaItems;
• attendanceSummary;
• decisionSummary;
• auditSummary;
• logisticsSummaryFromKmme;
• votePanels;
• agendaReviews;
• allowedActions.

Agenda

| Type | Description | | --- | --- | | AgendaSummary | Totaux d'agenda: total, prêts, en attente, décidés. | | AgendaItemViewModel | Ligne d'agenda avec statut, règle, votes et actions. | | AgendaItemReviewViewModel | Revue d'un item: dossier, readiness DCE, notes, votes et actions. | | DocumentReadinessViewModel | État documentaire DCE associé à un item. | | VotesSummary | Compteurs synthétiques de votes. |

Présence et quorum

| Type | Description | | --- | --- | | AttendanceSummary | Quorum, membres présents et actions de présence. | | MemberAttendanceViewModel | Présence d'un membre, conflit d'intérêt éventuel, représentation. | | QuorumSnapshot | Snapshot serveur du quorum. Le front l'affiche sans recalcul. |

Vote

| Type | Description | | --- | --- | | VotePanelViewModel | Données de vote pour un membre et un item d'agenda. | | MemberContext | Membre votant, rôle d'affichage, droit de vote et poids. | | CurrentVote | Vote déjà exprimé. | | ConflictOfInterestState | État de conflit d'intérêt et blocage éventuel du vote. | | CastVoteRequest | Payload de vote envoyé par le UI Kit au provider. |

Décisions, PV et audit

| Type | Description | | --- | --- | | DecisionSummary | Synthèse des décisions et disponibilité du PV. | | DecisionResultViewModel | Résultat de décision calculé par le backend. | | VoteBreakdown | Détail des votes ou poids de décision. | | VoteBreakdownEntry | Ligne générique de breakdown. | | DecisionHistoryEntry | Historique d'une décision. | | MinutesAvailability | État de génération et URL de téléchargement du PV. | | AuditSummary | Résumé d'audit, overrides et événements. | | AuditEventViewModel | Événement d'audit. | | OverrideRequest | Payload d'override de décision. | | AttendanceRequest | Payload d'enregistrement de présence. |

Intentions KcgeIntent

| Type | Payload | | --- | --- | | openAgendaItemRequested | { agendaItemId } | | addAgendaItemRequested | { sessionId } | | sessionActionRequested | { sessionId, action } | | attendanceRecorded | { memberId, req } | | voteRequested | { agendaItemId, req } | | computeDecisionRequested | { agendaItemId } | | overrideDecisionRequested | { agendaItemId, req? } | | minutesRequested | { sessionId } | | conflictDeclared | { memberId, agendaItemId } |

Règles métier et sécurité

• allowedActions est la seule source d'autorisation UI.
• mode et actorContext servent au rendu et au chargement, jamais à autoriser une action.
• QuorumSnapshot est affiché tel quel.
• DecisionResultViewModel est affiché tel quel.
• voteOptions vient du backend.
• conflictOfInterestState.blocksVote = true doit bloquer le formulaire de vote.
• CommitteeReadOnlyViewModel.allowedActions doit rester vide pour les usages read-only.
• logisticsSummaryFromKmme est optionnel et ne doit pas contenir vote, quorum ou décision.
• contractVersion dans KcgeMeta doit évoluer quand le contrat change.

Évolution des contrats

Toute évolution doit suivre ce cycle:

1. Ajouter ou modifier le type dans libs/kcge-viewmodels/src/lib/kcge-viewmodels.ts.
2. Garder la compatibilité si le backend peut encore produire l'ancien contrat.
3. Ajouter les champs optionnels avec ? ou | null lorsque la donnée n'est pas garantie.
4. Mettre à jour le UI Kit si le champ est rendu.
5. Mettre à jour les mocks et tests.
6. Mettre à jour les README.
7. Augmenter contractVersion côté producteur backend/BFF.

Éviter:

• types Angular;
• classes avec comportement métier;
• fonctions de calcul;
• dépendances runtime;
• enums fermés si le backend peut ajouter de nouveaux codes.

Préférer:

• interfaces simples;
• unions souples avec string extensible si nécessaire;
• champs optionnels pour intégrations externes;
• payloads explicites pour les intents et requêtes.

Développement dans ce monorepo

Structure:

libs/kcge-viewmodels/
  package.json
  project.json
  tsconfig.json
  tsconfig.lib.json
  src/
    index.ts
    lib/
      kcge-viewmodels.ts

Commandes:

npm.cmd run build:viewmodels
npm.cmd run build:ui
npm.cmd run test:cdc -- --runInBand --verbose
npm.cmd run lint:architecture

Le script lint:architecture vérifie notamment que kavaa-kcge-viewmodels ne contient pas d'import Angular.

Publication:

npm.cmd run build:viewmodels

Sortie attendue:

dist/libs/kcge-viewmodels

Le package est ESM et expose:

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "default": "./dist/index.js"
    }
  }
}

Dépannage

Cannot find module 'kavaa-kcge-viewmodels'

Vérifier:

• le package est installé;
• le scope @kavaa pointe vers Azure Artifacts;
• l'authentification Azure Artifacts fonctionne;
• dans le monorepo, tsconfig.base.json contient le path local.

E401 pendant npm install

Relancer:

.\tools\npm\set-azure-artifacts-auth.ps1

Puis:

npm whoami --registry=https://pkgs.dev.azure.com/kavaa/CDC-Carthage/_packaging/Kavaa_Feed/npm/registry/

Une action UI ne s'affiche pas

Vérifier le ViewModel produit par le backend:

• allowedActions contient bien l'action;
• le statut de session est compatible;
• le contexte read-only n'a pas vidé les actions volontairement;
• le front n'utilise pas mode ou actorContext comme autorisation.

Le front affiche un mauvais quorum ou une mauvaise décision

Le calcul ne doit pas être corrigé dans kavaa-kcge-ui-angular. Corriger la projection produite par le backend/BFF KCGE, puis recharger le workspace.

TypeScript demande des extensions .js

Si le projet consommateur utilise moduleResolution: nodenext, les imports relatifs internes peuvent nécessiter .js. Les imports package restent:

import type { CommitteeSessionWorkspaceViewModel } from 'kavaa-kcge-viewmodels';

Checklist d'intégration

• kavaa-kcge-viewmodels est installé ou résolu par path Nx.
• Le registry @kavaa est configuré.
• L'auth Azure Artifacts fonctionne.
• Les DTO backend sont adaptés vers les ViewModels KCGE.
• KcgeMeta.contractVersion est renseigné.
• allowedActions est fourni par le backend.
• voteOptions est fourni par le backend.
• QuorumSnapshot est fourni par le backend.
• DecisionResultViewModel est fourni par le backend.
• logisticsSummaryFromKmme reste optionnel.
• Les champs externes DCE/KMME/KFE-L restent dans leurs zones dédiées.
• Aucun import Angular n'est ajouté dans ce package.
• npm.cmd run build:viewmodels passe.
• npm.cmd run lint:architecture passe.

Règle d'or

kavaa-kcge-viewmodels décrit le contrat. Il ne décide pas, ne calcule pas, n'appelle pas d'API et n'autorise aucune action.