# 6. Conventions

## Langue et vocabulaire

- Code, identifiants SQL et routes en anglais ; interface et documentation utilisateur traduisibles en français.
- Un seul terme canonique par concept : `third_party`, `sales_order`, `delivery_note`, `goods_receipt`, `financial_account`.
- Dates et nombres stockés dans des formats neutres, localisés uniquement à l’affichage.

## Fichiers et dossiers

- Classes PHP : un fichier par classe, `PascalCase.php`, correspondant exactement à la classe.
- Contrôleurs : `SalesInvoiceController.php` ; services : `SalesInvoiceService.php` ; repositories : `SalesInvoiceRepository.php` ; validators : `StoreSalesInvoiceValidator.php` ; policies : `SalesInvoicePolicy.php`.
- Vues : `kebab-case.php`, regroupées par module, par exemple `sales-invoices/show.php`.
- Assets : `kebab-case.css`, `kebab-case.js` ; aucun JavaScript métier inline.
- Configurations : `lowercase.php` (`database.php`, `session.php`).
- Tests : nom de la classe suivi de `Test.php`.

## PHP

- PSR-12, `declare(strict_types=1);`, namespaces PSR-4 sous `App\`.
- Classes `PascalCase`, méthodes/propriétés/variables `camelCase`, constantes `UPPER_SNAKE_CASE`.
- Méthodes verbales et explicites : `createDraft`, `validateInvoice`, `allocatePayment`.
- Booléens préfixés par `is`, `has`, `can`, `should`.
- Types de paramètres et retours obligatoires ; `mixed` évité ; valeurs monétaires transportées comme chaînes décimales ou objets dédiés, jamais float.
- Contrôleurs minces, services transactionnels, repositories SQL ; pas de logique métier dans les vues/helpers.
- Injection des dépendances par constructeur ; pas de globals ni singleton de connexion.
- Exceptions spécifiques traduites en réponses HTTP par le gestionnaire central.

## Fonctions et helpers

- Les fonctions globales sont exceptionnelles, pures et nommées en `snake_case` uniquement si retenues comme helpers de vue (`e()`, `old()` peuvent être des exceptions documentées).
- Toute fonction métier vit dans une classe/service avec un verbe précis.
- Une fonction fait une chose, évite les paramètres booléens ambigus et ne masque pas une écriture en base.

## SQL

- Tables et colonnes en `snake_case`, noms pluriels pour les tables.
- PK `id`; FK `<entity>_id`; booléens `is_*`/`has_*`; dates métier `*_date`; instants `*_at`.
- Contraintes nommées : `pk_<table>`, `fk_<table>_<column>`, `uq_<table>_<columns>`, `chk_<table>_<rule>`.
- Index : `idx_<table>_<columns>`. Indexer les FKs et les motifs réels de filtre/tri, pas chaque colonne isolément.
- Migrations horodatées : `YYYYMMDDHHMMSS_create_sales_invoices_table.php`.
- Mots-clés SQL en majuscules dans les requêtes multilignes ; colonnes explicites, jamais `SELECT *` en production.
- Toute requête est préparée ; pagination bornée ; ordre dynamique en liste blanche.
- Horodatages UTC ; affichage converti dans le fuseau de la société/utilisateur.

## Routes HTTP

Routes en anglais, minuscules, noms pluriels et `kebab-case`. Pas de verbes dans l’URL lorsqu’un verbe HTTP suffit.

```text
GET    /customers
GET    /customers/{id}
POST   /customers
PATCH  /customers/{id}
DELETE /customers/{id}
POST   /sales-quotes/{id}/send
POST   /sales-quotes/{id}/accept
POST   /sales-orders/{id}/confirm
POST   /delivery-notes/{id}/validate
POST   /sales-invoices/{id}/validate
POST   /payments/{id}/cancel
```

- `GET` lecture sans effet de bord ; `POST` création/commande métier ; `PATCH` modification partielle ; `DELETE` suppression logique autorisée d’un référentiel.
- Les transitions métier explicites utilisent une sous-route verbale en `POST` et sont idempotentes lorsque possible.
- Paramètres de filtre : `?page=1&per_page=25&sort=-invoice_date&status=validated`.
- Noms internes : `sales-invoices.index`, `sales-invoices.show`, `sales-invoices.validate`.
- Codes : 200 lecture, 201 création, 204 succès sans contenu, 400 requête invalide, 401 non connecté, 403 interdit, 404 absent ou masqué, 409 conflit d’état, 422 validation, 429 limitation.

## Modèles, DTO et états

- Une entité représente un enregistrement métier ; un DTO représente une commande validée.
- Les statuts sont centralisés dans des constantes/classes dédiées, jamais dispersés comme chaînes arbitraires.
- Les transitions sont centralisées et testées.
- Les snapshots documentaires sont intentionnels et ne sont pas remplacés par des jointures vers les données courantes.

## Front-end futur

- HTML5 sémantique, Bootstrap 5, approche mobile-first.
- Composants réutilisables pour formulaires, erreurs, pagination, tableaux et badges d’état.
- Labels associés, navigation clavier, focus visible, contrastes WCAG AA.
- JavaScript progressif : le parcours essentiel reste cohérent côté serveur.
- Aucun secret ni règle d’autorisation seulement côté JavaScript.

## Commits et versions

- Commits atomiques au format `type(scope): description`, par exemple `feat(stock): add transfer validation`.
- Types : `feat`, `fix`, `refactor`, `test`, `docs`, `build`, `security`.
- Schéma modifié uniquement par migration ; chaque migration prévoit montée, descente sûre ou justification d’irréversibilité.
- Versionnement sémantique des livraisons et changelog des changements métier.

## Definition of Done d’un module

Un module n’est terminé que si : règles métier et transitions sont documentées ; permissions et audit sont définis ; validations serveur existent ; requêtes sont préparées ; transactions couvrent les impacts multiples ; tests unitaires/intégration/fonctionnels passent ; responsive et accessibilité sont vérifiés ; erreurs sont exploitables sans fuite ; documentation d’installation et d’usage est mise à jour.