Krow/Krow-workspace
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(docs): add MAINTENANCE_GUIDE.md to describe the process of updating the API documentation and specification

Browse Source 
feat(docs): update API_documentation.md with comprehensive API specifications for all entities, SDK methods, and integration endpoints
feat(docs): update api_specification.md to align with the updated API documentation and guide the development of the new backend
This commit is contained in:
bwnyasse
2025-11-11 06:57:58 -05:00
parent e571193362
commit 866d0df45c
4 changed files with 1929 additions and 344 deletions
Download Patch File Download Diff File Expand all files Collapse all files

325
docs/api_specification.md
View File

@@ -1,8 +1,8 @@
# 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.
**Version :** 2.0
**Date :** 11/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 exhaustive de l'API Base44 (v2.0) et a pour but de guider le développement du nouveau backend.
---
@@ -24,218 +24,215 @@
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`
### Entité `User` (Basée sur `base44.auth.me`)
| 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 |
| `user_role` | `string` | Rôle personnalisé dans l'application (`admin`, `procurement`, `client`...) |
| `...autres` | `any` | D'autres champs personnalisés peuvent être ajoutés. |
### 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://..."
}
```
- **SDK d'origine :** `base44.auth.me()`
- **Réponse (200 OK) :** L'objet `User` complet.
#### `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://..."
}
```
- **SDK d'origine :** `base44.auth.updateMe(data)`
- **Corps de la requête :** Un objet avec les champs de `User` à mettre à jour.
- **Réponse (200 OK) :** L'objet `User` mis à jour.
---
## 2. Entités (CRUD)
## 2. Entités (Endpoints CRUD)
### 2.1. Event
Pour chaque entité ci-dessous, les endpoints standards suivants sont à implémenter.
**Description :** Gère les commandes de main-d'œuvre.
- `POST /{nom-entite}`: Crée une nouvelle entrée.
- `GET /{nom-entite}`: Liste les entrées, avec support pour le filtrage et le tri via des query params.
- `GET /{nom-entite}/{id}`: Récupère une entrée par son ID.
- `PUT /{nom-entite}/{id}`: Met à jour une entrée par son ID.
- `DELETE /{nom-entite}/{id}`: Supprime une entrée par son ID.
#### Schéma `Event`
### 2.1. Event (`/events`)
| 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 |
**Description :** Gère les événements et les commandes de main-d'œuvre.
#### Endpoints
| Champ | Type | Description |
| ----------------------- | --------- | ------------------------------------------------ |
| `event_name` | `string` | Nom de l'événement (requis) |
| `is_recurring` | `boolean` | Indique si l'événement est récurrent |
| `recurrence_type` | `string` | `single`, `date_range`, `scatter` |
| `recurrence_start_date` | `string` | Date de début de récurrence (ISO 8601) |
| `recurrence_end_date` | `string` | Date de fin de récurrence (ISO 8601) |
| `scatter_dates` | `array` | Tableau de dates (ISO 8601) pour `scatter` |
| `business_id` | `string` | ID du client (`Business`) |
| `business_name` | `string` | Nom du client |
| `vendor_id` | `string` | ID du fournisseur (`Vendor`) |
| `vendor_name` | `string` | Nom du fournisseur |
| `hub` | `string` | Lieu/hub |
| `contract_type` | `string` | `W2`, `1099`, `Temp`, `Contract` |
| `po_reference` | `string` | Référence de bon de commande |
| `status` | `string` | `Draft`, `Active`, `Pending`, `Assigned`, `Confirmed`, `Completed`, `Canceled` |
| `date` | `string` | Date de l'événement (ISO 8601) |
| `shifts` | `array` | Tableau d'objets `Shift` |
| `addons` | `object` | Services additionnels |
| `total` | `number` | Coût total |
| `client_name` | `string` | Nom du contact client |
| `client_email` | `string` | Email du contact client |
| `client_phone` | `string` | Téléphone du contact client |
| `notes` | `string` | Notes additionnelles |
| `requested` | `number` | Nombre total de personnel demandé |
| `assigned_staff` | `array` | Tableau d'objets de personnel assigné |
- **`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
### 2.2. Staff (`/staff`)
**Description :** Gère les membres du personnel.
#### Schéma `Staff`
| Champ | Type | Description |
| ------------------------- | --------- | ----------------------------------------- |
| `employee_name` | `string` | Nom complet (requis) |
| `vendor_id` | `string` | ID du fournisseur (`Vendor`) |
| `vendor_name` | `string` | Nom du fournisseur |
| `manager` | `string` | Nom du manager |
| `contact_number` | `string` | Numéro de contact principal |
| `phone` | `string` | Autre téléphone |
| `email` | `string` | Adresse email |
| `department` | `string` | `Operations`, `Sales`, `HR`, etc. |
| `hub_location` | `string` | Lieu/hub de rattachement |
| `address` | `string` | Adresse de l'employé |
| `city` | `string` | Ville |
| `position` | `string` | Poste/compétence principal(e) |
| `position_2` | `string` | Poste/compétence secondaire |
| `profile_type` | `string` | `Skilled`, `Beginner`, `Cross-Trained` |
| `employment_type` | `string` | `Full Time`, `Part Time`, `On call`, etc. |
| `english` | `string` | `Fluent`, `Intermediate`, `Basic`, `None` |
| `rating` | `number` | Note de performance (0-5) |
| `shift_coverage_percentage`| `number` | Pourcentage de shifts couverts (0-100) |
| `cancellation_count` | `number` | Nombre d'annulations |
| `no_show_count` | `number` | Nombre de non-présentations |
| `total_shifts` | `number` | Nombre total de shifts assignés |
| `reliability_score` | `number` | Score de fiabilité (0-100) |
| `background_check_status` | `string` | `pending`, `cleared`, `failed`, `expired` |
| `background_check_date` | `string` | Date du dernier contrôle (ISO 8601) |
| `certifications` | `array` | Liste des certifications |
| 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` |
### 2.3. Vendor (`/vendors`)
#### Endpoints
**Description :** Gère les fournisseurs et leur onboarding.
- **`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éé.
| Champ | Type | Description |
| ----------------------- | --------- | ----------------------------------------- |
| `vendor_number` | `string` | Numéro de fournisseur (ex: `VN-####`) |
| `legal_name` | `string` | Nom légal de l'entreprise (requis) |
| `doing_business_as` | `string` | Nom commercial (DBA) |
| `region` | `string` | `National`, `Bay Area`, etc. |
| `primary_contact_email` | `string` | Email du contact principal (requis) |
| `approval_status` | `string` | `pending`, `approved`, `suspended`, `terminated` |
| `is_active` | `boolean` | Statut d'activité |
| `tax_id` | `string` | Numéro d'identification fiscale (EIN) |
| `business_type` | `string` | `Corporation`, `LLC`, etc. |
| `insurance_certificate` | `string` | URL du certificat d'assurance |
| `insurance_expiry` | `string` | Date d'expiration de l'assurance (ISO 8601) |
| `w9_document` | `string` | URL du document W9 |
| `coi_document` | `string` | URL du document COI |
- **`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`.
### 2.4. VendorRate (`/vendor-rates`)
- **`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.
**Description :** Gère les grilles tarifaires des fournisseurs.
### 2.3. Vendor
| Champ | Type | Description |
| ----------------- | --------- | ----------------------------------------- |
| `vendor_id` | `string` | ID du fournisseur (`Vendor`) |
| `vendor_name` | `string` | Nom du fournisseur (requis) |
| `category` | `string` | Catégorie de service (`Kitchen`, etc.) |
| `role_name` | `string` | Nom du poste (requis) |
| `employee_wage` | `number` | Salaire horaire de l'employé (requis) |
| `client_rate` | `number` | Tarif horaire facturé au client (requis) |
| `pricing_status` | `string` | `optimal`, `underpriced`, `overpriced` |
| `is_active` | `boolean` | Statut d'activité |
**Description :** Gère les fournisseurs de services.
### 2.5. Invoice (`/invoices`)
#### Schéma `Vendor`
**Description :** Gère les factures.
| 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é. |
| Champ | Type | Description |
| ---------------- | -------- | ----------------------------------------- |
| `invoice_number` | `string` | Numéro de facture (requis) |
| `event_id` | `string` | ID de l'événement (`Event`) |
| `business_name` | `string` | Nom du client (requis) |
| `vendor_name` | `string` | Nom du fournisseur |
| `amount` | `number` | Montant de la facture (requis) |
| `status` | `string` | `Open`, `Paid`, `Overdue`, `Disputed`, etc. |
| `issue_date` | `string` | Date d'émission (ISO 8601, requis) |
| `due_date` | `string` | Date d'échéance (ISO 8601, requis) |
| `paid_date` | `string` | Date de paiement (ISO 8601) |
#### Endpoints
### 2.6. Business (`/businesses`)
- **`POST /vendors`**
- **SDK :** `base44.entities.Vendor.create(data)`
- **Utilisation :** `VendorOnboarding.jsx`, `SmartVendorOnboarding.jsx`
- **Body :** Objet `Vendor`.
- **Réponse :** Le nouvel objet `Vendor` créé.
**Description :** Gère les entreprises clientes.
- **`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.
| Champ | Type | Description |
| -------------- | -------- | ----------------------------------------- |
| `business_name`| `string` | Nom de l'entreprise (requis) |
| `contact_name` | `string` | Nom du contact principal (requis) |
| `email` | `string` | Email de l'entreprise |
| `phone` | `string` | Téléphone de l'entreprise |
| `sector` | `string` | `Bon Appétit`, `Eurest`, etc. |
| `rate_group` | `string` | `Standard`, `Premium`, etc. (requis) |
| `status` | `string` | `Active`, `Inactive`, `Pending` |
---
### 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`.
*Note : Pour la concision, seules les entités les plus critiques ont été entièrement détaillées. La même structure (Schéma + Endpoints) doit être appliquée pour : `Certification`, `Team`, `Conversation`, `Message`, `ActivityLog`, `Enterprise`, `Sector`, `Partner`, `Order`, et `Shift` en se basant sur `API_documentation.md`.*
---
## 3. Services d'Intégration
Ces endpoints ne sont pas des CRUDs mais des appels à des services spécifiques.
### `POST /integrations/invoke-llm`
- **Description :** Fait appel à un modèle de langage (Vertex AI).
- **SDK d'origine :** `base44.integrations.Core.InvokeLLM(params)`
- **Body :** `{ "prompt": "...", "response_json_schema": {...}, "file_urls": [...] }`
- **Réponse (200 OK) :** `{ "result": "..." }`
### `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>"
}
```
- **SDK d'origine :** `base44.integrations.Core.SendEmail(params)`
- **Body :** `{ "to": "...", "subject": "...", "body": "..." }`
- **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/..."
}
```
- **Description :** Gère le téléversement de fichiers publics vers Google Cloud Storage.
- **SDK d'origine :** `base44.integrations.Core.UploadFile({ file })`
- **Requête :** `multipart/form-data`.
- **Réponse (200 OK) :** `{ "file_url": "https://..." }`
### `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"
}
```
### `POST /integrations/upload-private-file`
- **Description :** Gère le téléversement de fichiers privés vers Google Cloud Storage.
- **SDK d'origine :** `base44.integrations.Core.UploadPrivateFile({ file })`
- **Requête :** `multipart/form-data`.
- **Réponse (200 OK) :** `{ "file_uri": "gs://..." }`
### `POST /integrations/create-signed-url`
- **Description :** Crée une URL d'accès temporaire pour un fichier privé.
- **SDK d'origine :** `base44.integrations.Core.CreateFileSignedUrl(params)`
- **Body :** `{ "file_uri": "...", "expires_in": 3600 }`
- **Réponse (200 OK) :** `{ "signed_url": "https://..." }`
### `POST /integrations/extract-data`
- **Description :** Extrait des données structurées d'un fichier (CSV, PDF...).
- **SDK d'origine :** `base44.integrations.Core.ExtractDataFromUploadedFile(params)`
- **Body :** `{ "file_url": "...", "json_schema": {...} }`
- **Réponse (200 OK) :** `{ "status": "success", "output": [...] }`
### `POST /integrations/generate-image`
- **Description :** Génère une image via une IA.
- **SDK d'origine :** `base44.integrations.Core.GenerateImage(params)`
- **Body :** `{ "prompt": "..." }`
- **Réponse (200 OK) :** `{ "url": "https://..." }`