# PROJECT_RULES.md — Performance S2S

## 1. Mission et principes

Performance S2S est une application interne de pilotage financier de Scale To Success (S2S). Elle doit fournir une vision fiable et traçable de la rentabilité, de la trésorerie, des engagements et de la capacité de financement de l'entreprise.

Configuration de référence :
- Trésorerie initiale déclarée : 70 000 TND, à rattacher à une date de référence et à répartir entre les comptes après rapprochement.
- Mode de suivi : trésorerie (cash) et comptabilité de gestion (accrual).
- Horizon de prévision : 24 mois glissants.
- Projection court terme : hebdomadaire sur 13 semaines.
- Réserve de sécurité : 3 mois de charges fixes.
- Périmètre : S2S et toutes ses activités/produits.
- Devise principale : TND.
- Saisie manuelle et import CSV/Excel.
- Stack : PHP 8.3+, PDO, MySQL 8+ ou version MariaDB compatible, HTML/CSS/JavaScript, Bootstrap 5 et Chart.js.

Ne jamais traiter les 70 000 TND comme un solde actuel confirmé sans date de référence, répartition par compte et rapprochement.

## 2. Règles non négociables

1. La fiabilité financière prime sur la vitesse de développement et l'apparence.
2. Séparer systématiquement :
   - résultat comptable / accrual ;
   - facturation et créances/dettes ;
   - mouvements de trésorerie réels ;
   - prévisions et hypothèses.
3. Une facture n'est pas un encaissement. Une facture fournisseur n'est pas un décaissement.
4. Les paiements partiels sont obligatoires et doivent être historisés individuellement.
5. Un transfert entre comptes ne constitue ni un revenu ni une dépense.
6. Les opportunités commerciales non signées ne sont jamais assimilées à du cash certain.
7. Ne jamais supprimer physiquement un document financier payé, rapproché ou utilisé dans un calcul. Utiliser annulation, contrepassation ou remboursement avec piste d'audit.
8. Chaque montant doit être stocké en DECIMAL, jamais en FLOAT ou DOUBLE.
9. Toutes les opérations financières multi-tables doivent être atomiques via transactions SQL.
10. Toute modification sensible doit être traçable : auteur, date, action, ancienne valeur et nouvelle valeur lorsque pertinent.
11. Les calculs financiers résident dans des services PHP testables, jamais dans les vues ou uniquement dans le JavaScript.
12. Les vues ne doivent jamais recalculer elles-mêmes un indicateur financier.
13. Toute donnée de démonstration doit être clairement identifiée et ne doit pas être mélangée aux données réelles.
14. Ne pas inventer de taux de TVA, règles fiscales tunisiennes ou traitements comptables. Les rendre configurables et faire valider leur paramétrage par le comptable.
15. En cas de doute sur une règle financière, documenter la question et demander une décision avant de coder une hypothèse.

## 3. Architecture logicielle

Utiliser un monolithe PHP structuré en couches, sans microservices pour la V1.

Répartition des responsabilités :
- Controllers : réception HTTP, contrôle des entrées, orchestration légère et réponse.
- Services : règles métier et calculs financiers.
- Repositories : accès SQL via PDO uniquement.
- Models/Entities : objets métier si utiles, sans logique SQL dispersée.
- Validators : validation serveur.
- Middleware : authentification, autorisation, CSRF et contrôles transversaux.
- Views : présentation uniquement.
- Tests : tests unitaires, d'intégration et financiers.

Arborescence cible :

```text
performance-s2s/
├── app/
│   ├── Config/
│   ├── Core/
│   ├── Controllers/
│   ├── Models/
│   ├── Repositories/
│   ├── Services/
│   ├── Middleware/
│   ├── Validators/
│   ├── Helpers/
│   └── Views/
├── database/
│   ├── migrations/
│   ├── seeds/
│   ├── schema.sql
│   └── demo_data.sql
├── public/
│   ├── index.php
│   └── assets/
├── routes/
│   ├── web.php
│   └── api.php
├── storage/
│   ├── logs/
│   ├── cache/
│   ├── exports/
│   └── private/
├── tests/
│   ├── Unit/
│   ├── Integration/
│   └── Financial/
├── scripts/
├── vendor/
├── .env.example
├── composer.json
├── PROJECT_RULES.md
└── README.md
```

Le répertoire `public/` est le seul document root accessible par le serveur web. Les fichiers privés, exports temporaires, logs et justificatifs ne doivent pas être accessibles directement par URL.

## 4. Technologies et conventions

- PHP 8.3+ avec `declare(strict_types=1);` dans les nouveaux fichiers PHP.
- PDO avec exceptions activées, requêtes préparées et émulation des requêtes préparées désactivée lorsque compatible.
- MySQL 8+ ou MariaDB compatible avec les migrations et contraintes retenues.
- InnoDB, `utf8mb4` et fuseau horaire documenté.
- Bootstrap 5 pour le responsive ; JavaScript natif pour les interactions.
- Chart.js pour les graphiques.
- Composer pour les dépendances.
- PHPUnit pour les tests.
- PhpSpreadsheet pour Excel/CSV si nécessaire ; Dompdf pour PDF si nécessaire.
- Noms de tables et colonnes en `snake_case`, en anglais.
- Classes PHP en `PascalCase`, méthodes et variables en `camelCase`.
- Contrôleurs minces ; services explicites ; repositories responsables du SQL.
- Pas de requêtes SQL dans les vues.
- Pas de logique métier dupliquée.
- Éviter les dépendances lourdes sans justification.

## 5. Base de données et intégrité

### Types et conventions
- Identifiants : `BIGINT UNSIGNED` lorsque approprié.
- Montants TND : `DECIMAL(15,3)`.
- Taux de change : `DECIMAL(15,6)`.
- Quantités/taux : précision explicite selon le besoin.
- Dates métier : `DATE` pour les échéances/calendriers ; `DATETIME` ou `TIMESTAMP` pour les événements horodatés.
- Ajouter des index sur les clés étrangères, dates de transaction, dates d'échéance, statuts, comptes et produits.
- Définir les clés étrangères et règles `ON DELETE` explicitement.
- Utiliser des migrations versionnées ; ne pas modifier silencieusement une migration déjà appliquée en environnement partagé.

### Domaines de données
Prévoir au minimum les entités suivantes :
- Utilisateurs, rôles et permissions.
- Comptes financiers et devises.
- Clients, fournisseurs, employés et produits/activités.
- Catégories de revenus et dépenses.
- Factures/revenus et paiements clients.
- Dépenses/factures fournisseurs et paiements fournisseurs.
- Transactions de trésorerie et transferts.
- Écritures comptables de gestion et lignes débit/crédit si le périmètre le nécessite.
- Contrats et éléments récurrents.
- Prévisions, scénarios, budgets et lignes budgétaires.
- Affectations de coûts.
- Immobilisations et amortissements si inclus dans le périmètre V1.
- Alertes, pièces jointes, imports, lignes d'import, audit logs et périodes clôturées.

### Distinction trésorerie / accrual
- `revenues` et `expenses` décrivent les documents et leur traitement en accrual.
- `revenue_payments` et `expense_payments` décrivent les règlements.
- `transactions` représente les mouvements réels des comptes financiers.
- `transfers` représente les transferts internes ; ils modifient les soldes des comptes mais pas le résultat.
- Les écritures comptables de gestion ne doivent pas être confondues avec les transactions de banque/caisse.
- Définir une seule source de vérité pour chaque fait financier afin d'éviter les doubles comptabilisations.
- Les soldes doivent pouvoir être recalculés depuis le solde d'ouverture et les transactions validées.

### Paiements atomiques
Lorsqu'un paiement est enregistré :
1. Valider le document, le montant restant et le compte financier.
2. Ouvrir une transaction PDO.
3. Insérer le paiement.
4. Insérer le mouvement de trésorerie associé.
5. Mettre à jour le statut/solde du document si nécessaire.
6. Insérer les écritures de gestion nécessaires selon les règles retenues.
7. Insérer l'audit log.
8. Commit ; en cas d'erreur, rollback complet.

Prévenir les doubles paiements/doubles imports via références uniques, clés d'idempotence ou contrôles de doublons adaptés.

## 6. Règles du moteur financier

Centraliser les calculs dans des services dédiés, notamment :
- `CashFlowService`
- `RunwayService`
- `ProfitabilityService`
- `ForecastService`
- `BudgetService`
- `RevenueService`
- `ExpenseService`
- `DepreciationService`
- `AlertService`

### Trésorerie
Solde d'un compte = solde d'ouverture + entrées validées - sorties validées.
Trésorerie consolidée = somme des soldes des comptes inclus dans le périmètre, dans une devise de reporting commune.
Les transferts internes doivent être exclus des revenus et dépenses consolidés.
Les transactions en devises doivent conserver montant/devise d'origine, taux utilisé, date du taux et montant converti.

### Burn rate et runway
- Gross burn : décaissements opérationnels sur une période définie.
- Net burn : décaissements de trésorerie moins encaissements de trésorerie sur la même période.
- Si le net burn est positif, runway simplifié = cash disponible / net burn mensuel moyen.
- Si le net burn est nul ou négatif, afficher que l'entreprise ne consomme pas de trésorerie nette sur la période observée ; ne pas afficher une durée infinie.
- Le runway décisionnel doit aussi provenir d'une projection datée des encaissements et décaissements, et identifier la première date où le solde passe sous zéro.
- Afficher la méthode, la période d'observation et les hypothèses utilisées.
- Ne jamais inclure les créances comme cash disponible ; les inclure seulement dans les prévisions à leur date d'encaissement estimée et selon leur niveau de confiance.

### Réserve de sécurité
Réserve cible = 3 × charges fixes mensuelles de référence.
La définition des charges fixes doit être configurable, documentée et validée. Afficher cash disponible, réserve cible, excédent/déficit et date prévisionnelle de franchissement.

### Compte de résultat / accrual
- Calculer les produits et charges selon les dates et règles d'acquisition définies, non selon la date du paiement.
- Séparer CA HT, TVA collectée, TTC, charges HT, TVA déductible et TTC.
- Les immobilisations ne doivent pas être passées automatiquement en charge intégrale ; gérer leur traitement et amortissement selon un paramétrage validé.
- Ne pas présenter un résultat de gestion comme un état comptable légal certifié.
- Les taxes et règles locales doivent être paramétrables et validées par le comptable.

### Prévisions
- Horizon glissant de 24 mois, avec projection hebdomadaire des 13 prochaines semaines.
- Distinguer confirmé, contractuel, probable et hypothétique.
- Les opportunités pondérées peuvent alimenter un scénario, jamais le cash certain.
- Modéliser les dates prévues de règlement, paiements partiels, retards, récurrences et événements exceptionnels.
- Prévoir au minimum les scénarios prudent/pessimiste, central et optimiste.
- Afficher les hypothèses et permettre leur modification autorisée.
- Éviter de compter deux fois un contrat et les factures générées par ce contrat.

### Rentabilité par activité
Activités initiales : SHIPPINGLOG, EZYCOM, INVOXAPRO, CUISYSTOCK, FOODX, DEV, MAINT et GENERAL.
- Distinguer coûts directs et indirects.
- Affecter les coûts partagés selon des clés configurables, datées et justifiables.
- Ne pas répartir automatiquement un coût sans règle définie.
- Afficher séparément la marge avant et après allocation des coûts indirects.

## 7. Import CSV / Excel

Processus obligatoire en deux étapes :
1. Prévisualisation : détection colonnes, formats, erreurs, doublons potentiels et total des montants.
2. Validation puis import transactionnel.

Exigences :
- Modèle de fichier téléchargeable.
- Mapping des colonnes.
- Validation des dates, devises, montants, catégories et comptes.
- Rapport des lignes acceptées/rejetées.
- Détection des doublons.
- Historique de l'import et possibilité de retrouver la source.
- Aucun import silencieux.
- Ne pas transformer un relevé bancaire importé en revenus/dépenses sans classification et validation.

## 8. Sécurité

- Hacher les mots de passe avec `password_hash()` et vérifier avec `password_verify()`.
- Utiliser des sessions sécurisées : cookies `HttpOnly`, `Secure` en HTTPS, `SameSite`, régénération d'identifiant après connexion.
- Protéger toutes les mutations contre CSRF.
- Échapper les sorties HTML selon le contexte.
- Valider côté serveur toutes les entrées ; ne jamais faire confiance au navigateur.
- Utiliser exclusivement des requêtes préparées PDO pour les valeurs.
- Contrôler l'autorisation sur chaque route et chaque ressource, pas seulement masquer les boutons.
- Limiter les tentatives de connexion et journaliser les événements pertinents.
- Stocker les secrets dans `.env`, jamais dans Git.
- Refuser les fichiers exécutables ; contrôler type MIME, taille, extension et nom ; stocker les pièces jointes hors `public/`.
- Ne pas exposer les erreurs SQL, stack traces ou secrets aux utilisateurs.
- Configurer HTTPS, sauvegardes chiffrées lorsque possible et accès restreint aux exports.
- Les exports financiers doivent respecter les permissions et être journalisés.

## 9. UX et présentation

- Interface responsive, sobre et professionnelle.
- Navigation claire par modules.
- Les montants affichent la devise et une précision cohérente.
- Les périodes, filtres et hypothèses sont visibles.
- Les KPI indiquent leur définition et période.
- Les données estimées sont visuellement distinguées des données réelles.
- Les états vides, erreurs, chargements et confirmations doivent être traités.
- Les formulaires financiers doivent afficher un récapitulatif avant validation.
- Prévoir recherche, tri, pagination et filtres sur les listes.
- Ne pas utiliser de couleurs seules pour transmettre un statut.

## 10. Tests obligatoires

Utiliser PHPUnit et créer des tests unitaires, intégration et financiers.

Cas de référence :
1. Facture de 10 000 TND HT réglée en 4 000 puis 6 000 : deux encaissements, créance finale nulle, revenu comptabilisé une seule fois.
2. Transfert de 5 000 TND entre deux comptes : soldes ajustés, trésorerie consolidée inchangée, aucun impact P&L.
3. Cash 70 000, encaissements mensuels 12 000, décaissements 20 000 : net burn 8 000, runway simplifié 8,75 mois.
4. Charges fixes 18 000 : réserve cible 54 000.
5. Salaire de 15 000 exigible avant un encaissement prévu dans 20 jours : projection signale le déficit intermédiaire.
6. Paiement en double : refus ou détection explicite.
7. Annulation d'un paiement rapproché : correction traçable, pas de suppression silencieuse.
8. Import répété du même fichier : détection des doublons.
9. Prévisions : les éléments hypothétiques ne sont pas intégrés au cash confirmé.
10. Soldes recalculés : concordance entre journal et soldes des comptes.

Ajouter des tests pour les dates limites, montants nuls/négatifs, arrondis, devise, fuseaux horaires, droits d'accès et périodes clôturées.

## 11. Qualité et workflow de développement

Pour chaque fonctionnalité :
1. Lire les règles existantes et inspecter le code avant modification.
2. Confirmer les tables et migrations nécessaires.
3. Implémenter validation, service, repository, contrôleur et vue.
4. Ajouter tests unitaires et d'intégration.
5. Vérifier les permissions et l'audit.
6. Exécuter les tests et corriger les régressions.
7. Mettre à jour README et documentation.
8. Résumer les fichiers modifiés, migrations, tests et limites.

Ne pas :
- réécrire un module stable sans nécessité ;
- changer le schéma sans migration ;
- supprimer des données ou fichiers existants ;
- ajouter une dépendance sans justification ;
- introduire de fausses données dans l'environnement réel ;
- contourner les tests en désactivant des assertions ;
- déclarer une fonctionnalité terminée si elle n'a pas été testée.

## 12. Déploiement et exploitation

- Le document root Nginx/Apache pointe uniquement vers `public/`.
- `.env` n'est pas servi par le web.
- Exécuter les migrations de manière contrôlée.
- Utiliser un compte SQL applicatif aux privilèges minimaux.
- Sauvegarder la base et les fichiers privés quotidiennement.
- Conserver des sauvegardes externes et tester régulièrement une restauration.
- Journaliser dans `storage/logs/` avec rotation et accès restreint.
- Documenter les commandes d'installation, mise à jour, migration, sauvegarde et restauration.

## 13. Définition de « terminé »

Une tâche n'est terminée que si :
- les règles métier sont documentées ;
- les validations serveur existent ;
- les autorisations sont appliquées ;
- les écritures sont atomiques si multi-tables ;
- les erreurs sont gérées ;
- les tests pertinents passent ;
- l'interface fonctionne sur desktop et mobile ;
- les migrations et documentation sont à jour ;
- aucun secret ou fichier privé n'est exposé.
