feat: Initial commit of KROW Workforce Web client (Base44 export)
This commit is contained in:
bwnyasse
241
docs/api_specification.md
Normal file
241
docs/api_specification.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# 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) :**
|
||||
```json
|
||||
{
|
||||
"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 :**
|
||||
```json
|
||||
{
|
||||
"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 :**
|
||||
```json
|
||||
{
|
||||
"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) :**
|
||||
```json
|
||||
{
|
||||
"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 :**
|
||||
```json
|
||||
{
|
||||
"prompt": "Analyse ce document et extrais les informations suivantes...",
|
||||
"context": "..." // Contexte additionnel
|
||||
}
|
||||
```
|
||||
- **Réponse (200 OK) :**
|
||||
```json
|
||||
{
|
||||
"result": "Texte ou JSON généré par le LLM"
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user