efc27932dd
Closes the 12 MAJ raised by the release/0.5.0 audit pipeline (cf.
docs/audit/reports/release-0.5.0/summary.md → summary-reaudit.md).
Volet 1 — Reasoning architecture (audits 01/02/06/07 strengthening)
* Domain ports: LLMProvider, ReasoningRunner, ReasoningParseError
* Domain DTOs: LLMProviderType, ReasoningResult, ReasoningIteration
* infra/llm/ollama_provider.py — OllamaProvider with health_check
* infra/docling_agent_reasoning.py — runner adapter, encapsulates the
private _rag_loop call (tracked at docling-project/docling-agent#26),
commits OLLAMA_HOST once at boot (eliminates the per-request env race),
translates upstream IndexError into ReasoningParseError
* api/reasoning.py — zero coupling to docling-agent / mellea / docling-core,
consumes app.state.reasoning_runner via the port
* main.py — DI wires OllamaProvider + DoclingAgentReasoningRunner at boot
when REASONING_ENABLED=true and deps are importable
* Rename RAG_* env vars → REASONING_*, endpoint /rag → /reasoning,
type RAGResult → ReasoningResult, frontend feature flag wiring,
i18n strings, tests, docs (BREAKING — pre-1.0 surface, no external
consumers in production)
* 17 new tests: adapter unit tests with sys.modules stubs, OllamaProvider
httpx tests, R3 concurrent-host isolation, R6 multi-iteration trace
serialization, R13 Protocol conformance via isinstance
* E2E Karate scenario: nav-reasoning hidden when REASONING_ENABLED=false
* README — Live Reasoning section (env vars, archi, link to issue #26)
Bloc B — Security (audit 08, dev-only context)
* docker-compose.yml — DEV DEFAULTS header, OpenSearch DISABLE_SECURITY_PLUGIN
flagged as dev-only with link to OpenSearch security docs
* main.py — boot warning if NEO4J_URI is set with the default 'changeme'
password, so prod operators can't silently inherit it
Bloc C — DRY frontend (audit 05)
* shared/storage/keys.ts — STORAGE_KEYS centralised (theme, locale)
* features/settings/store.ts — dead apiUrl ref + orphan i18n keys removed
* api/schemas.py — DOCUMENT_STATUS_UPLOADED constant
Bloc D — Quality (audits 02/06/07/09/10/12)
* domain/ports.py — DocumentConverter.supports_page_batching property
(LSP fix, replaces isinstance(ServeConverter) check)
* domain/ports.py — VectorStore.ping() (encapsulation, replaces
_vector_store._client.info() reach-around)
* api/analyses.py + api/ingestion.py — path params {job_id} → {analysis_id}
aligned with the user-facing terminology (URLs unchanged)
* api/documents.py — Path.read_bytes() + generate_preview() wrapped in
asyncio.to_thread, unblocks the FastAPI event loop on /preview
* infra/docling_tree.py — PEP 604 union for isinstance (Ruff UP038)
* src/__tests__/integration/ — cross-feature integration test relocated
out of features/history/ so feature folders stay self-contained
* Tightened terminal `assert X is not None` checks (isinstance(.., datetime),
exact value comparisons)
Validation
* 446 backend pytest, 202 frontend vitest — all green
* ruff + ruff format + ESLint + Prettier + vue-tsc clean
* Re-audit verdict: 0 CRIT / 0 MAJ, score ~94/100, GO
Closes #200
64 lines
4.3 KiB
Markdown
64 lines
4.3 KiB
Markdown
# Rapport d'audit : KISS (Keep It Simple, Stupid)
|
|
|
|
**Release** : 0.5.0
|
|
**Date** : 2026-04-28
|
|
**Auditeur** : claude-code
|
|
|
|
---
|
|
|
|
## Score de compliance
|
|
|
|
| Metrique | Valeur |
|
|
|----------|--------|
|
|
| Items conformes | 7 / 8 |
|
|
| Score | 87.5 / 100 |
|
|
| Ecarts CRITICAL | 0 |
|
|
| Ecarts MAJOR | 0 |
|
|
| Ecarts MINOR | 1 |
|
|
| Ecarts INFO | 2 |
|
|
|
|
---
|
|
|
|
## Ecarts constates
|
|
|
|
### [MIN] Unnecessary wrapper function `_to_response`
|
|
- **Localisation** : `document-parser/api/documents.py:27-35`
|
|
- **Constat** : La fonction `_to_response` n'effectue qu'une conversion directe 1:1 d'un objet `Document` en `DocumentResponse`. Aucune logique, validation, ou transformation de valeur. Le mapping est trivial et répété 4 fois (upload, list, get, preview).
|
|
- **Regle violee** : Item 4.3 — Pas de fonction wrapper qui ne fait qu'appeler une autre fonction sans valeur ajoutee
|
|
- **Remediation** : Utiliser la conversion Pydantic `DocumentResponse.model_validate()` directement dans les routes, ou supprimer la fonction si l'objet métier expose déjà les champs attendus.
|
|
|
|
### [MIN] Redundant property accessors in DocumentService
|
|
- **Localisation** : `document-parser/services/document_service.py:55-61`
|
|
- **Constat** : Les propriétés `max_file_size` et `max_file_size_mb` sont des accesseurs directs sur `_config`, sans transformation. `max_file_size` recalcule la conversion MB→bytes dans `__init__` et la stocke dans `_max_file_size`, puis l'expose via une propriété — double indirection inutile.
|
|
- **Regle violee** : Item 4.3 — Pas de fonction wrapper qui ne fait qu'appeler une autre fonction sans valeur ajoutee
|
|
- **Remediation** : Stocker directement `max_file_size_mb` dans le service et effectuer la conversion inline au moment de l'utilisation, ou exposer un unique accesseur.
|
|
|
|
### [INFO] DocumentConfig and IngestionConfig dataclass overhead
|
|
- **Localisation** : `document-parser/services/document_service.py:29-35` et `document-parser/services/ingestion_service.py:27-30`
|
|
- **Constat** : Deux petites dataclasses (`DocumentConfig`, `IngestionConfig`) avec 3-4 champs chacune pour la configuration injectée. Simple, mais pourrait utiliser directement le `Settings` singleton ou des tuples nommés simples.
|
|
- **Regle violee** : Item 4.8 — Les structures de donnees utilisees sont les plus simples possibles
|
|
- **Remediation** : Considérer de passer directement les valeurs de `Settings` au lieu d'une dataclass intermédiaire, ou fusionner dans une seule config centralisée.
|
|
|
|
### [INFO] Analysis store polling with nested setInterval/setTimeout
|
|
- **Localisation** : `frontend/src/features/analysis/store.ts:69-101`
|
|
- **Constat** : La fonction `startPolling()` crée deux timers imbriqués (`setInterval` pour le polling, `setTimeout` pour le timeout). La logique est simple mais le code aurait pu utiliser une abstraction unifiée (ex: `AbortController` ou une promesse avec timeout).
|
|
- **Regle violee** : Item 4.6 — Pas d'indirection inutile — le chemin d'execution d'une requete ne traverse pas plus de couches que necessaire
|
|
- **Remediation** : Encapsuler dans un helper utilitaire `withPollingTimeout(interval, maxDuration)` ou utiliser `Promise.race()` pour unifier la logique.
|
|
|
|
---
|
|
|
|
## Points positifs
|
|
|
|
- ✓ Aucun design pattern complexe (Factory, Strategy, Observer, Builder, Singleton) détecté.
|
|
- ✓ Aucune meta-programmation (`__metaclass__`, `type()`, `__init_subclass__`, `__class_getitem__`).
|
|
- ✓ La configuration centralisée en `infra/settings.py` est simple et lisible ; validation explicite en `__post_init__()` sans magie.
|
|
- ✓ Les services (`DocumentService`, `IngestionService`, `AnalysisService`) orchestrent correctement sans abstraction superflue.
|
|
- ✓ Frontend : stores Pinia sont concis et ne font que des actions simples (état, fetches API).
|
|
- ✓ Pas d'indirection excessive sur les couches HTTP → service → domain.
|
|
- ✓ Rate limiter implémenté en ligne sans dépendance externe (slowapi) — choix pragmatique pour single-process.
|
|
|
|
---
|
|
|
|
## Verdict partiel : GO
|
|
|
|
**Justification** : Score 87.5 ≥ 80 ; zéro écarts CRITICAL ou MAJOR. Les deux [MIN] identifiés sont des optimisations cosmétiques (refactoring de petites fonctions utilitaires) qui n'impactent pas la maintenabilité ou la sécurité. Les [INFO] sont des suggestions pour la prochaine itération. Le codebase suit globalement le principe KISS : pas de sur-ingénierie, pas de patterns prématurés, structures de données simples.
|