Krow-workspace/docs/api_specification.md

Spécification de l'API KROW Workforce (Migration GCP)

Version : 1.0 Date : 10/11/2025 Objectif : Ce document définit l'API RESTful à construire sur Google Cloud Platform (Cloud Functions, Cloud SQL) pour remplacer le backend Base44. Il est basé sur la documentation fournie par Base44 et une analyse exhaustive de l'utilisation de son SDK dans le code source du frontend.

---

Conventions Générales

• URL de base : /api/v1
• Authentification : Chaque requête (sauf POST /login et GET /health) doit inclure un header Authorization: Bearer <Firebase-Auth-Token>.
• Format des données : Toutes les requêtes et réponses seront au format application/json.
• Réponses d'erreur : Les erreurs utiliseront les codes de statut HTTP standards (400, 401, 403, 404, 500) et incluront un corps de réponse JSON de la forme { "error": "Description du problème" }.
• Champs Communs : Chaque entité aura les champs suivants, gérés automatiquement par le backend :
  • id: string (UUID, Clé primaire)
  • created_date: string (ISO 8601 Timestamp)
  • updated_date: string (ISO 8601 Timestamp)
  • created_by: string (Email de l'utilisateur créateur)

---

1. Authentification (/auth)

Basé sur Firebase Authentication. Le frontend gère l'inscription et la connexion avec le SDK Firebase. Notre backend a besoin d'un endpoint pour récupérer les informations étendues de l'utilisateur.

Entité User

Champ	Type	Description
id	string	ID Firebase de l'utilisateur
email	string	Email de l'utilisateur (non modifiable)
full_name	string	Nom complet
user_role	string	Rôle (admin, procurement, client...)
company_name	string	Nom de l'entreprise associée
profile_picture	string	URL de l'image de profil

Endpoints

GET /auth/me

• Description : Récupère les informations du profil de l'utilisateur actuellement authentifié.
• Utilisation observée : base44.auth.me() (utilisé dans presque toutes les pages).
• Réponse (200 OK) :

  {
    "id": "firebase-user-id-123",
    "email": "dev@example.com",
    "full_name": "Dev User",
    "user_role": "admin",
    "company_name": "KROW Corp",
    "profile_picture": "https://..."
  }
  

PUT /auth/me

• Description : Met à jour le profil de l'utilisateur actuel.
• Utilisation observée : base44.auth.updateMe(data) (dans WorkforceProfile.jsx, RoleSwitcher.jsx).
• Corps de la requête :

  {
    "full_name": "John Doe",
    "profile_picture": "https://..."
  }
  

• Réponse (200 OK) : L'objet User mis à jour.

---

2. Entités (CRUD)

2.1. Event

Description : Gère les commandes de main-d'œuvre.

Schéma Event

Champ	Type	Description
event_name	string	Nom de l'événement/commande
order_type	string	Enum: rapid, one_time, recurring, permanent
business_id	string	ID de l'entité Business (client)
vendor_id	string	ID de l'entité Vendor (fournisseur)
status	string	Enum: Draft, Active, Pending, Assigned, Confirmed, Completed, Canceled
shifts	array	Tableau d'objets Shift (défini comme une sous-entité ou un type JSON)
date	string	ISO 8601 Timestamp, date de début de l'événement

Endpoints

• POST /events

  • SDK : base44.entities.Event.create(eventData)
  • Utilisation : CreateEvent.jsx, QuickReorderModal.jsx
  • Body : Objet Event sans les champs communs.
  • Réponse : Le nouvel objet Event créé.

• GET /events

  • SDK : base44.entities.Event.list(sort, limit) et .filter(query, sort, limit)
  • Utilisation : Events.jsx, Dashboard.jsx, WorkforceShifts.jsx, etc.
  • Paramètres de requête :
    • sort (ex: -date pour trier par date décroissante)
    • limit (ex: 50)
    • Autres champs de l'entité pour le filtrage (ex: status=Active)
  • Réponse : Tableau d'objets Event.

• PUT /events/{id}

  • SDK : base44.entities.Event.update(id, data)
  • Utilisation : EditEvent.jsx, QuickAssignPopover.jsx
  • Body : Un objet avec les champs de Event à mettre à jour.
  • Réponse : L'objet Event mis à jour.

2.2. Staff

Description : Gère les membres du personnel.

Schéma Staff

Champ	Type	Description
employee_name	string	Requis. Nom de l'employé.
vendor_id	string	Fournisseur auquel l'employé est rattaché.
rating	number	Note de 0 à 5.
shift_coverage_percentage	number	Pourcentage de shifts couverts.
background_check_status	string	Enum: pending, cleared, failed, expired

Endpoints

• POST /staff

  • SDK : base44.entities.Staff.create(staffData)
  • Utilisation : AddStaff.jsx
  • Body : Objet Staff sans les champs communs.
  • Réponse : Le nouvel objet Staff créé.

• GET /staff

  • SDK : base44.entities.Staff.list(sort, limit)
  • Utilisation : StaffDirectory.jsx, Dashboard.jsx, Reports.jsx, etc.
  • Paramètres de requête : sort, limit, et autres champs pour le filtrage.
  • Réponse : Tableau d'objets Staff.

• PUT /staff/{id}

  • SDK : base44.entities.Staff.update(id, data)
  • Utilisation : EditStaff.jsx
  • Body : Un objet avec les champs de Staff à mettre à jour.
  • Réponse : L'objet Staff mis à jour.

2.3. Vendor

Description : Gère les fournisseurs de services.

Schéma Vendor

Champ	Type	Description
vendor_number	string	Format: VN-####
legal_name	string	Requis. Nom légal.
approval_status	string	Enum: pending, approved, suspended, terminated
is_active	boolean	Statut d'activité.

Endpoints

• POST /vendors

  • SDK : base44.entities.Vendor.create(data)
  • Utilisation : VendorOnboarding.jsx, SmartVendorOnboarding.jsx
  • Body : Objet Vendor.
  • Réponse : Le nouvel objet Vendor créé.

• GET /vendors

  • SDK : base44.entities.Vendor.list() et .filter()
  • Utilisation : VendorManagement.jsx
  • Paramètres de requête : sort, limit, approval_status, etc.
  • Réponse : Tableau d'objets Vendor.

• PUT /vendors/{id}

  • SDK : base44.entities.Vendor.update(id, data)
  • Utilisation : EditVendor.jsx, VendorManagement.jsx
  • Body : Champs de Vendor à mettre à jour.
  • Réponse : L'objet Vendor mis à jour.

---

2.4. Autres Entités Majeures (Structure Similaire)

La même structure d'endpoints (POST, GET, PUT) doit être créée pour les entités suivantes, en se basant sur les schémas à obtenir et l'utilisation observée dans le code :

• VendorRate: Gère les tarifs des fournisseurs.
• Business: Gère les clients.
• Invoice: Gère les factures.
• Team, TeamMember, TeamMemberInvite: Gère les équipes et les invitations.
• ActivityLog: Gère les notifications et les journaux d'activité.
• Certification: Gère les certifications du personnel.
• Enterprise, Sector, Partner: Gèrent la hiérarchie organisationnelle.
• Conversation, Message: Gèrent la messagerie interne.
• ... et toutes les autres entités listées dans api/entities.js.

---

3. Services d'Intégration

Ces endpoints ne sont pas des CRUDs mais des appels à des services spécifiques.

POST /integrations/send-email

• Description : Envoie un email.
• SDK : base44.integrations.Core.SendEmail(params)
• Utilisation : InviteVendor.jsx, TeamDetails.jsx, etc.
• Body :

  {
    "to": "recipient@example.com",
    "subject": "Sujet de l'email",
    "body": "<h1>Contenu HTML</h1>"
  }
  

• Réponse (200 OK) : { "status": "sent" }

POST /integrations/upload-file

• Description : Gère le téléversement de fichiers vers Google Cloud Storage.
• SDK : base44.integrations.Core.UploadFile({ file })
• Utilisation : WorkforceProfile.jsx, VendorOnboarding.jsx, etc.
• Requête : Doit être une requête multipart/form-data.
• Réponse (200 OK) :

  {
    "file_url": "https://storage.googleapis.com/..."
  }
  

POST /integrations/invoke-llm

• Description : Fait appel à un modèle de langage (Vertex AI).
• SDK : base44.integrations.Core.InvokeLLM({ prompt })
• Utilisation : SmartVendorOnboarding.jsx, VendorCompliance.jsx
• Body :

  {
    "prompt": "Analyse ce document et extrais les informations suivantes...",
    "context": "..." // Contexte additionnel
  }
  

• Réponse (200 OK) :

  {
    "result": "Texte ou JSON généré par le LLM"
  }