ajoute snapshot

Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>
2026-06-13 22:52:13 +02:00 · 2026-06-13 22:52:13 +02:00 · 0f2d7126eb
commit 0f2d7126eb
parent c73021a14f
11 changed files with 862 additions and 19 deletions
--- a/docs/api.md
+++ b/docs/api.md
@ -381,3 +381,93 @@ Valide ou dé-valide une transaction.
 ### `DELETE /transactions/{id}`

 **Réponse `204`**
+
+---
+
+## Snapshots
+
+Les snapshots capturent la valorisation de chaque compte sur une fenêtre glissante :
+- **Passé** : transactions validées uniquement
+- **Futur** : toutes les transactions (validées ou non) — projection basée sur les transactions planifiées
+
+Deux tables sont alimentées :
+- `position_snapshot` — quantité + valeur par instrument et par compte
+- `account_snapshot` — valeur totale agrégée par compte
+
+**Fenêtre** : de la première transaction jusqu'à `today + SNAPSHOT_HORIZON_DAYS` (défaut : 30 jours). Configurable via la variable d'environnement `SNAPSHOT_HORIZON_DAYS`.
+
+**Toutes les transactions sont comptées** quelle que soit leur validation.
+Le snapshot représente toujours l'état envisagé complet du compte :
+transactions confirmées (`validated = true`) **et** planifiées (`validated = false`).
+La liste `?pending=true` (transactions non validées à date dépassée) reste distincte — c'est un outil de suivi, pas un filtre de calcul.
+
+**Job `daily-snapshot`** (toutes les 24h) :
+1. Traite les invalidations en attente
+2. Recalcule hier (consolide les transactions de la veille)
+3. Calcule le nouveau jour entrant dans la fenêtre (`today + horizon`)
+
+---
+
+### `GET /accounts/{id}/snapshots`
+
+Liste la valorisation totale du compte jour par jour.
+
+**Paramètres de filtre**
+| Paramètre | Type | Description |
+|---|---|---|
+| `from` | string | Date de début `YYYY-MM-DD` (optionnel, défaut : première date disponible) |
+| `to` | string | Date de fin `YYYY-MM-DD` (optionnel, défaut : dernier jour calculé dans la fenêtre) |
+
+**Réponse `200`** — triée par date ASC
+```json
+[
+  { "date": "2026-06-01", "valeur": 2750.00 },
+  { "date": "2026-06-02", "valeur": 2800.00 },
+  { "date": "2026-07-13", "valeur": 2950.00 }
+]
+```
+
+---
+
+### `GET /accounts/{id}/snapshots/positions`
+
+Liste les positions détaillées (par instrument) du compte jour par jour.
+
+**Paramètres de filtre** — mêmes que `/snapshots` (`from`, `to`)
+
+**Réponse `200`** — triée par date ASC puis instrument_id
+```json
+[
+  {
+    "date": "2026-06-01",
+    "instrument_id": 1,
+    "quantite": 2750.00,
+    "prix_cloture": 1.0,
+    "valeur": 2750.00
+  },
+  {
+    "date": "2026-06-01",
+    "instrument_id": 2,
+    "quantite": 5.0,
+    "pru": 350.00,
+    "prix_cloture": 360.00,
+    "valeur": 1800.00
+  }
+]
+```
+
+---
+
+### `POST /accounts/{id}/snapshots/recompute`
+
+Recalcule immédiatement les snapshots d'un compte depuis sa **date d'invalidation** jusqu'à `today + horizon`.
+
+Chaque mutation de transaction (create, update, delete, validate/dévalider) marque automatiquement les comptes concernés comme dirty avec `recompute_from = MIN(date_existante, date_transaction)`. Cet endpoint consomme ce flag sans attendre le job nocturne.
+
+**Réponse `200`** — recalcul effectué
+```json
+{ "account_id": 1, "from": "2026-06-01", "to": "2026-07-13", "status": "ok" }
+```
+
+**Réponse `204`** — aucune invalidation en attente, rien à faire
+**Réponse `404`** — compte introuvable