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

# Conventions

> Dates, devises, locales, noms de champs, formats

# Conventions

## Dates et heures

Toutes les dates utilisent **ISO 8601** en UTC.

| Type          | Format                     | Exemple                           |
| ------------- | -------------------------- | --------------------------------- |
| Date          | `YYYY-MM-DD`               | `2026-04-18`                      |
| Date+heure    | `YYYY-MM-DDTHH:mm:ssZ`     | `2026-04-18T14:00:00Z`            |
| Date+heure ms | `YYYY-MM-DDTHH:mm:ss.SSSZ` | `2026-04-18T14:00:00.123Z`        |
| Durée         | ISO 8601 duration          | `PT30M` (30 min), `P7D` (7 jours) |

<Warning>
  L'heure locale Cameroun (WAT) est **UTC+1**. Ne jamais envoyer de date sans suffixe de fuseau.
</Warning>

## Devises

| Code  | Nom            | Usage                  |
| ----- | -------------- | ---------------------- |
| `XAF` | Franc CFA BEAC | Par défaut             |
| `EUR` | Euro           | Offres internationales |
| `USD` | Dollar US      | Rare                   |

Les montants sont **toujours en entier dans l'unité principale** (pas de centimes). Ex. `500000` = 500 000 XAF.

## Téléphones

Format E.164 avec code pays obligatoire.

```
✅ +237690123456
✅ +33612345678
❌ 690123456
❌ 0690123456
```

## Emails

Validation stricte RFC 5322. Longueur max **254 caractères**.

## Noms de champs

* API (JSON) : `camelCase` — `firstName`, `dateExpiration`, `niveauExperience`
* SQL (colonnes) : `snake_case` — `first_name`, `date_expiration`
* SQL (tables) : `snake_case` pluriel — `candidats`, `offres_emploi`
* Enums : `UPPER_SNAKE_CASE` — `CDI`, `PENDING_APPROVAL`, `NEW`

## IDs

* Type : `long` (64 bits)
* Format dans JSON : nombre entier
* Exposés tels quels (pas d'obfuscation ni de slug)

```json theme={null}
{ "id": 42, "titre": "..." }
```

## Pagination

Spring Data standard. Voir [Pagination](/pagination).

```
?page=0&size=20&sort=createdAt,desc
```

* `page` base 0
* `size` max 100 (clampé silencieusement)
* `sort` accepte plusieurs entrées

## Tri

| Champ       | Direction défaut               |
| ----------- | ------------------------------ |
| `createdAt` | `desc`                         |
| `updatedAt` | `desc`                         |
| `titre`     | `asc`                          |
| `nom`       | `asc`                          |
| `relevance` | `desc` (recherche plein-texte) |

## Langues

```mermaid theme={null}
flowchart LR
    REQ[Accept-Language] --> DET{Détecter}
    DET -->|fr| FR[Réponse FR]
    DET -->|en| EN[Réponse EN]
    DET -->|autre| FR
    DET -->|absent| FR
```

Les messages d'erreur et enumérations sont renvoyés selon `Accept-Language` (fr/en). Le français est le défaut.

```http theme={null}
Accept-Language: fr-FR,fr;q=0.9,en;q=0.8
```

## Encodage

* Body : `UTF-8`
* URL : percent-encoding standard
* Multipart : boundary généré par le client

## Codes pays

ISO 3166-1 alpha-2. Cameroun = `CM`.

## Géolocalisation

Format `POINT(lon lat)` pour les coordonnées PostGIS (interne). Exposé en API sous forme :

```json theme={null}
{
  "latitude": 4.0511,
  "longitude": 9.7679
}
```

## Enumérations

Toujours documentées par endpoint. Liste complète : [Énumérations](/enumerations).

## Nullabilité

Champs absents **omis du JSON** (pas `null`). Exception : champs explicitement documentés comme `nullable`.

```json theme={null}
{
  "id": 1,
  "titre": "Offre",
  "description": "..."
  // "dateExpiration" omis si non défini
}
```

## Casse des réponses

* Clés JSON : `camelCase` strict
* Valeurs enum : `UPPER_SNAKE_CASE`
* Chaînes libres : telles qu'enregistrées

## Headers standards

| Header                              | Rôle                                |
| ----------------------------------- | ----------------------------------- |
| `Content-Type: application/json`    | Requête JSON                        |
| `Content-Type: multipart/form-data` | Upload                              |
| `Authorization: Bearer <jwt>`       | Auth                                |
| `Accept-Language: fr`               | Langue                              |
| `X-Request-ID`                      | Trace (optionnel, généré si absent) |
| `If-None-Match`, `ETag`             | Cache HTTP (réponses longues)       |