Aller au contenu principal

ADR-0176 : Navin Enterprise Banking Back-Office Automation Agent, couche produit d'opérations bancaires au-dessus du Control Plane

  • Statut : proposé le 2026-11-04, en attente de validation de l'utilisateur (voir « Points à valider »)
  • Date : 2026-11-04
  • Portée : nouveau projet navin-enterprise-banking-backoffice/ (backend FastAPI, workers, frontend Next.js 16, intégration Navin), types additifs du modèle OpenFGA (deploy/policies/openfga/model.fga), paquet OPA eai.banking_backoffice (deploy/policies/opa/banking_backoffice.rego), contrat contracts/v1/banking-action-request.schema.json, gabarit d'agent du Navin Manager préparé mais non publié
  • Documents liés : ADR-0101 (politique de licences), ADR-0103 (vLLM et LiteLLM), ADR-0108 (Opik), ADR-0166 (haute disponibilité déclarée, ClamAV et YARA-X), ADR-0171 (installation durcie), ADR-0173 (séparation du Manager et d'Enterprise), ADR-0174 (mémoire Mem0 et Cognee), ADR-0175 (Navin Enterprise RAG Agent, motif repris), audit navin-enterprise-banking-backoffice/docs/NAVIN_INTEGRATION_AUDIT.md, cahier des charges agent_uses_cases/00_Banking_Back_Office_Automation_Agent_Prompt.md

Contexte​

Le client demande une application bancaire complète de back-office : files de travail, opérations de paiement et de règlement, moteur de rapprochement, suspens et exceptions, traitement des instructions documentaires, frais et corrections sous contrôle, console de fin de journée, contrôles opérationnels, rapports et copilote IA, le tout installable par le Navin Manager comme gabarit de service en prépublication.

L'audit du 2026-11-04 montre que la plateforme fournit déjà, sous gouvernance : l'identité et le contexte tenant et projet (eai.auth.Principal, require_relation fail-closed), la passerelle d'outils (POST /v1/tools/{name}/invoke avec décision OPA, DLP et approbation), les approbations avec séparation des tâches et clé d'idempotence, les délégations datées et révocables, l'analyse obligatoire des fichiers (quarantaine, ClamAV, YARA-X), les bases de connaissances (Docling, Qdrant), la mémoire (Mem0, Cognee), les connecteurs avec courtier de secrets, l'outbox transactionnelle et le worker, les traces OpenTelemetry et Opik, les métriques Prometheus et l'audit chaîné. Le produit RAG (ADR-0175) montre le motif d'une couche produit au-dessus du Control Plane, avec RLS, SSE, BFF et descripteur non publié.

Il manque tout le métier bancaire : aucun moteur de rapprochement, aucun suspens, aucune confirmation du système source, aucune matrice de délégation par montant, devise, rail et niveau d'autorité, et aucun des modules voisins cités par le cahier des charges (Customer Operations, Compliance & Audit, KYC/AML, Credit Analysis) n'existe dans le dépôt.

Décision​

1. Une couche produit, pas une seconde plateforme​

QuiFait quoi
Navin Managerinstalle et exploite le runtime (API, workers, web), ses dépendances, TLS, santé, sauvegardes, mises à jour, rollback ; expose le gabarit dans l'onglet Agents avec le statut prepared
Control Planeidentités, tenants, projets, rôles, OpenFGA, OPA, approbations, délégations, outils, modèles par la passerelle LiteLLM, analyse des fichiers, connaissances, mémoire, secrets, quotas, audit, traces
Backend UC-00objets métier (files, dossiers, paiements observés, rapprochements, suspens, exceptions, instructions, ajustements, EOD, contrôles, rapports, conversations), Action Gateway, moteur de rapprochement ; appelle le Control Plane uniquement par le SDK Python enterprise_ai

Aucun second IAM, aucune passerelle LLM propre, aucune troisième solution de traçabilité : le backend n'appelle jamais directement Keycloak pour autre chose que la vérification de ses jetons, ni LiteLLM, Qdrant, Cognee, Docling, ClamAV ou YARA-X.

2. Les systèmes de la banque restent les seules sources de vérité​

Le core banking, le payment hub, les réseaux de compensation et le grand livre (GL) sont les seules sources de vérité des statuts, des soldes et des écritures. Le schéma PostgreSQL banking_backoffice conserve des dossiers, des écritures proposées, des instantanés de statut (payment_status_snapshots, reconciliation_source_snapshots), des références (ledger_entry_refs, subledger_entry_refs) et des journaux de workflow : ce sont des caches d'investigation horodatés et versionnés, jamais un livre officiel. Aucune table n'est présentée comme une seconde comptabilité ; toute écriture effective vient du GL par connecteur approuvé, avec référence immuable et preuve de comptabilisation.

3. Action Gateway​

Toute action à effet de bord sur un système bancaire passe par l'Action Gateway du backend :

  • un contrat d'outil typé (manifeste Tool du Control Plane : schémas, side_effects, requires_approval, idempotent) invoqué par la passerelle POST /v1/tools/{name}/invoke ;
  • un workflow maker-checker : approbation du Control Plane (POST /v1/approvals), séparation des tâches, quorum, approbation consommée une seule fois, et en plus la décision OPA eai.banking_backoffice par type d'opération, montant, devise, rail, région, urgence, conflit d'intérêts et niveau d'autorité ; l'initiateur n'approuve jamais sa propre action ; un sous-agent ou une identité de service n'est jamais approbateur ;
  • un en-tête Idempotency-Key sur chaque écriture de l'API et une clé d'idempotence dérivée du dossier et de sa version pour chaque appel au système source ; If-Match et ETag sur les mises à jour ;
  • la confirmation du système source : après soumission, le résultat reste unknown_pending_confirmation jusqu'à ce que verify_source_operation_status ait relu la source ; une opération n'est jamais marquée failed ou success par défaut, et une nouvelle soumission exige un nouvel identifiant et une relecture de la source.

4. Moteur de rapprochement déterministe​

Le moteur de rapprochement (1:1, 1:N, N:1, groupes, tolérances, devises, fenêtres de date) est déterministe, versionné (reconciliation_rule_versions) et reproductible ; il réserve transactionnellement les lignes appariées, conserve tous les candidats et leurs raisons, produit les totaux de contrôle par devise et période, et ne dépend d'aucun modèle de langage. Le LLM explique, synthétise et prépare ; il ne décide d'aucun appariement, n'invente aucun solde et ne confirme aucun paiement.

5. Observabilité​

Grafana, Loki et Tempo, demandés par le cahier des charges, sont sous AGPL-3.0 et refusés par l'ADR-0101. Comme pour le RAG (ADR-0175), les tableaux de bord, journaux et traces passent par les composants autorisés du catalogue : Prometheus, Alertmanager, Alloy, OpenSearch et OpenSearch Dashboards, Jaeger, Opik, ClickHouse facultatif. Les métriques bank_ops_* ne portent aucun identifiant de paiement ou de client comme étiquette ; la valeur non rapprochée est exposée par devise, jamais agrégée entre devises. L'audit métier (audit_event_references) renvoie à l'audit chaîné du Control Plane et survit à l'échantillonnage des traces.

6. Mémoire et connaissances​

Qdrant et Docling, par le domaine knowledge du Control Plane, servent aux procédures, barèmes et guides ; Cognee, par le contrat Navin Memory Provider (ADR-0174), est une mémoire explicative des liens documentaires et jamais la source de vérité d'une relation financière, comptable ou d'un statut. Installation dédiée par instance pour les banques tant que la séparation de Cognee n'est que logique (ADR-0175, point 4).

7. Rôles et autorisations​

Les douze rôles logiques (Operations Clerk, Payment Operator, Reconciliation Analyst, Suspense Analyst, Operations Supervisor, Settlement Manager, GL Controller, Credit Operations Officer, Compliance Reviewer, Operations Approver, Internal Auditor en lecture seule, Tenant Admin) sont des relations OpenFGA sur le type additif backoffice_instance, héritées par work_item, reconciliation_run, suspense_case, adjustment_draft, eod_checklist et document_instruction. Le contexte tenant, projet et instance vient toujours de l'identité validée, jamais du navigateur. Fail-closed : OpenFGA, OPA, analyse des fichiers et quotas indisponibles bloquent l'action protégée.

8. Connecteurs remplaçables et fonctionnement autonome​

Les modules Customer Operations, Compliance & Audit, KYC/AML et Credit Analysis sont absents du dépôt. UC-00 fonctionne seul : chaque intégration voisine est un port (ticketing, controls_export, kyc_status, credit_decision) avec une implémentation none par défaut qui affiche Not configured, et les connecteurs bancaires (core banking, payment hub, GL, relevés, clearing) sont des manifestes Connector du Control Plane, en lecture seule par défaut, avec une table de capacités déclarée par fournisseur. Aucun connecteur fictif ; aucune action simulée présentée comme opérationnelle.

9. Gabarit préparé, non publié​

Le gabarit navin-banking-backoffice-agent est ajouté au registre navin-manager/agent-templates avec le statut prepared et un descripteur validé contre navin-manager/catalog/schema/service.schema.json sur une copie temporaire du catalogue. Rien n'est copié dans navin-manager/catalog avant la validation explicite de l'utilisateur.

10. Réutilisation des motifs du RAG​

Backend FastAPI avec SQLAlchemy asynchrone et Alembic, RLS par set_config dans chaque transaction, travaux durables en PostgreSQL (FOR UPDATE SKIP LOCKED, outbox), exécutions avec SSE et reprise, frontend Next.js 16 avec MUI et BFF (aucun jeton dans le navigateur), contrat OpenAPI publié dans navin-enterprise-banking-backoffice/docs/api/openapi.json, politiques OPA et OpenFGA testées, descripteur de service vérifié par un script, documentation française et anglaise appariée.

Conséquences​

  • Les contrôles bancaires (maker-checker enrichi, confirmation source, matrice par montant) vivent dans le produit et dans le paquet OPA, sans modifier les domaines du Control Plane ; des extensions additives restent possibles.
  • Un passage supplémentaire par le Control Plane pour chaque outil ; latence mesurée par les tests de charge.
  • Le produit dépend de bacs à sable bancaires représentatifs pour ses tests E2E : aucun statut tested sans eux.
  • Les gains de productivité ne sont annoncés qu'avec une mesure avant et après.

Points à valider​

  1. Remplacement de Grafana, Loki et Tempo par les composants autorisés du catalogue (même choix que l'ADR-0175).
  2. Installation dédiée par instance pour les banques tant que la séparation de Cognee n'est que logique.
  3. Ports none par défaut pour les modules voisins absents, sans aucune implémentation fictive.
  4. Prépublication seulement : le gabarit reste prepared jusqu'à l'accord explicite de l'utilisateur.

Alternatives écartées​

  • Un grand livre miroir dans PostgreSQL : seconde comptabilité, contraire au cahier des charges.
  • Appariements proposés par le LLM : non reproductibles, non auditables.
  • Exécution directe des actions bancaires depuis l'outil, sans Action Gateway : pas de confirmation source ni d'anti-double exécution.
  • Grafana, Loki et Tempo : AGPL-3.0, refusés par l'ADR-0101.
  • Publication immédiate dans le catalogue du Manager.

Plan de réalisation​

Quatorze lots suivis sur le tableau du projet, dans l'ordre de la section 23 du cahier des charges : audit et ADR ; contrats v1 ; schémas de paiement et connecteurs source ; ingestion, événements, workflows et permissions ; moteur de rapprochement 1:1 et totaux ; N:M, tolérances, ambiguïtés et versionnement ; suspens, exceptions et réparations ; actions source contrôlées et maker-checker ; documents et extraction ; contrôle EOD ; interfaces opérationnelles ; RAG, copilote et rapports ; tests des invariants, de la double exécution et de la sécurité ; observabilité, HA et packaging Navin Manager.