Skill : Pipeline Affaires Diplomatiques (Orchestrateur)

Regle : Si la requete porte sur un sujet couvert par un skill specialise, lire d'abord CE skill specialise puis revenir ici pour le contexte global.

Reference Principale

Lire IMPERATIVEMENT avant toute action :

1. convex/_generated/ai/guidelines.md — Regles Convex (CRITIQUE)
2. convex/schemas/diplomaticAffairs.ts — Schema complet
3. convex/functions/diplomaticAffairs.ts — Fonctions CRUD
4. convex/ai/diplomaticAI.ts — Actions IA Gemini

Architecture du Module

Tables Convex (6 + 2 nouvelles)

Tables existantes :

Tables a ajouter :

Pipeline en 5 Phases

targeting → strategy → outreach → reporting → project

Matrice de transition :

const transitionMatrix = {
  targeting: ["strategy"],           // Cible → Plan
  strategy: ["outreach", "targeting"], // Plan → Lettres (ou retour ciblage)
  outreach: ["reporting", "strategy"], // Lettres → Rapports (ou retour strategie)
  reporting: ["project", "outreach"],  // Rapports → Projet (ou retour contact)
  project: [],                        // Phase finale
};

Regles de transition :

• On ne peut avancer que vers les phases autorisees dans la matrice
• Le retour en arriere est possible (strategy → targeting, outreach → strategy, etc.)
• La phase project est terminale
• Chaque transition est loguee dans historiqueEtapes

State Machine des Statuts

Chaque entite a son propre cycle de statuts :

Cible (Target) :

identifie → en_analyse → qualifie → contacte → en_negociation → partenaire → archive → rejete

Plan Strategique :

brouillon → en_revue → approuve → archive

Lettre :

brouillon → en_revue → approuvee → envoyee → reponse_recue → archive

Rapport :

brouillon → en_revue → valide → archive

Projet :

identification → formulation → en_revue → approuve → en_cours → termine → archive

Actions IA (Gemini 2.5 Flash)

6 actions dans convex/ai/diplomaticAI.ts :

Pattern commun :

export const actionName = authAction({
  args: { orgId: v.id("orgs"), targetId: v.id("diplomaticTargets"), ... },
  handler: async (ctx, args) => {
    // 1. Recuperer les donnees necessaires
    // 2. Construire le prompt Gemini
    // 3. Appeler Gemini via generateJSON() ou generateText()
    // 4. Sauvegarder le resultat via ctx.runMutation(...)
    // 5. Retourner le resultat
  }
});

Auth et Custom Functions

CRITIQUE — Ne JAMAIS utiliser les fonctions Convex brutes.

// ✅ CORRECT
import { authQuery, authMutation, authAction } from "../lib/customFunctions";
import { rawInternalMutation, rawInternalQuery, rawInternalAction } from "../_generated/server";

// ❌ INTERDIT
import { query, mutation, action } from "../_generated/server";

Pour les fonctions internes (hooks, schedulers) :

import { rawInternalMutation as internalMutation } from "../_generated/server";

Priorites Diplomatiques du Gabon

Les 7 axes prioritaires qui guident TOUT le pipeline :

1. Diversification economique — Sortir de la dependance petroliere
2. Industrialisation — Transformation locale des matieres premieres (bois, manganese, fer)
3. Emploi des jeunes — Chaque partenariat doit creer des emplois et former
4. Souverainete — Le Gabon decide, le Gabon controle, le Gabon beneficie
5. Developpement durable — 88% de foret tropicale = actif strategique
6. Integration CEMAC — Renforcer le leadership regional
7. Numerique — Digitalisation des services (consulat.ga en est la preuve)

Ces priorites sont stockees dans la table diplomaticPriorities et chaque cible/plan/projet est evalue par rapport a elles.

Flux de Donnees Inter-Entites

                    ┌─────────────────────────┐
                    │   diplomaticPriorities   │
                    │   (axes prioritaires)    │
                    └──────────┬──────────────┘
                               │ aligne
                    ┌──────────▼──────────────┐
      discoverTargets │   diplomaticTargets    │
      enrichTarget    │   (cibles operateurs)  │
                    └──────────┬──────────────┘
                               │ targetId
                    ┌──────────▼──────────────┐
      generateStrategy│   diplomaticPlans     │
                    │   (plans strategiques)  │
                    └──────────┬──────────────┘
                               │ targetId + planId
                    ┌──────────▼──────────────┐
      draftLetter     │   diplomaticLetters   │
                    │   (lettres officielles) │
                    └──────────┬──────────────┘
                               │ targetId
                    ┌──────────▼──────────────┐
      compileReport   │   diplomaticReports   │
                    │   (rapports reunion)    │
                    └──────────┬──────────────┘
                               │ targetId + reportIds
                    ┌──────────▼──────────────┐
      structureProject│   diplomaticProjects  │
                    │   (projets cooperation) │
                    └──────────┘
                               │
              ┌────────────────┼────────────────┐
              ▼                ▼                ▼
      diplomaticFolders  diplomaticDocuments  [Export ZIP]

Frontend — Structure des Routes

App : apps/agent-web (TanStack Router)

/affaires-diplomatiques
  ├── /                          → Dashboard (KPI, pipeline, carte monde)
  ├── /cibles                    → Liste des cibles (filtres, recherche)
  ├── /cibles/:id                → Fiche cible detaillee
  ├── /plans                     → Liste des plans strategiques
  ├── /plans/:id                 → Plan strategique detaille
  ├── /lettres                   → Liste des lettres
  ├── /lettres/:id               → Lettre detaillee
  ├── /rapports                  → Liste des rapports
  ├── /rapports/:id              → Rapport detaille
  ├── /projets                   → Liste des projets
  ├── /projets/:id               → Projet detaille
  ├── /dossiers                  → Explorateur de dossiers
  ├── /dossiers/:secteur/:cible  → Dossier d'un operateur
  └── /priorites                 → Gestion des axes prioritaires

Composants communs :

• PipelineStepper.tsx — Barre de progression des 5 phases
• TargetPipelineCard.tsx — Carte cible avec phase actuelle
• AIActionPanel.tsx — Panneau d'actions IA (boutons Gemini)
• FolderExplorer.tsx — Navigation dans les dossiers
• ExportZipButton.tsx — Export ZIP du dossier complet

Design Charter

Suivre STRICTEMENT la charte DESIGN_CHARTER.md :

• Palette achromatique : 6 gris + 4 accents (bleu, vert, amber, rose)
• Couleurs Gabon (vert/jaune/bleu) = decoratif UNIQUEMENT (bandeau, tints)
• JAMAIS de couleurs Tailwind brutes (blue-500, green-100)
• JAMAIS de gradient colore pour les fonds de section
• Ombres achromatiques exclusivement
• Icones : lucide-react uniquement
• Neumorphic Soft UI : classes .neu-*

Conventions de Code

Nommage

• Tables : camelCase (ex: diplomaticTargets)
• Fonctions : camelCase (ex: createTarget, advancePhase)
• Validators : camelCaseValidator (ex: strategicAnalysisValidator)
• Composants : PascalCase (ex: TargetPipelineCard)
• Fichiers fonctions : camelCase.ts (ex: diplomaticAffairs.ts)
• Fichiers composants : PascalCase.tsx (ex: AIActionPanel.tsx)

Schema

• TOUJOURS : createdAt, updatedAt (timestamps v.number())
• TOUJOURS : createdBy: v.id("users")
• TOUJOURS : orgId: v.id("orgs")
• TOUJOURS : statut comme v.union(v.literal(...), ...)
• TOUJOURS : historiqueEtapes pour les workflows
• TOUJOURS : deletedAt: v.optional(v.number()) pour le soft delete
• TOUJOURS : filtrer avec .filter(q => q.eq(q.field("deletedAt"), undefined))

Mutations

• TOUJOURS ajouter updatedAt: Date.now() dans les updates
• TOUJOURS loguer dans historiqueEtapes les changements de statut
• TOUJOURS verifier les transitions autorisees avant un changement de phase
• TOUJOURS utiliser ctx.scheduler.runAfter(0, ...) pour les effets de bord (hooks)

Rappels Critiques

1. Convex guidelines — Lire convex/_generated/ai/guidelines.md AVANT tout code
2. customFunctions — JAMAIS les fonctions brutes Convex
3. Gemini 2.5 Flash — Seul modele IA autorise
4. Schema-first — Le schema est le contrat
5. Soft delete — Jamais de suppression physique
6. Mobile-first — 3G, Android, 5-6 pouces
7. Francais gabonais — Langage clair et accessible
8. Souverainete du code — Le code appartient au Gabon