Krow/Krow-workspace
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
92fd0118be5cb43efa1cec899315fcfaae55c0f4
Krow-workspace/docs/api_specification.md
bwnyasse 866d0df45c feat(docs): add MAINTENANCE_GUIDE.md to describe the process of updating the API documentation and specification 
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
2025-11-11 06:57:58 -05:00

238 lines
14 KiB
Markdown
Raw Blame History

# 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://..." }`
Reference in New Issue View Git Blame Copy Permalink