Skill rapprochement-bancaire

> Moteur d'état. Travaille uniquement sur l'arborescence clients//... produite par organisation-documents.

> Le travail réel est fait par scripts/main.py (qui appelle scripts/extract.py pour toute l'extraction de texte). Ce skill = quand le lancer + comment rendre compte.

⚠️ Règle absolue — EXÉCUTION DU SCRIPT (non négociable)

Pour chaque invocation, la SEULE action correcte est d'exécuter la commande :

python3 scripts/main.py <racine_clients>

puis de lire les followup.json / relances.json / anomalies.json par client + le compta_batch_report_.json consolidé, et de relayer au comptable.

❌ INTERDIT

• Réimplémenter le rapprochement en Python inline / pseudo-code. La logique (Pass 1 par référence, Pass 2 fuzzy, validation TVA, détection des anomalies, statuts overdue/partial, génération des relances) est dans scripts/main.py. La refaire à la main est garanti de diverger.
• Écrire followup.json / relances.json / anomalies.json à la main. C'est le script qui le fait, dans son format exact (liste d'objets avec les champs invoice_id, type, amount, status, bank_matched, matched_tx, …). Toute autre forme (dict keyé, champs payments / amount_paid ad hoc) casse les lectures ultérieures.
• Modifier le format des fichiers de sortie. Le format est contractuel entre ce skill et d'éventuels skills aval (relances, dashboards).

✅ OBLIGATOIRE

1. Exécuter la commande shell ci-dessus.
2. Lire les fichiers produits.
3. Relayer au comptable un tableau lisible par client (factures payées / en attente / partielles / overdue, anomalies — en mettant en avant les bloquantes).

Si le script échoue

Signale l'erreur exacte (stderr). Ne rejoue PAS le batch à la main.

> Pourquoi : on a déjà eu un run où l'agent a produit un followup.json au mauvais format (dict avec clés "in/N", champs payments/amount_paid/amount_remaining au lieu de bank_matched/status). Conséquence : aucun outil ni skill aval ne pouvait l'exploiter. Le script génère le bon format à tous les coups.

Exécution

python3 scripts/main.py [<racine_clients>]
# racine_clients par défaut : ~/.openclaw/workspace/clients

À lancer :

• une fois par jour (idéalement la nuit), sur tous les clients ;
• ou immédiatement après un trigger rapprochement-bancaire émis par organisation-documents.

Le script :

1. Parcourt clients/ en ignorant les dossiers techniques _ (_a-identifier, _incomplet, _non-attribue, _cabinet).
2. Périodes traitées : mois courant + mois précédent, plus tout mois ancien non verrouillé (batch.lock.json absent). Un mois verrouillé n'est pas retraité.
3. Factures : nom de fichier conventionnel (AAAA-MM-JJ_N°Facture_Contrepartie_MontantTTC.pdf) → invoice_id + montant. Si le nom n'est pas exploitable, lecture du contenu via extract.py. Si toujours rien → anomalie facture_illisible.
4. Relevés bancaires : transactions extraites ligne par ligne via extract.py (DATE | LIBELLÉ | MONTANT | CR/DB), avec la référence facture si le libellé contient REF ou FACT . Aucune transaction extractible → anomalie releve_non_parseable.
5. Rapprochement (montant comparé en valeur absolue : une facture out est encaissée par un crédit, une in réglée par un débit) :
• Pass 1 — réf facture : transaction dont invoice_ref == facture.invoice_id. Montant exact (±1 €) → paid ; montant inférieur → partial (conserve amount_paid, amount_remaining) ; supérieur → paid + overpaid_by.
• Pass 2 — fuzzy : |montant| ±1 € ET similarité libellé / contrepartie ≥ 0.6.
• aucun match + échéance dépassée → overdue.
6. Validation TVA de chaque facture : si |TVA déclarée − TVA attendue| / TVA attendue > 5 % (TVA attendue = TOTAL HT × taux) → anomalie tva_incorrecte (TVA 0 % / exonération ignorée).
7. Anomalies : voir tableau ci-dessous.
8. Relances : overdue / partial / unpaid hors délai → step selon ancienneté.
9. Écrit clients//followup.json, relances.json, anomalies.json, et un rapport consolidé compta_batch_report_.json.

Après l'exécution, lire le rapport et relayer au comptable un tableau lisible par client (factures payées / en attente, relances, anomalies — en mettant en avant les anomalies bloquantes). Jamais de chemins techniques.

Statuts de facture (followup.json)

Anomalies (anomalies.json)

Bloquantes (empêchent la clôture de la période) :

Non bloquantes (signalées, clôture possible) :

> facture_manquante ≠ paiement_orphelin : le premier = paiement qui cite un n° de facture qu'on n'a pas reçu (le client a oublié de transmettre la pièce) ; le second = encaissement sans aucune référence.

Relances (relances.json)

Pour partial : mention explicite "Solde restant dû : X,XX €".

Clôture de période

Le script crée clients////batch.lock.json quand : aucune anomalie bloquante sur la période, hash des fichiers stable depuis 7 jours, aucun statut unpaid/overdue non justifié. Les périodes verrouillées ne sont jamais retraitées sauf changement de hash.

Règles critiques

• Ne jamais supprimer de données. Ne jamais retraiter un mois verrouillé.
• followup.json est un cache reconstructible : les PDFs classés restent la vérité. Le batch peut tout recalculer depuis zéro.
• clients.json est lu seulement (maintenu par organisation-documents), jamais écrit ici.
• Toute l'extraction de texte passe par scripts/extract.py — source unique, pas de logique de parsing dupliquée ici.

Philosophie

organisation-documents  →  classe les pièces, déduit clients.json
rapprochement-bancaire            →  rapproche, valide, reconstruit l'état comptable  (scripts/main.py)
relances                →  décision différée

Le système doit pouvoir être recalculé intégralement à partir des documents classés.