fe83dcdf79
* docs: rename Clean Architecture → Hexagonal Architecture (ports & adapters) Le backend suit le pattern ports & adapters (ports dans domain/ports.py, adaptateurs dans infra/), pas Clean Architecture au sens Uncle Bob. Aligne la terminologie dans README, docs/architecture.md, ADR guide, audit master, fiche audit 01, et la nav mkdocs. Les noms de fichiers et la commande /audit:clean-architecture restent stables pour preserver les liens croises et les skills existants. * feat(settings): add paste-image size/type limits surfaced via /api/health Introduces MAX_PASTE_IMAGE_SIZE_MB (default 10) and PASTE_ALLOWED_IMAGE_TYPES (default image/png,image/jpeg,image/webp) env vars so the upcoming Verify-mode clipboard-paste handler can validate client-side against the same limits the backend enforces. Follows the existing MAX_FILE_SIZE_MB pattern. Ships the accepted design doc at docs/design/195-copy-paste-image-verify-mode.md. Refs #195
206 lines
5.8 KiB
Markdown
206 lines
5.8 KiB
Markdown
# Audit Master — Release Branch Quality Gate
|
|
|
|
Referentiel central d'audit qualite pour les branches `release/X.Y.Z` de Docling Studio.
|
|
|
|
Ce document est le **chef d'orchestre** : il definit les regles, commandite les audits unitaires, et normalise les rapports.
|
|
|
|
---
|
|
|
|
## 1. Perimetre
|
|
|
|
L'audit s'execute sur une branche `release/X.Y.Z` **apres feature freeze**, avant le merge dans `main`.
|
|
|
|
**Cibles :**
|
|
|
|
| Cible | Chemin |
|
|
|-------|--------|
|
|
| Backend (Python/FastAPI) | `document-parser/` (hors `.venv/`, `__pycache__/`, `tests/`) |
|
|
| Frontend (Vue 3/TypeScript) | `frontend/src/` |
|
|
| Tests backend | `document-parser/tests/` |
|
|
| Tests frontend | `frontend/src/**/*.test.*` |
|
|
| Tests e2e | `e2e/` |
|
|
| Infrastructure | `Dockerfile`, `docker-compose.yml`, `nginx.conf`, `.github/` |
|
|
|
|
---
|
|
|
|
## 2. Niveaux de criticite
|
|
|
|
Chaque ecart trouve lors d'un audit est classe selon ces 4 niveaux :
|
|
|
|
| Niveau | Tag | Description | Impact sur le GO/NO-GO |
|
|
|--------|-----|-------------|------------------------|
|
|
| **CRITICAL** | `[CRIT]` | Violation bloquante — faille de securite, corruption de donnees, violation d'architecture majeure | **Bloquant** — le release ne peut pas partir |
|
|
| **MAJOR** | `[MAJ]` | Violation significative — couplage fort, dette technique importante, test manquant sur un chemin critique | Bloquant si > 3 ecarts MAJOR non resolus |
|
|
| **MINOR** | `[MIN]` | Ecart de qualite — nommage, taille de fichier, duplication legere | Non bloquant — a corriger dans le prochain cycle |
|
|
| **INFO** | `[INFO]` | Observation, suggestion d'amelioration, bonne pratique non respectee mais sans risque | Non bloquant — informatif |
|
|
|
|
---
|
|
|
|
## 3. Bareme de compliance
|
|
|
|
Chaque audit unitaire produit une **note de compliance sur 100**.
|
|
|
|
### Calcul
|
|
|
|
Chaque item de checklist a un **poids** defini dans la fiche d'audit :
|
|
|
|
| Poids | Signification |
|
|
|-------|---------------|
|
|
| 3 | Critique — violation = ecart CRITICAL |
|
|
| 2 | Important — violation = ecart MAJOR |
|
|
| 1 | Standard — violation = ecart MINOR |
|
|
|
|
**Formule :**
|
|
|
|
```
|
|
score = (somme des poids des items conformes / somme totale des poids) * 100
|
|
```
|
|
|
|
### Seuils de decision
|
|
|
|
| Score | Verdict | Action |
|
|
|-------|---------|--------|
|
|
| >= 80 | **GO** | Release autorisee |
|
|
| 60 - 79 | **GO CONDITIONNEL** | Release autorisee si 0 CRITICAL, plan de remediation pour les MAJOR |
|
|
| < 60 | **NO-GO** | Release bloquee — corriger et re-auditer |
|
|
|
|
**Regle absolue** : tout ecart `[CRIT]` non resolu = **NO-GO** quel que soit le score.
|
|
|
|
---
|
|
|
|
## 4. Liste des audits
|
|
|
|
Les audits sont executes dans l'ordre ci-dessous. Chacun est une fiche autonome dans `audits/`.
|
|
|
|
| # | Audit | Fichier | Focus |
|
|
|---|-------|---------|-------|
|
|
| 01 | Hexagonal Architecture | [01-clean-architecture.md](audits/01-clean-architecture.md) | Ports & adapters, respect des couches, flux de dependances |
|
|
| 02 | DDD | [02-ddd.md](audits/02-ddd.md) | Bounded contexts, entites, value objects, ubiquitous language |
|
|
| 03 | Clean Code | [03-clean-code.md](audits/03-clean-code.md) | Nommage, taille, lisibilite |
|
|
| 04 | KISS | [04-kiss.md](audits/04-kiss.md) | Simplicite, pas de sur-ingenierie |
|
|
| 05 | DRY | [05-dry.md](audits/05-dry.md) | Duplication, factorisation |
|
|
| 06 | SOLID | [06-solid.md](audits/06-solid.md) | 5 principes SOLID |
|
|
| 07 | Decouplage | [07-decoupling.md](audits/07-decoupling.md) | Front/back, inter-features, contrats |
|
|
| 08 | Securite | [08-security.md](audits/08-security.md) | OWASP, secrets, injection, CORS |
|
|
| 09 | Tests | [09-tests.md](audits/09-tests.md) | Couverture, qualite, e2e |
|
|
| 10 | CI / Build | [10-ci-build.md](audits/10-ci-build.md) | Pipeline, Docker, health check |
|
|
| 11 | Documentation | [11-documentation.md](audits/11-documentation.md) | Changelog, version, TODOs |
|
|
| 12 | Performance | [12-performance.md](audits/12-performance.md) | N+1, memory, concurrence |
|
|
|
|
---
|
|
|
|
## 5. Format de rapport attendu
|
|
|
|
Chaque audit produit un rapport dans `reports/release-X.Y.Z/XX-nom.md` respectant ce format :
|
|
|
|
```markdown
|
|
# Rapport d'audit : [Nom de l'audit]
|
|
|
|
**Release** : X.Y.Z
|
|
**Date** : YYYY-MM-DD
|
|
**Auditeur** : [nom ou "claude-code"]
|
|
|
|
---
|
|
|
|
## Score de compliance
|
|
|
|
| Metrique | Valeur |
|
|
|----------|--------|
|
|
| Items conformes | XX / YY |
|
|
| Score | XX / 100 |
|
|
| Ecarts CRITICAL | N |
|
|
| Ecarts MAJOR | N |
|
|
| Ecarts MINOR | N |
|
|
| Ecarts INFO | N |
|
|
|
|
---
|
|
|
|
## Ecarts constates
|
|
|
|
### [CRIT] Titre de l'ecart
|
|
- **Localisation** : `chemin/fichier.py:ligne`
|
|
- **Constat** : description factuelle
|
|
- **Regle violee** : reference a l'item de checklist
|
|
- **Remediation** : action corrective proposee
|
|
|
|
### [MAJ] Titre de l'ecart
|
|
...
|
|
|
|
### [MIN] Titre de l'ecart
|
|
...
|
|
|
|
### [INFO] Titre de l'ecart
|
|
...
|
|
|
|
---
|
|
|
|
## Points positifs
|
|
|
|
- ...
|
|
|
|
---
|
|
|
|
## Verdict partiel : GO / GO CONDITIONNEL / NO-GO
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Rapport de synthese
|
|
|
|
Le fichier `reports/release-X.Y.Z/summary.md` consolide tous les audits :
|
|
|
|
```markdown
|
|
# Synthese d'audit — Release X.Y.Z
|
|
|
|
**Date** : YYYY-MM-DD
|
|
**Branche** : release/X.Y.Z
|
|
|
|
---
|
|
|
|
## Tableau de bord
|
|
|
|
| # | Audit | Score | CRIT | MAJ | MIN | INFO | Verdict |
|
|
|---|-------|-------|------|-----|-----|------|---------|
|
|
| 01 | Hexagonal Architecture | XX | N | N | N | N | GO |
|
|
| 02 | DDD | XX | N | N | N | N | GO |
|
|
| ... | ... | ... | ... | ... | ... | ... | ... |
|
|
|
|
**Score global** : XX / 100 (moyenne ponderee)
|
|
**Ecarts CRITICAL totaux** : N
|
|
**Ecarts MAJOR totaux** : N
|
|
|
|
---
|
|
|
|
## Ecarts CRITICAL (tous audits confondus)
|
|
|
|
1. [audit] description — fichier:ligne
|
|
|
|
---
|
|
|
|
## Verdict final : GO / GO CONDITIONNEL / NO-GO
|
|
|
|
Conditions (si GO CONDITIONNEL) :
|
|
- ...
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Execution
|
|
|
|
### Lancer un audit complet
|
|
|
|
```
|
|
Audite la branche release/X.Y.Z en suivant docs/audit/master.md
|
|
```
|
|
|
|
### Lancer un audit unitaire
|
|
|
|
```
|
|
Execute l'audit docs/audit/audits/02-ddd.md sur la branche courante
|
|
```
|
|
|
|
### Re-auditer apres correction
|
|
|
|
```
|
|
Re-audite uniquement les ecarts CRITICAL et MAJOR du rapport docs/audit/reports/release-X.Y.Z/summary.md
|
|
```
|