# 3. Analyse fonctionnelle

## Modules

### Administration et identité

Gère sociétés, utilisateurs, rôles, permissions, préférences, séquences documentaires et journal d’audit. Un utilisateur peut appartenir à plusieurs sociétés, mais toute requête métier est exécutée dans une société active explicite.

### Clients, prospects et fournisseurs

Référentiel unique des tiers avec rôles, contacts, adresses, conditions de paiement, plafond de crédit et statut. Le blocage interdit les nouveaux engagements sans supprimer l’historique. Les doublons sont détectés par identifiant fiscal, e-mail et similarité de raison sociale.

### Produits, services et catégories

Catalogue, unités, tarifs d’achat/vente, TVA, codes-barres et catégories hiérarchiques. Un service n’affecte pas le stock. Les prix proposés dans un document peuvent être ajustés si la permission le permet, puis sont figés dans la ligne.

### Ventes

Création, envoi et suivi des devis ; conversion en commandes ; préparation/livraison partielle ; facturation totale, partielle, par livraison, acompte et avoir. Chaque conversion conserve les liens ligne à ligne et empêche la surfacturation ou la surlivraison.

### Achats

Commande fournisseur avec approbation, réception partielle, rapprochement commande–réception–facture et avoir fournisseur. Les écarts de quantité ou de prix sont signalés avant validation.

### Stock et entrepôts

Stock physique par entrepôt/localisation, réservations, transferts, inventaires et alertes. Le disponible est `physique - réservé`. Les réceptions augmentent le physique ; les livraisons le diminuent. Une annulation génère un mouvement inverse traçable.

### Facturation et paiements

Échéances, soldes, paiements partiels ou groupés, allocations, avoirs et relances. Le statut payé provient des allocations validées. Une facture validée n’est pas modifiée ; une correction passe par avoir ou annulation réglementairement autorisée.

### Caisse, banque et dépenses

Comptes financiers, entrées/sorties, dépenses approuvées, transferts, soldes et rapprochement. Un transfert crée une sortie et une entrée atomiques. Une dépense payée crée son écriture financière.

### Tableaux de bord et rapports

Indicateurs filtrés par période, société, utilisateur et entrepôt : chiffre d’affaires, marge indicative, ventes, achats, créances, dettes, trésorerie, rotation/valorisation du stock, ruptures, dépenses et taxes. Export CSV/PDF contrôlé par permissions.

### Documents et notifications

Pièces jointes privées, PDF commerciaux versionnés, alertes de stock, échéances, approbations et événements métier. L’envoi externe est journalisé sans exposer les documents publiquement.

## Cycle client

```text
Client → Devis → Commande client → Bon de livraison → Facture client → Paiement
```

1. **Client** : porte identité, adresses, contacts, devise, conditions de paiement et limite de crédit.
2. **Devis** : proposition sans engagement de stock. Il passe de brouillon à envoyé, puis accepté/refusé/expiré. Un devis accepté peut produire une ou plusieurs commandes si les reliquats sont suivis.
3. **Commande** : engagement commercial. Sa confirmation contrôle crédit, prix et disponibilité, puis crée éventuellement des réservations. Les quantités commandées restent la référence des reliquats.
4. **Bon de livraison** : constate une sortie physique, complète ou partielle, depuis un entrepôt. Sa validation consomme les réservations et crée les mouvements de sortie. Un service n’y crée aucun mouvement.
5. **Facture** : peut provenir de la commande, des quantités livrées ou d’un acompte selon la politique choisie. Sa validation attribue le numéro définitif, fige montants/taxes/adresse et ouvre une créance.
6. **Paiement** : entrée de trésorerie allouée à une ou plusieurs factures du même client. Les allocations déterminent soldes et statuts partiellement payé/payé.

Les étapes sont liées mais pas artificiellement obligatoires : une facture directe ou une commande sans devis est permise avec autorisation. Chaque document conserve sa propre copie historique et référence ses sources. Les conversions sont idempotentes et ne consomment que les quantités restantes.

### Cas particuliers vente

- livraison et facturation partielles avec reliquats ;
- retour client : réception physique et avoir éventuel, deux événements distincts ;
- annulation : seulement selon statut, sinon document inverse ;
- facture d’acompte imputée ensuite à la facture finale ;
- avoir alloué aux factures sans créer un faux paiement ;
- commande bloquée si plafond de crédit dépassé, sauf dérogation auditée.

## Cycle fournisseur

```text
Fournisseur → Commande fournisseur → Réception → Facture fournisseur → Paiement
```

1. **Fournisseur** : conditions d’achat, contacts, devise et références légales.
2. **Commande fournisseur** : besoins, prix attendus, taxes, dates et entrepôt prévu ; peut exiger une approbation selon montant.
3. **Réception** : constate les quantités réellement reçues et augmente le stock au coût retenu. Les réceptions partielles maintiennent un reliquat.
4. **Facture fournisseur** : rapprochée de la commande et/ou réception. Les écarts de prix, quantité ou taxe sont signalés ; sa validation ouvre une dette.
5. **Paiement fournisseur** : sortie de banque/caisse, allouée à une ou plusieurs factures. Les allocations déterminent le solde dû.

Une facture fournisseur peut précéder la réception, mais elle ne modifie jamais le stock. Seule la réception physique le fait. Un retour fournisseur crée un mouvement de sortie et un avoir fournisseur séparé.

## Gestion du stock

### Quantités

- `stock physique` : somme des mouvements validés ;
- `stock réservé` : réservations actives de commandes ;
- `stock disponible` : physique moins réservé ;
- `stock attendu` : reliquats des commandes fournisseur approuvées ;
- `stock projeté` : disponible plus attendu.

### Événements

| Événement | Effet physique | Effet réservation |
|---|---:|---:|
| Commande client confirmée | 0 | augmentation optionnelle |
| Livraison client validée | diminution | consommation/libération |
| Retour client reçu | augmentation | 0 |
| Réception fournisseur | augmentation | 0 |
| Retour fournisseur | diminution | 0 |
| Transfert expédié | diminution source | 0 |
| Transfert reçu | augmentation destination | 0 |
| Inventaire validé | ajustement différentiel | 0 |
| Annulation | mouvement inverse | restauration adaptée |

### Valorisation

La première version utilisera le **coût moyen pondéré mobile** par produit/entrepôt : après une entrée, nouveau coût moyen = `(valeur actuelle + valeur entrée) / nouvelle quantité`. Les sorties reprennent le coût moyen courant. Les services et produits non suivis sont exclus. Une quantité négative est interdite par défaut ; toute dérogation est configurée et auditée.

### Concurrence et intégrité

Validation de livraison/réception sous transaction : verrou du solde concerné, contrôle de disponibilité, insertion du mouvement, mise à jour du solde et du document, puis commit. Une clé d’idempotence empêche un double mouvement après rafraîchissement ou reprise réseau.

## États et transitions

Les transitions sont explicites et contrôlées par permissions. Exemple générique : `draft → validated/confirmed → partially_processed → completed`, avec `cancelled` selon les règles. Le retour à brouillon est interdit après impact stock ou financier. Toute transition sensible enregistre acteur, date, état précédent et état suivant.

## Règles transversales

- Les montants sont recalculés côté serveur avec une politique d’arrondi documentée par devise.
- La devise et le taux de change sont figés à la validation.
- Les recherches et exports respectent les mêmes restrictions que les écrans.
- Les tableaux de bord ne permettent pas de déduire des données auxquelles l’utilisateur n’a pas accès.
- Toutes les listes prévoient pagination, recherche, filtres, tri, export autorisé et conservation optionnelle des filtres.