ackify/docs/fr/admin-guide.md

Guide Administrateur

Guide complet pour les administrateurs utilisant Ackify pour gérer les documents, les signataires attendus et les rappels email.

Table des Matières

• Obtenir l'accès Admin
• Dashboard Admin
• Gestion des Documents
• Signataires Attendus
• Rappels Email
• Monitoring & Statistiques
• Bonnes Pratiques
• Dépannage

---

Obtenir l'accès Admin

Prérequis

Pour accéder aux fonctionnalités admin, votre email doit être configuré dans la variable d'environnement ACKIFY_ADMIN_EMAILS.

# Dans le fichier .env
ACKIFY_ADMIN_EMAILS=admin@company.com,manager@company.com

Après ajout de votre email:

1. Redémarrer Ackify: docker compose restart ackify-ce
2. Se déconnecter et se reconnecter
3. Vous devriez maintenant voir le lien "Admin" dans la navigation

Vérifier l'accès Admin

Visitez /admin - si vous voyez le dashboard admin, vous avez l'accès admin.

---

Dashboard Admin

URL: /admin

Le dashboard admin fournit:

• Total Documents: Nombre de documents dans le système
• Lecteurs Attendus: Nombre total de signataires attendus sur tous les documents
• Documents Actifs: Documents non supprimés
• Liste Documents: Liste paginée (20 par page) avec recherche

Fonctionnalités du Dashboard

Statistiques Rapides

Trois cartes KPI en haut:

• Nombre total de documents
• Total des lecteurs/signataires attendus
• Documents actifs (non supprimés)

Recherche de Documents

• Recherche par titre, ID document ou URL
• Filtrage en temps réel

Liste des Documents

Vue desktop - Tableau avec colonnes:

• ID Document
• Titre
• URL
• Date de création
• Créateur
• Actions (Voir détails)

Vue mobile - Mise en page carte avec:

• ID document et titre
• Info création
• Tap pour voir détails

Pagination

• 20 documents par page
• Boutons Précédent/Suivant
• Indicateur de page actuelle

---

Gestion des Documents

Créer un Document

Depuis le Dashboard Admin:

1. Cliquer sur le bouton "Créer Nouveau Document"
2. Remplir le formulaire:
   • Référence (requis): URL, chemin fichier ou ID personnalisé
   • Titre (optionnel): Auto-généré depuis l'URL si vide
   • Description (optionnel): Contexte additionnel
3. Cliquer sur "Créer Document"

Fonctionnalités Automatiques:

• Génération ID Unique: doc_id base36 résistant aux collisions
• Extraction Titre: Auto-extrait de l'URL si non fourni
• Calcul Checksum: Pour URLs distantes (si admin et fichier < 10MB)

Exemple:

Référence: https://docs.company.com/politique-2025.pdf
Titre: Politique de Sécurité 2025 (auto-extrait ou manuel)
Description: Politique annuelle de conformité sécurité

Résultat:

• doc_id: k7m2n4p8 (auto-généré)
• Checksum: SHA-256 auto-calculé (si URL accessible)

Voir les Détails d'un Document

URL: /admin/docs/{docId}

Fournit des informations complètes sur le document:

1. Section Métadonnées

Éditer les informations du document:

• Titre
• URL
• Description
• Checksum (SHA-256, SHA-512 ou MD5)
• Algorithme Checksum

Pour éditer:

1. Cliquer sur "Éditer Métadonnées"
2. Modifier les champs
3. Cliquer sur "Sauvegarder"
4. Modal de confirmation pour changements critiques (checksum, algorithme)

2. Panneau Statistiques

Suivi des signatures en temps réel:

• Attendus: Nombre de signataires attendus
• Signés: Nombre ayant signé
• En Attente: Pas encore signé
• Complétion: Pourcentage complété

3. Section Signataires Attendus

Liste tous les signataires attendus avec statut:

• Email: Adresse email du signataire
• Statut: ✅ Signé ou ⏳ En attente
• Ajouté: Date d'ajout à la liste attendue
• Jours Depuis Ajout: Suivi du temps
• Dernier Rappel: Quand le dernier rappel a été envoyé
• Nb Rappels: Total rappels envoyés
• Actions: Bouton retirer signataire

Code couleur:

• Fond vert: Signataire a signé
• Fond par défaut: Signature en attente

4. Signatures Inattendues

Affiche les utilisateurs ayant signé mais pas sur la liste attendue:

• Email utilisateur
• Date de signature
• Indique participation organique/inattendue

5. Actions

• Envoyer Rappels: Emailer les signataires en attente
• Partager Lien: Générer et copier lien de signature
• Supprimer Document: Suppression douce (préserve historique signatures)

Mettre à Jour les Métadonnées du Document

Champs importants:

Titre & Description:

• Peuvent être changés librement
• Pas de confirmation requise

URL:

• Met à jour où le document est localisé
• Modal de confirmation affiché

Checksum & Algorithme:

• Critique pour vérification d'intégrité
• Modal de confirmation avertit de l'impact
• Changer uniquement si version du document a changé

Workflow:

1. Cliquer sur "Éditer Métadonnées"
2. Modifier les champs désirés
3. Cliquer sur "Sauvegarder"
4. Si checksum/algorithme changé, confirmer dans modal
5. Notification de succès affichée

Supprimer un Document

Comportement Suppression Douce:

• Document marqué comme supprimé (timestamp deleted_at défini)
• Historique signatures préservé
• Document n'apparaît plus dans listes publiques
• Admin peut toujours voir via URL directe
• Signatures CASCADE update (marquées avec doc_deleted_at)

Pour supprimer:

1. Aller sur page détail document (/admin/docs/{docId})
2. Cliquer sur bouton "Supprimer Document"
3. Confirmer suppression dans modal
4. Document déplacé en état supprimé

Note: Il n'y a pas de "restauration" - c'est une suppression douce permanente.

---

Signataires Attendus

Les signataires attendus sont les utilisateurs que vous souhaitez suivre pour la complétion du document.

Ajouter des Signataires Attendus

Depuis la page détail document:

1. Défiler jusqu'à la section "Signataires Attendus"
2. Cliquer sur bouton "Ajouter Signataire Attendu"
3. Entrer adresse(s) email:
   • Simple: alice@company.com
   • Multiple: Séparées par virgules alice@company.com,bob@company.com
4. Optionnellement ajouter des notes
5. Cliquer sur "Ajouter"

Endpoint API:

POST /api/v1/admin/documents/{docId}/signers
Content-Type: application/json
X-CSRF-Token: {token}

{
  "emails": ["alice@company.com", "bob@company.com"],
  "notes": "Membres du conseil - Q1 2025"
}

Contraintes:

• Email doit avoir format valide
• Contrainte UNIQUE: Impossible d'ajouter même email deux fois au même document
• Ajouté par admin utilisateur actuel (suivi dans added_by)

Retirer des Signataires Attendus

Depuis la page détail document:

1. Trouver signataire dans liste Signataires Attendus
2. Cliquer sur bouton "Retirer" à côté de leur email
3. Confirmer le retrait

Endpoint API:

DELETE /api/v1/admin/documents/{docId}/signers/{email}
X-CSRF-Token: {token}

Effet:

• Signataire retiré de la liste attendue
• NE supprime PAS leur signature s'ils ont déjà signé
• Historique des rappels préservé dans reminder_logs

Suivre le Statut de Complétion

API Statut Document:

GET /api/v1/admin/documents/{docId}/status

Réponse:

{
  "docId": "abc123",
  "expectedCount": 10,
  "signedCount": 7,
  "pendingCount": 3,
  "completionPercentage": 70.0
}

Indicateurs visuels:

• Barre de progression montrant pourcentage complétion
• Statut code couleur: Vert (signé), Orange (en attente)
• Jours depuis ajout (aide identifier signataires lents)

---

Rappels Email

Les rappels email sont envoyés de manière asynchrone via le système email_queue.

Envoyer des Rappels

Depuis la page détail document:

1. Cliquer sur bouton "Envoyer Rappels"
2. Modal s'ouvre avec options:
   • Envoyer à: Tous en attente OU emails spécifiques
   • URL Document: Pré-rempli, peut personnaliser
   • Langue: en, fr, es, de, it
3. Cliquer sur "Envoyer Rappels"
4. Confirmation: "X rappels mis en file pour envoi"

Endpoint API:

POST /api/v1/admin/documents/{docId}/reminders
Content-Type: application/json
X-CSRF-Token: {token}

{
  "emails": ["alice@company.com"],  // Optionnel: emails spécifiques
  "docURL": "https://docs.company.com/politique.pdf",
  "locale": "fr"
}

Comportement:

• Envoie à TOUS les signataires en attente si emails non spécifié
• Envoie aux emails spécifiques si fournis (même si déjà signé)
• Emails mis en file dans table email_queue
• Worker background traite la file
• Retry en cas d'échec (3 tentatives, exponential backoff)

Templates Email

Emplacement: backend/templates/emails/

Templates disponibles:

• reminder.html - Version HTML
• reminder.txt - Version texte simple

Variables disponibles dans les templates:

• {{.DocTitle}} - Titre document
• {{.DocURL}} - URL document
• {{.RecipientEmail}} - Email destinataire
• {{.SenderName}} - Admin ayant envoyé rappel
• {{.OrganisationName}} - Depuis ACKIFY_ORGANISATION

Locales: en, fr, es, de, it

• Répertoire template: templates/emails/{locale}/
• Fallback vers locale par défaut si traduction manquante

Historique des Rappels

Voir log des rappels:

GET /api/v1/admin/documents/{docId}/reminders

Réponse:

{
  "reminders": [
    {
      "id": 123,
      "docId": "abc123",
      "recipientEmail": "alice@company.com",
      "sentAt": "2025-01-15T10:30:00Z",
      "sentBy": "admin@company.com",
      "templateUsed": "reminder",
      "status": "sent",
      "errorMessage": null
    }
  ]
}

Valeurs de statut:

• queued - Dans email_queue, pas encore traité
• sent - Livré avec succès
• failed - Échec de livraison (voir errorMessage)
• bounced - Email retourné

Suivi:

• Date dernier rappel envoyé affiché par signataire
• Nombre rappels affiché par signataire
• Aide éviter sur-envoi

Monitoring de la File Email

Vérifier statut de la file (PostgreSQL):

-- Emails en attente
SELECT id, to_addresses, subject, status, scheduled_for
FROM email_queue
WHERE status IN ('pending', 'processing')
ORDER BY priority DESC, scheduled_for ASC;

-- Emails échoués
SELECT id, to_addresses, last_error, retry_count
FROM email_queue
WHERE status = 'failed';

Configuration du worker:

• Taille lot: 10 emails
• Intervalle polling: 5 secondes
• Max retries: 3
• Cleanup: Rétention 7 jours

---

Monitoring & Statistiques

Statistiques Niveau Document

Suivi complétion:

• Nombre Attendus vs Signés
• Liste signataires en attente
• Pourcentage complétion
• Temps moyen pour signer

Efficacité des rappels:

• Nombre rappels envoyés
• Taux succès/échec
• Temps entre rappel et signature

Métriques Système Global

Requêtes PostgreSQL:

-- Total documents
SELECT COUNT(*) FROM documents WHERE deleted_at IS NULL;

-- Total signatures
SELECT COUNT(*) FROM signatures;

-- Documents par statut complétion
SELECT
  CASE
    WHEN signed_count = expected_count THEN '100%'
    WHEN signed_count >= expected_count * 0.75 THEN '75-99%'
    WHEN signed_count >= expected_count * 0.50 THEN '50-74%'
    ELSE '<50%'
  END as completion_bracket,
  COUNT(*) as doc_count
FROM (
  SELECT
    d.doc_id,
    COUNT(DISTINCT es.email) as expected_count,
    COUNT(DISTINCT s.user_email) as signed_count
  FROM documents d
  LEFT JOIN expected_signers es ON d.doc_id = es.doc_id
  LEFT JOIN signatures s ON d.doc_id = s.doc_id AND s.user_email = es.email
  WHERE d.deleted_at IS NULL
  GROUP BY d.doc_id
) stats
GROUP BY completion_bracket;

-- Statistiques file email
SELECT status, COUNT(*), MIN(created_at), MAX(created_at)
FROM email_queue
GROUP BY status;

Exporter les Données

Signatures pour un document:

COPY (
  SELECT s.user_email, s.user_name, s.signed_at, s.payload_hash
  FROM signatures s
  WHERE s.doc_id = 'votre_doc_id'
  ORDER BY s.signed_at
) TO '/tmp/signatures_export.csv' WITH CSV HEADER;

Statut signataires attendus:

COPY (
  SELECT
    es.email,
    CASE WHEN s.id IS NOT NULL THEN 'Signé' ELSE 'En attente' END as status,
    es.added_at,
    s.signed_at
  FROM expected_signers es
  LEFT JOIN signatures s ON es.doc_id = s.doc_id AND es.email = s.user_email
  WHERE es.doc_id = 'votre_doc_id'
) TO '/tmp/expected_signers_export.csv' WITH CSV HEADER;

---

Bonnes Pratiques

1. Création de Documents

✅ À Faire:

• Utiliser titres descriptifs
• Ajouter descriptions claires
• Inclure URL document pour accès facile
• Stocker checksum pour vérification intégrité
• Créer liste signataires attendus avant partage

❌ À Éviter:

• Utiliser titres génériques comme "Document 1"
• Laisser URL vide si document accessible en ligne
• Changer checksums sauf si document réellement changé

2. Gestion Signataires Attendus

✅ À Faire:

• Ajouter signataires attendus avant d'envoyer lien document
• Utiliser notes claires pour expliquer pourquoi signataires attendus
• Réviser signataires en attente régulièrement
• Retirer signataires qui ne sont plus pertinents

❌ À Éviter:

• Ajouter centaines de signataires d'un coup (utiliser lots)
• Envoyer rappels trop fréquemment (max une fois par semaine)
• Retirer signataires ayant déjà signé (préserver historique)

3. Rappels Email

✅ À Faire:

• Attendre 3-5 jours avant premier rappel
• Envoyer dans langue préférée du destinataire
• Inclure titre et URL document clairs
• Suivre historique rappels pour éviter spam
• Envoyer rappels pendant heures bureau

❌ À Éviter:

• Envoyer rappels quotidiens (cause fatigue)
• Envoyer sans vérifier si déjà signé
• Utiliser sujets génériques (personnaliser avec titre doc)
• Envoyer hors heures bureau

4. Intégrité des Données

✅ À Faire:

• Sauvegarder régulièrement base PostgreSQL
• Vérifier checksums correspondent documents réels
• Monitorer file email pour échecs
• Réviser signatures inattendues (peut indiquer intérêt plus large)
• Exporter données signatures importantes

❌ À Éviter:

• Supprimer documents avec signatures actives
• Modifier timestamps manuellement en base
• Ignorer échecs livraison email
• Changer checksums sans mettre à jour document

5. Sécurité

✅ À Faire:

• Limiter accès admin aux utilisateurs de confiance uniquement
• Utiliser HTTPS en production (ACKIFY_BASE_URL=https://...)
• Tourner ACKIFY_OAUTH_COOKIE_SECRET périodiquement
• Monitorer actions admin via logs application
• Utiliser restrictions domaine OAuth autorisé

❌ À Éviter:

• Partager identifiants admin
• Fonctionner sans HTTPS en production
• Désactiver protection CSRF
• Ignorer échecs authentification dans logs

---

Dépannage

Problèmes Courants

1. Lien Admin Non Visible

Problème: Ne peut pas voir lien "Admin" dans navigation

Solutions:

• Vérifier email dans variable ACKIFY_ADMIN_EMAILS
• Redémarrer Ackify: docker compose restart ackify-ce
• Se déconnecter et se reconnecter
• Vérifier logs: docker compose logs ackify-ce | grep admin

2. Emails Non Envoyés

Problème: Rappels mis en file mais pas livrés

Diagnostic:

SELECT * FROM email_queue WHERE status = 'failed' ORDER BY created_at DESC LIMIT 10;

Solutions:

• Vérifier configuration SMTP (ACKIFY_MAIL_HOST, ACKIFY_MAIL_USERNAME, etc.)
• Vérifier identifiants SMTP corrects
• Vérifier logs worker email: docker compose logs ackify-ce | grep email
• S'assurer ACKIFY_MAIL_FROM est adresse expéditeur valide
• Tester connexion SMTP manuellement

3. Erreur Signataire Dupliqué

Problème: "Email existe déjà comme signataire attendu"

Cause: Contrainte UNIQUE sur (doc_id, email)

Solution: Comportement attendu - chaque email ne peut être ajouté qu'une fois par document

4. Checksum Non Correspondant

Problème: Utilisateurs rapportent checksum ne correspond pas

Solutions:

• Vérifier checksum stocké correspond document réel
• Vérifier algorithme utilisé (SHA-256, SHA-512, MD5)
• Recalculer checksum et mettre à jour via Éditer Métadonnées
• S'assurer utilisateurs téléchargent version correcte

5. Document N'apparaît Pas

Problème: Document créé n'apparaît pas dans liste

Solutions:

• Vérifier si document supprimé en douce (deleted_at IS NOT NULL)
• Vérifier création réussie (vérifier réponse/logs)
• Vider cache navigateur
• Vérifier base: SELECT * FROM documents WHERE doc_id = 'votre_id';

6. Signature Déjà Existe

Problème: Utilisateur ne peut pas signer document à nouveau

Cause: Contrainte UNIQUE (doc_id, user_sub) - une signature par utilisateur par document

Solution: Comportement attendu - utilisateurs ne peuvent pas signer même document deux fois

Obtenir de l'Aide

Logs:

# Logs application
docker compose logs -f ackify-ce

# Logs base de données
docker compose logs -f ackify-db

# Logs worker email (grep email)
docker compose logs ackify-ce | grep -i email

Inspection base de données:

# Se connecter à PostgreSQL
docker compose exec ackify-db psql -U ackifyr ackify

# Requêtes utiles
SELECT * FROM documents ORDER BY created_at DESC LIMIT 10;
SELECT * FROM expected_signers WHERE doc_id = 'votre_doc_id';
SELECT * FROM email_queue WHERE status != 'sent' ORDER BY created_at DESC;

Rapporter problèmes:

• GitHub: https://github.com/btouchard/ackify-ce/issues
• Inclure logs et messages erreur
• Décrire comportement attendu vs réel

---

Référence Rapide

Variables Environnement

ACKIFY_ADMIN_EMAILS=admin@company.com
ACKIFY_MAIL_HOST=smtp.gmail.com
ACKIFY_MAIL_FROM=noreply@company.com

Endpoints Clés

GET  /admin                              # Dashboard
GET  /admin/docs/{docId}                 # Détail document
POST /admin/documents/{docId}/signers    # Ajouter signataire
POST /admin/documents/{docId}/reminders  # Envoyer rappels
PUT  /admin/documents/{docId}/metadata   # Mettre à jour métadonnées

Tables Importantes

• documents - Métadonnées documents
• signatures - Signatures utilisateurs
• expected_signers - Qui doit signer
• reminder_logs - Historique emails
• email_queue - File email async

Raccourcis Clavier (Frontend)

• Barre recherche auto-focus sur dashboard
• Entrée pour soumettre formulaires
• Échap pour fermer modales

---

Dernière Mise à Jour: 2025-10-26 Version: 1.0.0