Sync compta : skill de traitement

---
name: sync-compta
description: Importe les transactions depuis un Balance Activity Report CSV (Airwallex/Wise/etc.), les enrichit (marchand, catégorie, carte, split entre associés via compta-config.mjs), valide avec l'utilisateur, puis pousse vers Google Sheets avec déduplication. Usage mensuel.
---

# Sync Compta

Importe les transactions depuis un Balance Activity Report CSV, les enrichit, et les pousse vers Google Sheets.

## Input

- `$ARGUMENTS` : chemin vers le CSV Balance Activity Report (ex : `~/Downloads/Balance_Activity_Report_2026-01-31.csv`)
- Fichier de règles : `[PROJET]/scripts/compta-config.mjs` (CARD_RULES, MERCHANT_MAP, CATEGORIES)
- Google Sheets compta : `[SHEET_ID]`

## Output

- Google Sheets compta mis à jour
- Onglet **Revenue** : entrées d'argent (settlements clients, virements, refunds)
- Onglet **Expenses** : sorties d'argent (SaaS, payouts, frais, achats carte)
- Déduplication automatique par ID de transaction

## Processus

### Étape 0 : Export du CSV (humain)

**Méthode :** les credentials bancaires ne sont pas données à l'IA. L'utilisateur exporte manuellement le Balance Activity Report (pas le relevé de transactions). Si le fichier n'existe pas, l'agent guide vers ce qu'il faut faire.
**Outils :** Bash (test -f).
**Piège :** confondre Balance Activity Report et Financial Transactions. C'est le premier qu'on veut.

Si `$ARGUMENTS` est vide ou que le fichier n'existe pas, demander à l'utilisateur :

> Exporte le **Balance Activity Report** depuis ta plateforme bancaire :
> 1. Va sur la page des transactions
> 2. Sélectionne la période voulue
> 3. Clique **Export** → **Balance Activity Report** (pas Financial Transactions)
> 4. Enregistre le CSV et donne-moi le chemin

### Étape 1 : Parser le CSV

**Méthode :** script Node.js dédié pour le travail mécanique. Source de vérité : le Balance Activity Report = ce qui touche réellement le wallet.
**Outils :** Bash + Node.js (`parse-csv.mjs`).
**Piège :** inclure les conversions FX internes. Elles sont exclues automatiquement.

```bash
node "[PROJET]/scripts/parse-csv.mjs" "$ARGUMENTS"
```

Output : `/tmp/parsed-<nom_csv>.json` avec `{ revenue: [...], expenses: [...] }`.

Types de transactions :

| Type | Direction | Signification |
|------|-----------|---------------|
| DEPOSIT | Revenue | Virement entrant |
| PAYIN_SETTLEMENT | Revenue | Batch settlement clients |
| PAYOUT_REFUND | Revenue | Annulation d'un payout |
| CARD_PURCHASE | Expense | Achat carte bancaire |
| PAYOUT | Expense | Virement sortant |
| FEE | Expense | Frais bancaires |
| ADJUSTMENT | Expense | Ajustement ponctuel |
| CONVERSION_SELL/BUY | **Exclu** | Mouvements FX internes |

Les frais processing sont déjà déduits des PAYIN_SETTLEMENT, ne pas les mettre en expense séparée.

### Étape 2 : Enrichir les données

**Méthode :** scripts pour le mécanique, IA pour l'intelligent. L'IA reconnaît les marchands, catégorise, détecte les cartes. Le fichier de config externalise les règles : quand un nouveau marchand apparaît, l'ajouter dans compta-config.mjs.
**Outils :** Read (config + JSON), Write (JSON enrichi). Intelligence IA pour la catégorisation.
**Piège :** ne pas nettoyer les noms de marchands. "BUNNYCDN, MEDVODE, SVN, (Subscriptions, **5627)" doit devenir "BunnyCDN".

Pour chaque **dépense**, déterminer :
- **marchand** : nom propre (croiser MERCHANT_MAP + contexte de la description)
- **catégorie** : SaaS, Hébergement, Closers, Presta, Payout, Frais bancaires, Remboursement, Autre
- **carte** : détecter le propriétaire via le last4 dans la description
- **split** : pourcentage par défaut selon la carte (CARD_RULES)

Pour chaque **revenu** : garder la description complète du CSV. L'utilisateur ajustera manuellement sur le sheet.

Écrire le JSON enrichi dans `/tmp/enriched-<nom_csv>.json`.

### Étape 3 : Présenter le résumé

**Méthode :** afficher dépenses par catégorie avec totaux + détail (date, montant, marchand, catégorie, carte, split). Puis revenus avec descriptions complètes. Totaux et marge estimée.
**Outils :** Read + affichage formaté.
**Piège :** valider sans avoir lu le détail. Demander explicitement validation ou ajustements.

**→ Demander validation ou ajustements à l'utilisateur.**

### Étape 4 : Pousser vers Google Sheets

**Méthode :** script Node.js dédié. Déduplication par ID de transaction = filet de sécurité, on peut relancer le skill autant de fois que voulu sans risque.
**Outils :** Bash + Node.js (`push-to-sheets.mjs`) + googleapis.
**Piège :** oublier la déduplication. Sans elle, doublons = compta cassée.

```bash
node "[PROJET]/scripts/push-to-sheets.mjs" "/tmp/enriched-<nom_csv>.json"
```

Ce script :
- Déduplique par ID de transaction (ne ré-insère pas les existants)
- Écrit les revenus dans le tab **Revenue**
- Écrit les dépenses dans le tab **Expenses**
- Affiche le nombre de lignes insérées

### Étape 5 : Résultat

Afficher :
- Nombre de revenus / dépenses importés
- Lien vers le Google Sheet
- Rappeler à l'utilisateur de vérifier les deposits (ajuster les pourcentages pour les virements personnels)

## Méthode détaillée

### Source de vérité : le Balance Activity Report

On utilise le Balance Activity Report (pas le relevé de transactions) parce que :
- Il montre l'argent **réellement reçu/envoyé** sur le wallet
- Les paiements clients arrivent en **batch settlements** (nets de frais processing)
- Les frais processing sont déjà déduits, pas de double comptage
- Les descriptions sont riches (nom expéditeur, référence, note)

### Règles de split par défaut

| Situation | Associé A % | Associé B % |
|-----------|-------------|-------------|
| Carte partagée | 50 | 50 |
| Carte associé A | 100 | 0 |
| Carte associé B | 0 | 100 |
| Payout prestataire | 100 | 0 |
| Tout le reste | 50 | 50 |

### Catégories fixes

SaaS, Hébergement, Closers, Presta, Payout, Frais bancaires, Remboursement, Autre.

Un dropdown est configuré sur la colonne `categorie` dans Google Sheets.

## Exemples

### Bon exemple d'enrichissement

Description brute du CSV :
> BUNNYCDN, MEDVODE, SVN, (Subscriptions, **5627): USD 25.00

L'agent reconnaît :
- Marchand : BunnyCDN (un CDN)
- Catégorie : Hébergement (pas SaaS)
- Carte : partagée (50/50)
- Split : 50% associé A, 50% associé B

> Pourquoi c'est bon : l'agent croise les règles du fichier de config avec le contexte de la description. Il ne se contente pas de matcher un nom, il comprend ce que fait le service et le catégorise correctement.

### Mauvais exemple d'enrichissement

Description brute :
> BUNNYCDN, MEDVODE, SVN, (Subscriptions, **5627): USD 25.00

Résultat incorrect :
- Marchand : "BUNNYCDN, MEDVODE, SVN" (nom brut non nettoyé)
- Catégorie : "Autre" (pas de correspondance trouvée)
- Split : 50/50 (par défaut, sans vérification de la carte)

> Pourquoi c'est raté : pas de croisement avec le fichier de config, pas de nettoyage du nom, catégorisation par défaut paresseuse. L'agent doit utiliser les règles + son intelligence pour enrichir correctement.

## Ce que tu ne fais PAS

- Demander les credentials bancaires, l'export reste manuel
- Inclure les conversions FX internes (CONVERSION_SELL/BUY)
- Mettre les frais processing en expense séparée (déjà déduits)
- Pousser sans validation humaine du résumé
- Oublier la déduplication par ID de transaction
- Laisser un nom de marchand brut non nettoyé