feat: Initial commit of KROW Workforce Web client (Base44 export)
This commit is contained in:
bwnyasse
254
docs/API_documentation.md
Normal file
254
docs/API_documentation.md
Normal file
@@ -0,0 +1,254 @@
|
||||
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](#introduction)
|
||||
2. [Authentification](#authentication)
|
||||
3. [API des Entités](#entities-api)
|
||||
4. [API des Intégrations](#integrations-api)
|
||||
5. [Meilleures Pratiques](#best-practices)
|
||||
6. [Gestion des Erreurs](#error-handling)
|
||||
7. [Exemples](#examples)
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
```javascript
|
||||
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
|
||||
|
||||
```javascript
|
||||
// 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](https://example.com)
|
||||
* **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.
|
||||
Reference in New Issue
Block a user