Krow-workspace/docs/API_documentation.md

Voici le contenu reformaté en Markdown pour une meilleure lisibilité :

KROW Workforce Control Tower - Documentation de l'API

Version : 1.0.0 Dernière mise à jour : Décembre 2024 URL de base : base44.entities et base44.integrations

---

Table des matières

1. Introduction
2. Authentification
3. API des Entités
4. API des Intégrations
5. Meilleures Pratiques
6. Gestion des Erreurs
7. Exemples

---

Introduction

L'API KROW Workforce Control Tower fournit une plateforme complète pour la gestion des opérations de la main-d'œuvre, des événements, des fournisseurs, de la conformité, et plus encore. Construite sur la plateforme Base44, elle offre :

• Architecture multi-locataire supportant les entreprises, les secteurs, les partenaires, les fournisseurs et la main-d'œuvre.
• Gestion des données en temps réel avec l'intégration de React Query.
• Contrôle d'accès basé sur les rôles (Admin, Achats, Opérateur, Secteur, Client, Fournisseur, Main-d'œuvre).
• Suivi de la conformité et gestion des certifications.
• Gestion des événements et des commandes avec des modèles récurrents.
• Optimisation des cartes de tarifs et de la tarification.

---

Authentification

Utilisateur Actuel

import { base44 } from '@/api/base44Client';

// Obtenir l'utilisateur actuellement authentifié
const user = await base44.auth.me();
// Retourne : { id, email, full_name, role, user_role, company_name, ... }

// Vérifier si l'utilisateur est authentifié
const isAuthenticated = await base44.auth.isAuthenticated();
// Retourne : boolean

// Mettre à jour le profil de l'utilisateur actuel
await base44.auth.updateMe({
  full_name: "John Doe",
  phone: "(555) 123-4567"
  // Note : Impossible de remplacer les champs intégrés (id, email, role)
});

// Déconnexion
base44.auth.logout(); // Recharge la page
base44.auth.logout('/login'); // Redirige vers une URL spécifique

// Rediriger vers la page de connexion
base44.auth.redirectToLogin(); // Page actuelle comme nextUrl
base44.auth.redirectToLogin('/dashboard'); // nextUrl personnalisé

Rôles des Utilisateurs

• admin - Administrateur de la plateforme avec un accès complet.
• procurement - Gère les fournisseurs, les partenaires et la conformité.
• operator - Supervise plusieurs secteurs.
• sector - Gère une branche/localisation spécifique.
• client - Demande des services de main-d'œuvre.
• vendor - Fournit des services de main-d'œuvre.
• workforce - Membres individuels du personnel.

---

API des Entités

Toutes les entités suivent le même modèle CRUD avec des champs intégrés :

• id (string, généré automatiquement)
• created_date (timestamp ISO 8601)
• updated_date (timestamp ISO 8601)
• created_by (email du créateur)

Opérations Générales sur les Entités

// Lister tous les enregistrements
const records = await base44.entities.EntityName.list();

// Lister avec tri (préfixer avec - pour un tri descendant)
const sorted = await base44.entities.EntityName.list('-created_date', 50);

// Filtrer les enregistrements
const filtered = await base44.entities.EntityName.filter({
  status: 'Active',
  created_by: user.email
}, '-updated_date', 10);

// Créer un enregistrement
const newRecord = await base44.entities.EntityName.create({
  field1: "value1",
  field2: "value2"
});

// Création en masse
const records = await base44.entities.EntityName.bulkCreate([
  { field1: "value1" },
  { field1: "value2" }
]);

// Mettre à jour un enregistrement
await base44.entities.EntityName.update(recordId, {
  field1: "updated_value"
});

// Supprimer un enregistrement
await base44.entities.EntityName.delete(recordId);

// Obtenir le schéma de l'entité
const schema = await base44.entities.EntityName.schema();
// Retourne le schéma JSON sans les champs intégrés

Référence des Entités

1. Event (Gestion des Commandes)

Objectif : Gérer les commandes de main-d'œuvre avec prise en charge des commandes ponctuelles, récurrentes, rapides et permanentes.

Champs Clés :

• event_name (string, optionnel)
• order_type (enum: rapid, one_time, recurring, permanent)
• business_id / business_name (référence client)
• vendor_id / vendor_name (référence fournisseur)
• status (enum: Draft, Active, Pending, Assigned, Confirmed, Completed, Canceled)
• shifts (tableau d'objets de quarts de travail avec des rôles)

2. Staff (Gestion de la Main-d'œuvre)

Objectif : Gérer les membres individuels du personnel avec suivi des performances et de la conformité.

Champs Clés :

• employee_name (string, requis)
• vendor_id / vendor_name (fournisseur propriétaire)
• rating (nombre, 0-5 étoiles)
• shift_coverage_percentage (nombre, 0-100)
• background_check_status (enum: pending, cleared, failed, expired)

3. Vendor

Objectif : Gérer les partenaires fournisseurs de services de main-d'œuvre.

Champs Clés :

• vendor_number (string, format: VN-####)
• legal_name (string, requis)
• approval_status (enum: pending, approved, suspended, terminated)
• is_active (boolean)

4. VendorRate

Objectif : Définir la tarification des services des fournisseurs avec suivi de la conformité.

Champs Clés :

• vendor_id / vendor_name (référence fournisseur)
• role_name (string, nom du poste)
• employee_wage (nombre)
• client_rate (nombre, taux horaire final)
• pricing_status (enum: optimal, underpriced, overpriced, competitive)

... et ainsi de suite pour les autres entités (Business, Certification, Enterprise, Sector, Partner, Order, Invoice, Team, ActivityLog).

---

API des Intégrations

Intégrations Principales

Toutes les intégrations sont accessibles via base44.integrations.Core.* :

1. InvokeLLM : Générer des réponses IA avec un contexte web optionnel et une sortie JSON.
2. SendEmail : Envoyer des e-mails aux utilisateurs.
3. UploadFile : Télécharger des fichiers sur un stockage public.
4. GenerateImage : Génération d'images par IA.
5. ExtractDataFromUploadedFile : Extraire des données structurées de documents.
6. Gestion de Fichiers Privés : Pour un stockage de fichiers sécurisé.

---

Meilleures Pratiques

1. Utiliser React Query pour la récupération de données : Pour la mise en cache, la refraîchissement en arrière-plan et la gestion de l'état du serveur.
2. Gérer le formatage des dates en toute sécurité : Éviter les erreurs avec des dates non valides.
3. Filtrer par rôle d'utilisateur : Appliquer une logique de filtrage côté client en fonction du rôle de l'utilisateur.
4. Opérations par lots : Utiliser bulkCreate au lieu de plusieurs appels create.
5. Gestion des erreurs avec des Toasts : Fournir un retour d'information clair à l'utilisateur en cas de succès ou d'échec.

---

Gestion des Erreurs

Modèles d'Erreurs Courants

• Entité non trouvée : Gérer les cas où un filter ne retourne aucun résultat.
• Erreurs de validation : Capturer et afficher les erreurs de validation du backend (par exemple, salaire inférieur au minimum).
• Erreurs d'authentification : Rediriger vers la page de connexion lorsque la session de l'utilisateur a expiré.

---

Exemples

Flux de Commande Complet

1. Créer un événement en utilisant base44.entities.Event.create.
2. Assigner du personnel en filtrant le personnel disponible et en mettant à jour l'événement.
3. Envoyer des notifications aux membres du personnel assignés via ActivityLog et SendEmail.
4. Créer une facture pour l'événement complété.

Surveillance de la Conformité

• Surveiller les certifications expirant bientôt et notifier les employés.
• Vérifier la conformité des salaires par rapport au salaire minimum.

Tableau de Bord Analytique

• Calculer des statistiques sur les événements (total, actifs, revenus).
• Identifier les meilleurs performers parmi le personnel en fonction de l'évaluation et de la couverture des quarts.
• Suivre la performance des fournisseurs actifs et approuvés.

---

Limites de Taux & Performance

• Pas de limites de taux explicites sur la plateforme Base44.
• Utiliser la pagination pour les grands ensembles de données.
• Privilégier les opérations par lots.
• Utiliser le filtrage côté serveur (filter()) au lieu de la récupération complète.

---

Support & Ressources

• Documentation de la plateforme : Documentation Base44
• Signalement de problèmes : Utiliser le bouton de feedback dans l'application.
• Demandes de fonctionnalités : Contacter l'équipe Base44.
• Support d'urgence : [Informations de contact]

---

Journal des Modifications

Version 1.0.0 (Décembre 2024)

• Documentation initiale de l'API.
• Documentation de toutes les entités principales.
• Documentation des points de terminaison d'intégration.
• Ajout d'exemples et de meilleures pratiques.