> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wethehivers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Modèle Vivier

> Bases de données candidats du recruteur

# Vivier

Un **vivier** est une liste de candidats constituée par un recruteur. Le vivier peut contenir des candidats **inscrits sur la plateforme** ou des candidats **externes** (importés depuis LinkedIn, CV reçus hors plateforme, etc.).

## Schéma

```mermaid theme={null}
classDiagram
    class Vivier {
        +Long id
        +Long recruteurId
        +String nom
        +String description
        +String[] tags
        +Boolean partageEntreprise
        +Instant createdAt
    }

    class VivierCandidat {
        +Long id
        +Long vivierId
        +Long candidatId "null si externe"
        +Long externalCandidatId "null si inscrit"
        +String note
        +String statut "NOUVEAU|CONTACTE|INVITE|INSCRIT|HORS_CIBLE"
        +Instant addedAt
    }

    class ExternalCandidat {
        +Long id
        +String firstName
        +String lastName
        +String email
        +String phone
        +String[] competences
        +String source "LINKEDIN|MANUAL|IMPORT_CSV"
        +Long addedBy
    }

    class Candidat {
        +Long id
        +String firstName
    }

    Vivier "1" --> "0..*" VivierCandidat
    VivierCandidat "N" --> "0..1" Candidat
    VivierCandidat "N" --> "0..1" ExternalCandidat
```

## Exemple JSON

```json theme={null}
{
  "id": 55,
  "nom": "Senior Java — pipeline 2026",
  "description": "Candidats identifiés pour futures ouvertures backend",
  "tags": ["Java", "Senior", "Backend"],
  "partageEntreprise": true,
  "totalCandidats": 24,
  "repartition": { "inscrits": 15, "externes": 9 },
  "candidats": [
    {
      "id": 701,
      "type": "INSCRIT",
      "candidat": { "id": 42, "firstName": "Jean", "niveauExperience": "SENIOR" },
      "statut": "CONTACTE",
      "note": "Contacté le 10/04, en cours d'échange"
    },
    {
      "id": 702,
      "type": "EXTERNE",
      "external": { "firstName": "Alain", "source": "LINKEDIN" },
      "statut": "INVITE",
      "note": "Invité à s'inscrire 05/04"
    }
  ]
}
```

## Flow d'ajout

```mermaid theme={null}
flowchart TD
    R[Recruteur] --> CH{Type candidat}
    CH -->|Inscrit plateforme| SEARCH[Recherche profils publics]
    SEARCH --> ADD1[POST /vivier/{id}/candidats\n {candidatId}]

    CH -->|Externe manuel| FORM[Formulaire manuel\n nom, email, compétences]
    FORM --> ADD2[POST /vivier/{id}/candidats/external]

    CH -->|Import CSV| CSV[Upload CSV]
    CSV --> PARSE[Parse + dédup par email]
    PARSE --> ADD3[INSERT bulk]

    ADD1 --> DB[vivier_candidats]
    ADD2 --> DB
    ADD3 --> DB
```

## Cycle d'un candidat dans le vivier

```mermaid theme={null}
stateDiagram-v2
    [*] --> NOUVEAU
    NOUVEAU --> CONTACTE: recruteur envoie message
    CONTACTE --> INVITE: invitation plateforme envoyée
    INVITE --> INSCRIT: candidat externe → s'inscrit
    INSCRIT --> [*]
    NOUVEAU --> HORS_CIBLE: disqualifié
    CONTACTE --> HORS_CIBLE
    INVITE --> HORS_CIBLE
```

## Invitation à s'inscrire (external → inscrit)

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant R as Recruteur
    participant API as Backend
    participant M as Mail
    participant C as Candidat externe

    R->>API: POST /vivier/55/candidats/702/invite
    API->>API: Générer token invitation (24h)
    API->>M: Envoi "Inscrivez-vous sur THE HIVE"\n + lien avec token
    M->>C: Email
    C->>API: POST /auth/register?invitationToken=...
    API->>API: Créer Candidat + lier à VivierCandidat.externalCandidatId
    API->>API: UPDATE vivier_candidats.candidatId = newId
    API->>R: Notification "Alain s'est inscrit"
```

## Partage intra-entreprise

```mermaid theme={null}
flowchart LR
    OWN[OWNER crée vivier] --> CH{partageEntreprise?}
    CH -->|oui| SHARE[Tous les MEMBER voient + ajoutent]
    CH -->|non| PRIV[Seul créateur voit]
```

## Endpoints principaux

| Méthode  | Path                                       | Description           |
| -------- | ------------------------------------------ | --------------------- |
| `POST`   | `/v1/api/vivier`                           | Créer vivier          |
| `GET`    | `/v1/api/vivier`                           | Mes viviers           |
| `GET`    | `/v1/api/vivier/{id}`                      | Détail + candidats    |
| `POST`   | `/v1/api/vivier/{id}/candidats`            | Ajouter inscrit       |
| `POST`   | `/v1/api/vivier/{id}/candidats/external`   | Ajouter externe       |
| `POST`   | `/v1/api/vivier/{id}/candidats/import-csv` | Import CSV            |
| `PATCH`  | `/v1/api/vivier/candidats/{id}`            | Changer statut / note |
| `POST`   | `/v1/api/vivier/candidats/{id}/invite`     | Invitation plateforme |
| `DELETE` | `/v1/api/vivier/candidats/{id}`            | Retirer               |

## Quota

| Plan       | Viviers max | Candidats par vivier |
| ---------- | :---------: | :------------------: |
| Gratuit    |      1      |          50          |
| Essentiel  |      5      |          500         |
| Pro        |      20     |         5000         |
| Entreprise |      ∞      |           ∞          |