oto-enterprise-os-dtp/DIRECTIVE_FINANCEMENT_BANCAIRE_COMPLET_20260803.md

# 💰 DIRECTIVE · Module Financement Bancaire COMPLET · 2026-08-03

## Exigence Michel (2026-08-03 · 05h AM voyage)

Le module Financement Bancaire actuel est trop simpliste. Michel demande un module COMPLET pour un vrai parcours bancaire immobilier RD.

## Composants OBLIGATOIRES

### 1. Section « Information de l'achat » (auto-remplie)
Résumé de la réservation en cours ·
- Projet · code + nom (P01 Coralis, P03 Nakua, etc.)
- Unité · référence + typologie + surface + orientation + étage + prix USD
- Plan de paiement · 20% résident / 30% étranger + solde bancable
- Apport déjà versé · dépôt de réservation + éventuels versements
- Solde à financer · calcul auto (prix - apport - autres versements)
- Statut Fideicomiso Ley 189-11 · constitué OUI/NON
- Statut CONFOTUR · exonération Ley 158-01 confirmée OUI/NON

### 2. Section « Choix de la banque partenaire »
Liste des banques dominicaines partenaires OTOV7 avec profils ·
- **Banreservas** · banque d'État · taux préférentiels résidents · durée jusqu'à 25 ans · LTV 80%
- **Banco Popular Dominicano** · réseau large · rapide · CONFOTUR-friendly · LTV 75-85%
- **BHD León** · haut de gamme · étrangers acceptés · biling · durée 30 ans
- **Banco Santa Cruz** · taux compétitifs · pré-qualif rapide
- **Scotiabank Republica Dominicana** · étrangers spécialistes · devise USD acceptée · LTV 70%
- **López de Haro** · niche haut de gamme
- Autre · à ajouter selon demande spécifique

Chaque banque doit afficher · taux min-max %, LTV%, durée max ans, spécialités (résidents / étrangers / CONFOTUR / devises acceptées), documents typiquement requis.

Le client choisit UNE banque en priorité (radio button). Possibilité d'ajouter des banques additionnelles en parallèle (multi-dossiers).

### 3. Section « Formulaires banque pré-remplis »
Pour chaque banque, générer automatiquement les formulaires officiels PDF de la banque, pré-remplis avec ·
- Données personnelles (nom, prénom, cédula/passeport, téléphone, courriel, adresse, statut marital, dépendants)
- Données financières client (revenu mensuel, autres crédits, épargne)
- Données achat (projet, unité, prix, apport)
- Données WAG vendeur (RNC, adresse, coordonnées)

**Formulaires typiques par banque** (à obtenir en vrai de chaque banque via démarche relationship manager)  ·
- Solicitud de Préstamo Hipotecario
- Autorización de investigación creditica (DataCrédito)
- Declaración jurada de patrimonio
- Autorización débito automático quote-part
- Certificación de origen de fondos (pour étrangers)

Le client télécharge le PDF pré-rempli, le VÉRIFIE, le SIGNE, le RE-UPLOAD via l'interface. Un journal audit trace chaque signature.

### 4. Section « Exigences bancaires par banque »
Liste explicite des documents que la banque exige, cochée automatiquement au fur et à mesure des uploads.

Documents typiques (varient selon banque) ·
- **Client** · Cédula ou Passeport (2 côtés), Preuve d'adresse récente (<3 mois), 3 dernières fiches de paye ou déclarations ITBIS/DGII, États bancaires 6 derniers mois, Lettre employeur ou attestation profession libérale, Certification de solvabilité, Certification DataCrédito (délivré par banque)
- **Immobilier** · Promesa Irrévocable signée notariée, Fideicomiso Inmobiliario constitué, Titre définitif ou Certificado de Título (si disponible)
- **Étrangers uniquement** · Passeport valide 2 côtés, Visa/résidence si applicable, Lettre origine des fonds notariée (FinCEN GTO), Références bancaires internationales, Références commerciales/personnelles

Chaque item · statut (Non déposé / Déposé / Validé WAG / Envoyé banque), bouton Upload, prévisualisation, remplacement possible.

### 5. Section « Autorisations à signer »
Documents que le client doit signer AVANT que WAG envoie le dossier à la banque ·
- Autorisation de partage de données personnelles avec la banque (RGPD/Ley 172-13)
- Autorisation d'investigation DataCrédito
- Mandat WAG comme intermédiaire de financement
- Acknowledgment · risques de refus bancaire + politique annulation

Signature électronique OTO Sign™ (DocuSeal) sur chaque autorisation, horodatée + IP + hash.

### 6. Mention CRITIQUE affichée en permanence

En haut du module Financement Bancaire, bandeau rouge/or persistant ·

> ⚠ **AUCUN DOCUMENT N'EST TRANSMIS À LA BANQUE tant que ·**
> · **TOUS les documents exigés** ne sont pas déposés dans le portail
> · **TOUTES les autorisations** ne sont pas signées électroniquement
> · **Validation manuelle WAG** confirmée par le conseiller référent
>
> Le bouton « Envoyer à la banque » reste **désactivé** tant que ces 3 conditions ne sont pas remplies. Statut affiché en temps réel.

### 7. Statut envoi banque temps réel
Une fois toutes conditions remplies, le bouton « Envoyer à la banque » s'active. Après envoi ·
- Timestamp exact de l'envoi
- Confirmation email + WhatsApp au client
- Numéro de dossier banque attribué
- Timeline switch vers workflow suivi banque (Prequalifié → Dossier soumis → Analyse crédit → Offre reçue → Contrat signé → Décaissement)

### 8. Journal d'activité complet
Historique horodaté visible par le client ·
- Chaque document déposé (date + heure + IP)
- Chaque autorisation signée (date + heure + hash signature)
- Chaque interaction WAG (validation, remarque, demande complément)
- Chaque étape workflow avancée

## Architecture technique demandée

### Backend endpoints à créer/enrichir
- `GET /api/hypotheque/banques` (existe · enrichir avec profils complets)
- `POST /api/hypotheque/dossier` · créer un nouveau dossier
- `GET /api/hypotheque/dossier/{id}` · état complet du dossier
- `POST /api/hypotheque/dossier/{id}/document` · upload document exigé
- `POST /api/hypotheque/dossier/{id}/authorization` · signer autorisation
- `GET /api/hypotheque/dossier/{id}/form/{bank}/{form_type}.pdf` · télécharger formulaire pré-rempli
- `POST /api/hypotheque/dossier/{id}/submit` · envoyer à la banque (gate check TOUS docs + autorisations)
- `GET /api/hypotheque/dossier/{id}/journal` · historique activité

### Frontend refonte renderHypotheque
Layout accordéon 6 sections · Info achat / Choix banque / Formulaires / Exigences / Autorisations / Envoi
Bandeau alerte persistant en haut
Timeline visible en bas
Journal cliquable expandable

### Backend gate check
Fonction `can_submit_dossier(dossier_id) -> (bool, list_of_reasons)` qui vérifie ·
1. Tous les documents `is_required=True` de la banque choisie sont statut `Validé WAG` ou `Envoyé banque`
2. Toutes les autorisations sont signées (`signature_date NOT NULL`)
3. Un conseiller WAG a validé (`wag_validated_by NOT NULL`)

Si UNE de ces conditions manque, `submit_to_bank()` retourne 403 avec liste raisons détaillées.

## Estimation effort

- **Backend** · 5-8 endpoints + gate check + génération PDF formulaires · **3-5 jours**
- **Frontend** · refonte renderHypotheque 6 sections + upload UI + bandeau alerte + journal · **2-3 jours**
- **Templates PDF** · récupérer les vrais formulaires officiels de 6 banques (démarche relationship management) · **1-2 semaines**
- **Tests** · flow complet client + gate check + envoi simulé · **1-2 jours**

**Total · 3 semaines pour version complète production**

## Livrable MVP dès ce soir (agents Claude Code DTP)

**Phase 1 (P0 · MVP) · 4-6h autonome**
- Refonte renderHypotheque avec les 6 sections + bandeau alerte
- Bouton envoi désactivé + affichage raisons
- Upload documents basique (endpoint existant `/api/hypotheque/upload-doc`)
- Formulaires PDF templates génériques (placeholder texte pré-rempli)

**Phase 2 · vrais formulaires banques** · attend démarche externes Michel avec relationship managers

## Commit régulier

Chaque livraison majeure · commit Gitea `[Sprint 5 · Financement] description`. Michel voit progression au retour.

---

## AMENDEMENT · Michel 2026-08-03 · Dépôt initial obligatoire

### 4ème condition CRITIQUE ajoutée au gate check

Avant que le module Financement Bancaire soit activé et que les démarches avec la banque puissent commencer, **le dépôt initial minimum de l'unité doit être COMPLÈTEMENT versé** ·

- **Résident RD** · 20% du prix total de l'unité
- **Étranger** · 30% du prix total de l'unité

Cette exigence est également une **exigence des banques dominicaines** · elles n'analysent aucun dossier sans preuve d'apport initial complet. Ley 189-11 (Fideicomiso Inmobiliario) valide.

### Gate check étendu · 4 conditions

Fonction `can_submit_dossier(dossier_id) -> (bool, list_of_reasons)` doit vérifier ·
1. **Dépôt initial complet** · `sum(paiements.montant_verse_usd) >= apport_requis_usd` où apport_requis = prix × (0.20 si résident, 0.30 si étranger)
2. Tous les documents `is_required=True` de la banque choisie sont `Validé WAG` ou `Envoyé banque`
3. Toutes les autorisations sont signées (`signature_date NOT NULL`)
4. Un conseiller WAG a validé (`wag_validated_by NOT NULL`)

### Bandeau alerte mise à jour

En haut du module Financement Bancaire, bandeau rouge/or persistant ·

> ⚠ **AUCUN DOCUMENT N'EST TRANSMIS À LA BANQUE tant que ·**
> · **Dépôt initial complet** (20% résident RD · 30% étranger) versé et vérifié
> · **TOUS les documents exigés** ne sont pas déposés dans le portail
> · **TOUTES les autorisations** ne sont pas signées électroniquement
> · **Validation manuelle WAG** confirmée par le conseiller référent
>
> Le bouton « Envoyer à la banque » reste **désactivé** tant que ces 4 conditions ne sont pas remplies. Progression affichée en temps réel avec barre 0-100% par condition.

### Section « Statut apport initial » ajoutée
Nouvelle section au top du module ·
- Prix total unité · X USD
- Statut résidence · Résident RD / Étranger
- Apport requis (20% ou 30%) · Y USD
- Apport versé · Z USD (calcul depuis USER_DATA.paiements)
- **Solde apport restant · W USD**
- Barre de progression apport 0-100%
- Bouton « Compléter le dépôt » (redirige vers section Paiements avec pré-config Cardnet montant restant)

Si apport non complet · les autres sections (Choix banque / Formulaires / Exigences / Autorisations / Envoi) sont **grisées et non-cliquables**. Message · « Complétez d'abord votre apport initial pour démarrer les démarches bancaires ».

### Endpoint backend

- `GET /api/hypotheque/dossier/{id}/gate-status` retourne ·
```json
{
  "can_submit": false,
  "conditions": {
    "apport_initial_complet": {"ok": false, "required": 29000, "paid": 15000, "remaining": 14000, "percent": 51.7},
    "documents_exiges": {"ok": false, "total": 8, "deposited": 5, "validated": 3},
    "autorisations_signees": {"ok": false, "total": 4, "signed": 2},
    "validation_wag": {"ok": false, "validated_by": null}
  }
}
```

Frontend consomme cet endpoint pour afficher progression réelle et griser boutons.

---

## PRÉCISION · Michel 2026-08-03 · Validation par OTO Auditeur Finances (agent IA)

### La 4ème condition N'EST PAS un humain WAG

Contrairement à la version précédente qui mentionnait « conseiller WAG », la validation est faite **directement par OTO Auditeur Finances**, un agent IA autonome. Aucun humain WAG n'est requis dans le cycle · c'est de l'audit automatique par agent.

### Rôle OTO Auditeur Finances

Agent Claude Code (module OTOIA capability `auditeur_finances`) qui exécute les vérifications suivantes à chaque changement d'état du dossier bancaire ·

1. **Cohérence des données client** · nom, cédula/passeport, tel, adresse, employeur cohérents entre tous les documents déposés
2. **Vérification montant apport initial** · somme des paiements Cardnet + virements = apport requis (20% résident / 30% étranger)
3. **Complétude documentaire** · tous les documents `is_required=True` de la banque choisie déposés + non-expirés (< 3 mois pour états bancaires, < 6 mois pour fiches paye)
4. **Validation signatures** · toutes les autorisations OTO Sign™ ont hash + IP + timestamp valides · pas de manipulation
5. **Screening OFAC + PEP + AML** · nom client vs liste OFAC SDN (fichier CSV local /opt/oto/data/compliance/ofac-sdn.csv téléchargé le 2026-08-02)
6. **Cohérence financière** · revenu déclaré ÷ mensualité estimée respecte ratio d'endettement < 40% (norme Superintendencia Bancos RD)
7. **Statut Fideicomiso Ley 189-11** · confirmé constitué avec référence acte notarié
8. **CONFOTUR** · exonération vérifiée si applicable (Ley 158-01)

### Décision agent

L'agent produit un rapport structuré JSON dans `/opt/oto/data/finance-audits/{dossier_id}_{timestamp}.json` ·

```json
{
  "dossier": "HYPO-P01-50r7v1kj0a",
  "audited_at": "2026-08-03T14:30:00Z",
  "audited_by": "oto-auditeur-finances-v1",
  "decision": "APPROVED" | "REJECTED" | "REQUEST_MORE_INFO",
  "checks": {
    "coherence_donnees": "ok",
    "apport_initial": "ok · 30000/30000 USD versé",
    "documents_complets": "missing · manque état bancaire mars 2026",
    "signatures_valides": "ok · 4/4 signées",
    "ofac_screening": "clean",
    "pep_screening": "clean",
    "ratio_endettement": "ok · 28%",
    "fideicomiso": "ok · acte notarié réf ACT-2026-P01",
    "confotur": "n/a"
  },
  "reasons": ["Manque état bancaire mars 2026 pour Banreservas"],
  "next_action": "Client doit déposer document manquant"
}
```

### Signature audit

Le rapport est signé HMAC-SHA256 avec clé privée OTO Auditeur (`/etc/oto/oto-auditeur.env · AUDIT_SIGNING_KEY`) pour garantir intégrité et non-répudiation. La signature est vérifiée par le backend avant de flipper `validation_oto_auditeur` à True dans le dossier.

### Intervention humaine · uniquement en dernier recours

Un humain WAG (Michel, Xavier, Cesar, Martires) n'intervient QUE si ·
- Agent retourne `REJECTED` avec raisons ambiguës (< 3× consécutifs sur le même dossier)
- Détection OFAC/PEP positive (screening humain requis par Ley 155-17 AML RD)
- Ratio endettement border-line 38-45% (humain juge exception)
- Client fait un recours écrit contre décision agent

### Endpoint backend supplémentaire

- `POST /api/hypotheque/dossier/{id}/run-audit` · déclenche audit OTO Auditeur (lance capability OTOIA `auditeur_finances`)
- `GET /api/hypotheque/dossier/{id}/audit-latest` · retourne dernier rapport JSON
- `GET /api/hypotheque/dossier/{id}/audit-history` · liste tous les audits horodatés

### Cycle automatique

L'agent OTO Auditeur Finances tourne toutes les 15 minutes en background (cron + task queue OTOIA) pour tous les dossiers en état `Documents complets · en attente audit`. Décisions automatiques poussées à ERPNext + notification client (email + WhatsApp).

### Gate check condition 4 mise à jour

Au lieu de `wag_validated_by IS NOT NULL`, la condition devient ·
```python
audit = get_latest_audit(dossier_id)
condition_4_ok = audit and audit['decision'] == 'APPROVED' and audit['signature_valid']
```

Le client voit dans son portail « Audit OTO Auditeur Finances · APPROUVÉ le [date] » avec lien vers rapport JSON téléchargeable.