add doc api

Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>

docs/README.md

@@ -4,6 +4,7 @@
 
 - [how to dev](./dev.md)
 - [how to release](./release.md)
+- [API reference](./api.md)
 
 ## Release list
 - [v0.1.0 Cachalot](./docs/release/v0.1.0_cachalot.md)

docs/api.md

@@ -0,0 +1,247 @@
+# API Reference
+
+Base URL : `http://localhost:8080`
+
+Toutes les réponses sont en `application/json`. Les erreurs retournent `{"error": "message"}`.
+
+---
+
+## Health
+
+### `GET /health`
+
+Vérifie la disponibilité du serveur et de la base de données.
+
+**Réponse `200`**
+```json
+{ "status": "ok" }
+```
+
+**Réponse `503`** — base indisponible
+
+---
+
+## Instruments
+
+Un instrument représente tout actif coté : devise (EUR), action, ETF, crypto.
+Le prix EUR vaut toujours 1 et est inséré automatiquement au démarrage.
+
+### `GET /instruments`
+
+Liste tous les instruments.
+
+**Réponse `200`**
+```json
+[
+  { "id": 1, "type": "devise", "code": "EUR", "name": "Euro", "devise_cotation": "EUR" },
+  { "id": 2, "type": "etf",    "code": "LU1681043599", "name": "Amundi MSCI World", "devise_cotation": "EUR" }
+]
+```
+
+---
+
+### `GET /instruments/{id}`
+
+**Réponse `200`**
+```json
+{ "id": 2, "type": "etf", "code": "LU1681043599", "name": "Amundi MSCI World", "devise_cotation": "EUR" }
+```
+
+**Réponse `404`** — instrument introuvable
+
+---
+
+### `POST /instruments`
+
+**Corps**
+| Champ | Type | Requis | Description |
+|---|---|---|---|
+| `type` | string | ✅ | `devise`, `action`, `etf`, `crypto` |
+| `code` | string | ✅ | ISIN (actions/ETF), ticker (crypto), code devise |
+| `name` | string | ✅ | Nom lisible |
+| `devise_cotation` | string | | Devise de cotation (défaut : `EUR`) |
+
+**Réponse `201`**
+```json
+{ "id": 3, "type": "crypto", "code": "BTC", "name": "Bitcoin", "devise_cotation": "EUR" }
+```
+
+> **Pipeline de prix** : le ticker Yahoo Finance (actions/ETF) est résolu automatiquement via OpenFIGI au prochain cycle. L'ID CoinGecko (crypto) est résolu via l'API search CoinGecko. Les résolutions sont mises en cache dans `instrument_ticker_cache`.
+
+---
+
+### `PUT /instruments/{id}`
+
+Même corps que `POST`. Retourne l'instrument mis à jour.
+
+---
+
+### `DELETE /instruments/{id}`
+
+**Réponse `204`** — supprimé
+
+---
+
+## Comptes
+
+Un compte est un conteneur de positions. Son solde est entièrement dérivé des transactions (aucun solde stocké).
+
+Les enveloppes sont des sous-comptes monétaires liés à un compte maître (voir section Enveloppes).
+`GET /accounts/{id}` retourne toujours le compte avec sa liste d'enveloppes.
+
+### `GET /accounts`
+
+Liste les comptes maîtres (sans les enveloppes).
+
+**Réponse `200`**
+```json
+[
+  {
+    "id": 1,
+    "nom": "Livret A",
+    "type": "livret",
+    "devise_reference": "EUR",
+    "plafond": 22950
+  }
+]
+```
+
+---
+
+### `GET /accounts/{id}`
+
+Retourne le compte et ses enveloppes.
+
+**Réponse `200`**
+```json
+{
+  "id": 1,
+  "nom": "Livret A",
+  "type": "livret",
+  "devise_reference": "EUR",
+  "plafond": 22950,
+  "envelopes": [
+    {
+      "id": 3,
+      "nom": "Vacances",
+      "type": "livret",
+      "devise_reference": "EUR",
+      "master_account_id": 1,
+      "objectif": "Road trip USA"
+    }
+  ]
+}
+```
+
+**Réponse `404`** — compte introuvable
+
+---
+
+### `POST /accounts`
+
+Crée un compte maître.
+
+**Corps**
+| Champ | Type | Requis | Description |
+|---|---|---|---|
+| `nom` | string | ✅ | Nom du compte |
+| `type` | string | ✅ | `courant`, `livret`, `pea`, `cto`, `crypto`, ... |
+| `devise_reference` | string | | Devise de référence (défaut : `EUR`) |
+| `plafond` | number | | Plafond réglementaire (indicatif) |
+
+**Réponse `201`**
+```json
+{ "id": 1, "nom": "Livret A", "type": "livret", "devise_reference": "EUR", "plafond": 22950 }
+```
+
+---
+
+### `PUT /accounts/{id}`
+
+Met à jour un compte maître. Même corps que `POST`.
+
+---
+
+### `DELETE /accounts/{id}`
+
+Supprime le compte **et toutes ses enveloppes** (CASCADE).
+
+**Réponse `204`**
+
+---
+
+## Enveloppes
+
+Une enveloppe est un sous-compte monétaire rattaché à un compte maître. Elle hérite automatiquement du `type` et de la `devise_reference` de son maître. Le solde est dérivé des transactions, comme pour tout compte.
+
+Règles :
+- Un compte maître ne peut pas lui-même être une enveloppe (pas de chaînage)
+- Supprimée automatiquement avec son compte maître
+
+### `GET /accounts/{id}/envelopes`
+
+Liste les enveloppes d'un compte.
+
+**Réponse `200`**
+```json
+[
+  {
+    "id": 3,
+    "nom": "Vacances",
+    "type": "livret",
+    "devise_reference": "EUR",
+    "master_account_id": 1,
+    "objectif": "Road trip USA"
+  }
+]
+```
+
+---
+
+### `POST /accounts/{id}/envelopes`
+
+Crée une enveloppe sous le compte `{id}`.
+
+**Corps**
+| Champ | Type | Requis | Description |
+|---|---|---|---|
+| `nom` | string | ✅ | Nom de l'enveloppe |
+| `objectif` | string | | Description libre de l'objectif |
+
+**Réponse `201`**
+```json
+{
+  "id": 3,
+  "nom": "Vacances",
+  "type": "livret",
+  "devise_reference": "EUR",
+  "master_account_id": 1,
+  "objectif": "Road trip USA"
+}
+```
+
+**Réponse `400`** — le compte est lui-même une enveloppe (chaînage interdit)
+**Réponse `404`** — compte introuvable
+
+---
+
+### `PUT /envelopes/{id}`
+
+Met à jour le nom et/ou l'objectif d'une enveloppe.
+
+**Corps**
+| Champ | Type | Requis | Description |
+|---|---|---|---|
+| `nom` | string | ✅ | Nouveau nom |
+| `objectif` | string | | Nouvel objectif |
+
+**Réponse `200`** — enveloppe mise à jour
+**Réponse `404`** — enveloppe introuvable
+
+---
+
+### `DELETE /envelopes/{id}`
+
+Supprime l'enveloppe.
+
+**Réponse `204`**