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

**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.

---

## 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` (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 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é.
-   **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.
-   **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 (Endpoints CRUD)

Pour chaque entité ci-dessous, les endpoints standards suivants sont à implémenter.

-   `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.

### 2.1. Event (`/events`)

**Description :** Gère les événements et les commandes de main-d'œuvre.

| 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é            |

### 2.2. Staff (`/staff`)

**Description :** Gère les membres du personnel.

| 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                  |

### 2.3. Vendor (`/vendors`)

**Description :** Gère les fournisseurs et leur onboarding.

| 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                       |

### 2.4. VendorRate (`/vendor-rates`)

**Description :** Gère les grilles tarifaires des fournisseurs.

| 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é                         |

### 2.5. Invoice (`/invoices`)

**Description :** Gère les factures.

| 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)               |

### 2.6. Business (`/businesses`)

**Description :** Gère les entreprises clientes.

| 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`           |

---

*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

### `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 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 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/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://..." }`