# Notes — Conventions

> Règles à respecter pour toute contribution (cohérence avec l'existant, cf. CLAUDE.md).

## Code

- **Contrôleurs I/O** : try/catch obligatoire, log via `FileLogger` (action, user_id, error, file, line), flash FR côté web, enveloppe `ApiResponseFormatter` côté API.
- **Accès DB** : toujours `EntityManagerService` (`safePersist`, `safeFlush`, `safeUpdate`…), jamais l'EM brut pour les écritures.
- **Entités** : `TimestampableEntity` ; soft-delete Gedmo + index `idx_<table>_deleted` **uniquement** pour les entités effaçables (catalogue, clients…) ; **jamais** sur les écritures comptables/ventes (append-only). UUID public pour les entités exposées API.
- **Montants** : entiers en **centimes XOF** ; pas de flottants pour l'argent.
- **Scoping** : filtrer par `Company` (boutique de l'utilisateur).

## Permissions (RBAC)

- Convention de code : `<domaine>.<sujet?>.<action>` en minuscules (`pos.sell`, `pos.session.open`, `catalogue.product.edit`, `report.view`).
- Déclarer/seeding dans `RbacSeedCommand` (idempotent) ; rattacher aux rôles de base (Manager/Employé) selon le besoin.
- Gater : `denyAccessUnlessGranted('<perm>', $company)` (contrôleur) et `is_granted('<perm>', company)` (Twig).

## API

- Nouveaux endpoints métier sous `/api/v1/...`, ressources au pluriel.
- Pagination `?page=&limit=`, tri `?sort=-field`, filtres `?filter[x]=`.
- Créations sensibles : accepter `Idempotency-Key`.
- Toujours l'enveloppe standard ; validation → 422.

## Nommage

- Entités/classes en anglais (`Product`, `Sale`, `CashSession`) ; **libellés utilisateur en français**.
- Routes web : `admin_*` / `manager_*` selon l'espace ; API : `api_*`.
- Fichiers de conception : `yima-shop/` (numérotés pour l'ordre de lecture), fiches modules dans `yima-shop/modules/`.

## Rappels de pièges connus

- **`.env.local` non chargé en env test** → redéclarer secrets nécessaires dans `.env.test`.
- **JWT en test** : clés dédiées (`config/jwt/*-test.pem`, passphrase `test_passphrase`).
- **PHPUnit 12** : data providers en attribut `#[DataProvider]`.
- **Rename Company→Boutique** : affichage seulement ; le code garde `Company`/`companies`.
- **Autorité RBAC** : phase 1 s'appuie sur les rôles globaux ; viser les codes de permission pour la bascule phase 2.

## Git / livraison

- Branche par fonctionnalité ; commit clair ; ne pas committer de secret (`.env.local`, `config/jwt/*.pem` sont gitignorés).
- Chaque livraison : tests verts + doc (fiche module + [suivi](../07-suivi.md)) à jour + schéma additif vérifié (`--dump-sql`).