transfer from private server/git server

docs/04_annexe_A1_qualite_code.md

@@ -0,0 +1,86 @@
+# Annexe A1 — Qualité du code
+
+## Charte de nommage
+
+| Élément | Convention | Exemple réel dans le code |
+|---|---|---|
+| Fonctions, variables | `snake_case` | `create_annonce`, `fichier_id` |
+| Classes / exceptions | `PascalCase` | `AnnonceNotFoundError`, `FileValidationError` |
+| Constantes | `UPPER_SNAKE_CASE` | `TITRE_MAX_LEN`, `ALLOWED_EXTENSIONS` |
+| Modules | `snake_case` court, un rôle par fichier | `annonce_service.py`, `audit_model.py` |
+
+## Séparation stricte des responsabilités
+
+Architecture en couches routes/ → services/ → models/ (voir Bloc 1 — C3/C4).
+Aucune route n'exécute de SQL ; aucun modèle ne connaît la logique HTTP.
+
+## Preuve réelle — exécution de flake8 (2026-08-20)
+
+Commande exécutée : `flake8 --max-line-length=110 --exclude=tests app.py
+config.py db.py models routes services init_db.py`
+
+```
+(sortie vide — 0 violation)
+```
+
+**0 violation PEP8/pyflakes** sur l'ensemble de la couche applicative
+(app.py, config.py, db.py, models/, routes/, services/, init_db.py — hors
+tests). Rapport complet : `docs/evidence/flake8_output.txt`.
+
+## Preuve réelle — exécution de radon (complexité et documentation)
+
+Commande : `radon cc models services routes app.py db.py -s -a`
+
+```
+84 blocs (classes, fonctions, méthodes) analysés.
+Complexité moyenne : A (1.70)
+```
+
+Une complexité cyclomatique moyenne de 1,70 (grade A) signifie que la
+quasi-totalité des fonctions n'a qu'un ou deux chemins d'exécution — cohérent
+avec la décomposition en étapes indépendantes (ex. upload de fichiers en
+8 fonctions, cf. Bloc 3 — C2).
+
+Commande : `radon raw models services routes app.py db.py -s`
+
+```
+Total :
+    LOC (lignes de code) : 984
+    Commentaires : 28 lignes ; commentaires + docstrings : 13 % du total (C+M % L)
+```
+
+**Taux de documentation interne mesuré : 13 %**, dans la fourchette cible
+8–15 % annoncée dans la Partie 2 (Bloc 1 — C2). Rapport complet :
+`docs/evidence/radon_cc_output.txt` et `docs/evidence/radon_raw_output.txt`.
+
+## Taux de réutilisation
+
+Les fonctions de validation et d'autorisation sont centralisées dans
+`services/auth_service.py` (décorateurs `require_login`/`require_admin`) et
+réutilisées par les 4 blueprints de routes (`annonces`, `fichiers`,
+`evenements`, `dashboard`). Les 5 modules de `models/` exposent tous la même
+interface (`insert`/`fetch_all`/`get`/`delete`), ce qui a permis d'écrire
+`services/` sans dupliquer la logique d'accès aux données.
+
+## Preuve réelle — suite de tests (Bloc 1 — C5, Bloc 3 — C7)
+
+Commande : `pytest tests/ -v` exécutée contre une véritable base MariaDB
+10.11 (et non des mocks) :
+
+```
+34 passed in 0.5s
+```
+
+Répartition : 22 tests unitaires (UT-01 à UT-12, avec variantes), 11 tests
+d'intégration (IT-01 à IT-10, avec variante), 6 tests de sécurité (TS-01 à
+TS-06). Détail complet dans `docs/evidence/pytest_output.txt` et dans la
+Partie 4 (Plan de tests) du présent dossier.
+
+Au cours de l'écriture de cette suite, **3 bugs réels ont été détectés puis
+corrigés** grâce aux tests (et non anticipés à l'écriture du code) :
+un paramètre par défaut Python évalué à l'import (`Config.UPLOAD_DIR`)
+qui ignorait les redirections de répertoire en test, un blueprint Flask
+redécoré à chaque création d'application de test, et une confusion entre
+"argument non fourni" et "argument explicitement `None`" dans
+`is_admin()`. Ce sont des exemples concrets de recherche systématique
+d'erreurs (Bloc 1 — C5) et de débogage (Bloc 3 — C5).