# 🗂️ Guide de passation — IRADA & RUWAD (socle de gestion)

*Rédigé le 15 août 2026. Point d'entrée pour toute nouvelle session Claude (Cowork ou Claude Code).
Objectif : qu'une session qui démarre à froid sache en 10 minutes ce que sont ces apps, où elles
tournent, comment on les déploie, ce qui a été fait récemment, et comment travaille le gérant.*

> **Comment lire ce document.**
> - **Claude Code** (dans le dépôt) : le `CLAUDE.md` / `AGENTS.md` à la racine reste la référence
>   pour les **conventions de code et les règles métier**. Ce guide-ci ajoute ce qui n'est pas dans
>   le code : **l'hébergement réel, le déploiement, l'historique récent, et la logique du gérant**.
> - **Claude Cowork** (dossier « my apps ») : commence par `LISEZ-MOI.md` (index des 4 dossiers),
>   puis ce guide pour le détail.
> - Les deux se complètent, ils ne se répètent pas. En cas de doute sur une règle **de code**,
>   `CLAUDE.md` prime ; sur une donnée **d'hébergement ou d'historique**, ce guide prime.

---

## 1. Carte rapide

Deux applications en production, **même code** (le « socle »), **données séparées** :

| | **IRADA** | **RUWAD** |
|---|---|---|
| Société | IRADA VENTURE | Ruwad Capital Group |
| Adresses | `app.iradaventure.ma` | `ruwadcapitalgroup.com` (vitrine) + `app.ruwadcapitalgroup.com` (admin) |
| Serveur cPanel | CapConnect · **saturn** (`46.4.24.98`) | CapConnect · **mars** |
| Compte cPanel | `mobdiema` | `ruwadcap` |
| Base MySQL | `mobdiema_irada_app` | `ruwadcap_ruwad_app` |
| Racine web | `/home/mobdiema/public_html/app.iradaventure.ma/public` | dépôt `ruwad-app` (le `public_html` = ancienne vitrine statique, **hors-ligne, à ignorer**) |
| Version en prod | **v3.8.6** | **v3.8.6** (montée 3.6.2 → 3.8.5 → 3.8.6 le 11 août) |
| Code (dev, sur le Mac) | `siteweb Iradaventure*/dev-gestion/irada-app` | `siteweb ruwad/dev/ruwad-app` |
| Statut trésorerie | **reconstruite et écrite en prod** (série 3.8.x) — ⚠️ ne pas relancer | garde société active — reprise **refusée** ici |

**PHP en prod (les deux)** : binaire `/opt/cpanel/ea-php83/root/usr/bin/php` (PHP 8.3, `ea-php83`).

Les deux autres dossiers de « my apps » ne sont **pas** ce socle : **MOBDIE** (`app.mobdie.ma`,
Laravel/Filament sur sa propre ligne **v1.6.2**, même compte cPanel `mobdiema` sur saturn) et
**MATCHYMOON** (`matchymoon.com`, site **PHP/MySQL classique**, pas Laravel). Détails dans
`LISEZ-MOI.md`.

---

## 2. Le socle en une page

- **Une seule base de code, plusieurs installations.** Chaque société a son hébergement, sa base,
  son `.env`. **Ce n'est pas du multi-tenant** : pas de `company_id`, pas de filtrage par société.
  Les données ne se croisent jamais parce qu'elles ne sont jamais dans la même base. Né du fork
  Ruwad → IRADA (août 2026).
- **Stack** : Laravel 12 + Filament 5 (3 panels : Admin `/`, Employé `/espace`, Investisseur
  `/portail`) + MySQL + PHP 8.3. Queue = `database`, cache = `file`, cron = `schedule:run`. cPanel
  mutualisé : **pas de Redis, pas de Node en prod**. IA = appels HTTP à l'API Anthropic,
  `ANTHROPIC_MODEL=claude-sonnet-5` (identifiant exact, ne jamais le remplacer).
- **La règle qui prime sur tout** : aucune commande ne touche des données sans vérifier **pour
  quelle société** elle a été écrite. Les outils à usage unique vivent dans
  `app/Console/Commands/Reprise/`, préfixe **`reprise:`**, et déclarent en dur leur société
  attendue. Une installation étrangère (ou sans code société) est **refusée** — dans le doute, on
  n'écrit rien. Les outils permanents portent `gestion:` et tournent partout.
- **Identité = configuration, jamais code.** Raison sociale, marque, couleurs, logos vivent dans les
  réglages `company.*`. Aucun repli ne nomme une société. `company.code` est immuable et commande
  la garde ci-dessus.
- **Conventions** : code/tables/colonnes en **anglais**, UI/libellés/e-mails en **français**.
  Montants `DECIMAL(14,2)` MAD affichés `1 234 567,89 DH`, dates `d/m/Y`, timezone
  `Africa/Casablanca`. Toute logique de calcul dans `app/Services/`, testée, jamais dans les
  ressources Filament.

*(Le détail des règles métier — CCA, RAS, clé de structure 50/50, cautions, catégories
structurelles, semences, sécurité — est dans le `CLAUDE.md` du dépôt. Ne pas le dupliquer ici.)*

---

## 3. Architecture cPanel / hébergement

C'est la partie **qui n'est écrite nulle part dans le code**. À garder à jour.

### IRADA — `app.iradaventure.ma`
- Serveur **saturn.capconnect.com** = `46.4.24.98`, compte cPanel **`mobdiema`**, home `/home/mobdiema`.
- Sous-domaine `app.iradaventure.ma`, **document root** `public_html/app.iradaventure.ma/public`.
- Base **`mobdiema_irada_app`**, hôte `localhost`, préfixe MySQL automatique `mobdiema_`.
- **DNS géré par CapConnect** (SPF/DKIM/DMARC déjà en place) — rien à toucher côté DNS.
- PHP **8.3** via *MultiPHP Manager*, doublé par la ligne `AddHandler ... ea-php83` dans le
  `.htaccess` de l'app (le sous-domaine hérite sinon du `.htaccess` parent qui force 8.2).
- ⚠️ **Sur ce même compte cohabitent** : le dossier `fr` (site iradaventure.ma **+** plateforme des
  comités dans `fr/app`), la base `mobdiema_comites`, et tout ce qui porte `mobdie` / `tottrust`.
  **Ne jamais y toucher.** Tout ce qui est IRADA porte `app.iradaventure.ma` ou `irada_app`.

### RUWAD — `ruwadcapitalgroup.com`
- Serveur **mars** (CapConnect), compte cPanel **`ruwadcap`** (préfixe MySQL `ruwadcap_`).
- Une seule app Laravel sert **la vitrine** (`ruwadcapitalgroup.com`) **et** l'admin
  (`app.ruwadcapitalgroup.com`, avec 2FA).
- Base **`ruwadcap_ruwad_app`**.
- ⚠️ Le **`public_html`** de RUWAD = **ancienne version statique, hors-ligne → à ignorer**. Tout se
  passe dans le dépôt `dev/ruwad-app`.

### Rappel important sur mobdie (même compte que IRADA)
- `app.mobdie.ma` tourne sur le **même compte cPanel `mobdiema`** (saturn, `46.4.24.98`), racine
  `public_html/app.mobdie.ma/public`.
- Mais la **zone DNS de `mobdie.ma` est chez Hostinger, pas dans cPanel** : l'éditeur de zone cPanel
  y est **inopérant**. L'enregistrement A `app` → `46.4.24.98` se règle **chez Hostinger**. (Piège
  connu — ne pas chercher à le régler dans cPanel.)

---

## 4. Déploiement — comment le gérant le fait

Il existe **deux voies**. Savoir laquelle est en jeu.

### 4.a Voie manuelle (celle utilisée en pratique, ex. la série 3.8.x)
Le gérant **applique lui-même** sur le serveur. Claude (Cowork ou Code) **ne déploie jamais** : il
**livre un zip à plat + une procédure exacte**, et le gérant l'exécute via **cPanel → File Manager
(upload + extract)** puis **cPanel → Terminal**.

Squelette d'un déploiement d'affichage/correctif (sans migration), à adapter :

```bash
# 1. Se placer dans l'app
cd /home/mobdiema/public_html/app.iradaventure.ma        # IRADA
PHP=/opt/cpanel/ea-php83/root/usr/bin/php

# 2. SAUVEGARDE base AVANT toute opération qui la touche
$PHP artisan backup:run --only-db

# 3. Sauvegarde des fichiers qu'on remplace (filet de sécurité)
tar czf ~/backup-app-$(date +%F).tgz app resources        # ajouter d'autres dossiers au besoin

# 4. Uploader le zip livré dans le dossier de l'app (File Manager) puis extraire à la racine

# 5. Vider les caches (obligatoire après remplacement de fichiers)
$PHP artisan optimize:clear

# 6. S'il y a des migrations (préciser dans la procédure) :
$PHP artisan migrate --force

# 7. Vérifier
$PHP artisan about | grep -Ei "environment|version"
```

Pour **RUWAD**, même logique mais `cd` vers le dépôt `ruwad-app` du compte `ruwadcap` sur **mars**
(⚠️ **pas** `/home/mobdiema/…` — c'est un autre serveur et un autre compte ; coller le mauvais bloc
dans le mauvais terminal est déjà arrivé, sans dommage grâce à la garde société, mais à éviter).

**Toujours** : `backup:run --only-db` d'abord ; **préserver** `.env`, `storage/` et la base (ne
jamais les écraser) ; livrer un **zip à plat** (chemins relatifs à la racine de l'app).

### 4.b Voie automatique (le socle sait se mettre à jour seul — mécanisme présent)
Le socle embarque un système de MAJ : `deploy/build-zip.sh` **fabrique** l'archive (ne publie rien) ;
`gestion:publier-version` **écrit le manifeste** et c'est lui seul qui met les installations en
mouvement, la nuit, dans leur fenêtre horaire. Ordre non négociable : SHA-256 vérifié → sauvegarde
base **présente et non vide** → maintenance → extraction → migrations dans un **processus PHP neuf**
(`gestion:maj-finaliser`). **Jamais de `migrate:rollback` automatique** (défaire une migration
détruit des données ; on restaure la sauvegarde à la place). ⚠️ Une version dont le manifeste
annonce une **commande de reprise** n'est **jamais** appliquée automatiquement : téléchargée,
signalée, elle attend une décision humaine.

> En clair : les mises à jour de routine peuvent passer par 4.b ; les opérations sensibles (reprise
> de trésorerie) sont **manuelles et humaines** (4.a). C'est un choix assumé.

---

## 5. La trésorerie reconstruite (IRADA) — le gros du travail récent

**Contexte.** La courbe « Trésorerie 12 mois » du tableau de bord était un miroir (elle recopiait le
solde au lieu de reconstruire l'historique jour par jour). Il fallait **reconstruire** les
alimentations passées pour que la courbe raconte la vraie histoire de la caisse et de la banque.

**L'outil.** `app/Services/Treasury/RepartitionDesAlimentations.php`, piloté par la commande gardée
**`reprise:repartir-alimentations`** (garde société = `IRADA`). Elle **répartit / recale** les
alimentations pour que, chaque jour, caisse et banque restent au-dessus de leurs planchers, **et**
que l'on **atterrisse exactement** sur le solde d'arrivée. Elle actionne **6 leviers** :

1. **Re-ventilation caisse ↔ banque** d'une alimentation (changer d'où vient l'argent).
2. **Recalage de date** d'une alimentation (l'avancer pour couvrir un creux).
3. **Ré-imputation d'une dépense** caisse → banque (quand la banque tient et pas la caisse).
4. *(interne)*
5. **Primes portées en CCA** sur la banque (une prime qui creuse la banque devient un apport en
   compte courant d'associé, si la banque tient après).
6. **Tiroir financé en CCA** sur la caisse (un manque résiduel de caisse est financé par un apport
   CCA de l'associé — « **Financement associé pour tout manque** », choix explicite du gérant).

**Deux gardes de sûreté, non contournables :**
- **Garde société** : sur une installation ≠ IRADA, la commande **refuse** (« L'installation
  courante est RUWAD »). Vérifié en vrai. C'est pour ça qu'aligner RUWAD sur le même code est sans
  danger : la reprise n'y tournera jamais.
- **Refus d'écrire si l'atterrissage n'est pas exact** : tant que la reconstruction ne tombe pas
  **au centime** sur le solde d'arrivée, **rien n'est écrit**. `--force` ne force que l'écriture
  d'un plan **qui atterrit** ; `--malgre-les-anomalies` **ne contourne PAS** ce refus.

**La leçon « ligne d'arrivée mobile ».** En mode `--cible-journal`, l'arrivée = le solde **actuel**
du journal (dérivé des événements). Donc si on **modifie une donnée** (ex. réduire un transfert),
on **déplace l'arrivée** — et une reconstruction qui atterrissait ne tombe plus juste. Ce n'est pas
un bug : c'est la cible qui a bougé. Toujours figer les données **avant** de reconstruire.

**Ce qui a débloqué (v3.8.5).** La dernière semaine (06–12 août) est **réellement** tendue en
liquidités avec **0 découvert** — donc mathématiquement non reconstructible ces jours-là. La
solution : l'option **`--jusqu-au=AAAA-MM-JJ`** qui arrête la reconstruction à une date. Avec
**`--jusqu-au=2026-07-31`**, la reconstruction **atterrit** (arrivée **12 994** en banque /
**1 112,80** en caisse, **0 impasse**) et a été **écrite en prod**. Août (mois courant, vivant) est
laissé de côté volontairement.

> ⚠️ **Pour toute session future** : la trésorerie IRADA est **déjà reconstruite et écrite**. **Ne
> pas relancer `reprise:repartir-alimentations`** sans une demande explicite du gérant. Si un jour
> il faut prolonger au-delà du 31/07, il faudra d'abord un vrai découvert ou de vraies entrées sur
> la dernière semaine — sinon ça ne peut pas atterrir.

---

## 6. Chronologie de cette conversation (archive)

Du plus récent au plus ancien, ce qui a été fait et **pourquoi** :

- **Ménage du dossier « my apps » (15 août).** Rangé et documenté. ~3,6 Go inutiles déplacés dans
  `_A_SUPPRIMER_2026-08-15/` (vendor/node_modules régénérables, vieux zips socle, ancien `_to_delete`
  mobdie, déchets macOS) — **rien supprimé définitivement**, le gérant vide la corbeille lui-même.
  Création de `LISEZ-MOI.md` (index) puis de ce guide. Jamais touché : code source, `.git`, secrets.
- **v3.8.6 — Affichage des marchés + dashboard (Mission B, les deux apps).** **Affichage seulement,
  aucun calcul modifié, aucune migration.** Refonte de la fiche marché (identité → position
  financière → répartition des coûts → cautions & RG), rappel « facturé non payé ≠ déficitaire »,
  meilleure hiérarchie du tableau de bord. Déployé sur IRADA **et** RUWAD.
- **RUWAD aligné 3.6.2 → 3.8.5 (Mission A) puis 3.8.6.** RUWAD tournait une vieille version ; montée
  au même code qu'IRADA, en gardant ses données et sa config. Garde société vérifiée (reprise
  refusée sur RUWAD). *(Note : le script `MISE-A-JOUR-RUWAD.sh` avait un faux avertissement « garde
  société n'a pas refusé » dû à `set -euo pipefail` + le code retour 1 de la reprise sur refus —
  cosmétique, la garde marche ; la vérification manuelle l'a prouvé.)*
- **v3.8.5 — option `--jusqu-au`** : ce qui a fait atterrir la reconstruction IRADA (voir §5).
- **v3.8.4 — levier 6** (`financerLeTiroir`, tiroir de caisse financé en CCA). Filtre `nature === null`
  pour exclure cautions/transferts/CCA du financement.
- **v3.8.3 — condition « la banque tient »** ajoutée au levier 5 (ne pas déplacer un trou de la
  caisse vers la banque).

État final : **IRADA et RUWAD en v3.8.6**, trésorerie IRADA reconstruite et écrite, affichage
marchés/dashboard refait.

---

## 7. Ta logique & tes préférences (comment travailler avec le gérant)

*Section demandée explicitement — pour qu'une nouvelle session adopte tout de suite le bon mode.*

- **Langue** : français, ton **direct et concis**. Va au résultat. Pas de préambule, pas de
  « je vais faire… » — fais, puis résume court.
- **Tu appliques toi-même les déploiements.** Claude **livre** (zip à plat + procédure copiable
  telle quelle, **avec les vrais chemins**), tu exécutes sur cPanel. Donne toujours des blocs de
  commandes **prêts à copier-coller**, pas des explications abstraites.
- **Tu détestes les cycles déployer → échouer → recommencer.** Avant de livrer, il faut que ce soit
  **vérifié** (tests verts, atterrissage exact, lint propre). Une livraison = quelque chose qui
  marche du premier coup.
- **Les décisions métier t'appartiennent, pas au logiciel.** Principe gravé : « *l'affectation d'un
  versement à une échéance est une décision de l'exploitant, pas une déduction du logiciel* ». Le
  logiciel **n'invente pas** : il n'infère pas une échéance, ne devine pas une donnée de reprise, ne
  choisit pas à ta place. Dans le doute, il **s'arrête et demande** (ou n'écrit rien).
- **Tu corriges les données toi-même quand il le faut** (« je vais le corriger moi-même par la
  suite ») — ne pas assainir ni « réparer » les données automatiquement.
- **Sécurité d'abord** : gardes société non contournables, refus d'écrire si ça ne tombe pas juste,
  secrets jamais partagés/committés, sauvegarde base avant tout. Tu préfères qu'un outil **refuse**
  plutôt qu'il « réussisse » une bêtise.
- **Réalité de trésorerie** : **0 découvert**. Les reconstructions doivent respecter cette
  contrainte — pas de solde négatif « toléré ».
- **Cohérence entre les deux apps** : IRADA et RUWAD doivent rester sur **la même version**. Une
  amélioration du socle se pense pour les deux.
- **Organisation** : tu tiens des `.md` partout (prompts, rapports, guides). Tu apprécies un dossier
  rangé, un index en tête, des noms de versions clairs.

---

## 8. Pièges & garde-fous (à ne pas réapprendre à chaque fois)

- **IRADA** : ne **jamais** relancer `reprise:*` (trésorerie déjà écrite). Ne **jamais** toucher le
  dossier `fr`, la base `mobdiema_comites`, ni ce qui porte `mobdie`/`tottrust` sur le compte.
- **RUWAD** : `public_html` = vitrine statique morte → ignorer ; tout est dans `dev/ruwad-app`.
  Serveur **mars**, compte `ruwadcap` (≠ IRADA/mobdie qui sont sur saturn/`mobdiema`).
- **mobdie** : DNS chez **Hostinger** (pas cPanel) — l'éditeur de zone cPanel n'a aucun effet.
- **`--malgre-les-anomalies` ne contourne pas** le refus d'atterrissage. `--force` non plus n'écrit
  qu'un plan qui atterrit.
- **Modifier une donnée déplace la ligne d'arrivée** en mode `--cible-journal` (voir §5).
- **`ANTHROPIC_MODEL=claude-sonnet-5`** est l'identifiant exact utilisé par l'app — ne pas le
  « corriger ».
- **Ne jamais renommer une commande planifiée** (`reprise:`, `gestion:`, `courrier:`, `payroll:`…) :
  plusieurs sont dans le cron de prod.
- **Secrets** : `ENV-PRODUCTION-IRADA.txt`, `.env` — jamais partagés, committés, ni copiés hors du
  Mac.
- **Synchro macOS/iCloud** : les dossiers de « my apps » peuvent apparaître renommés avec un suffixe
  « 2 » (`siteweb Iradaventure 2`) pendant une synchro — c'est le nom du moment, le contenu est
  intact. Vérifier le vrai chemin avant d'écrire.

---

## 9. Où est quoi (docs de référence)

- **Index du dossier** : `my apps/LISEZ-MOI.md`
- **Ce guide** : `my apps/GUIDE-PASSATION.md` (+ copie dans chaque dépôt)
- **Conventions de code & règles métier** : `…/irada-app/CLAUDE.md` et `…/irada-app/AGENTS.md`
  (idem côté `ruwad-app`)
- **Déploiement IRADA pas à pas** : `siteweb Iradaventure*/DEPLOIEMENT-IRADA-PAS-A-PAS.md`
- **Déploiement RUWAD** : `siteweb ruwad/ETAPES-A-A-Z.md`, `DEPLOIEMENT-v2.5.4-PAS-A-PAS.md`
- **Conception RUWAD d'origine** : `siteweb ruwad/claude-code-pack/` (cahier des charges, schéma
  BDD, prompts)
- **Rapports de version IRADA** : `…/irada-app/RAPPORT-V*.md`
- **Rapports de cette session** (RUWAD 3.8.5, marchés/dashboard 3.8.6) : `Archives app 2026-08-07/`
- **Trésorerie (code)** : `…/irada-app/app/Services/Treasury/RepartitionDesAlimentations.php` +
  `app/Console/Commands/Reprise/RepartirAlimentations.php`

---

*Fin du guide. À mettre à jour à chaque changement d'hébergement, de version, ou de règle du jeu.*