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
63 lines
3.5 KiB
Markdown
63 lines
3.5 KiB
Markdown
# Rapport d'audit : SOLID
|
|
|
|
**Release** : 0.5.0
|
|
**Date** : 2026-04-28
|
|
**Auditeur** : claude-code
|
|
|
|
---
|
|
|
|
## Score de compliance
|
|
|
|
| Metrique | Valeur |
|
|
|----------|--------|
|
|
| Items conformes | 18 / 20 |
|
|
| Score | 85 / 100 |
|
|
| Ecarts CRITICAL | 0 |
|
|
| Ecarts MAJOR | 1 |
|
|
| Ecarts MINOR | 1 |
|
|
| Ecarts INFO | 0 |
|
|
|
|
---
|
|
|
|
## Ecarts constates
|
|
|
|
### [MAJ] Liskov Substitution Principle — isinstance check sur adaptateur
|
|
|
|
- **Localisation** : `document-parser/services/analysis_service.py:356`
|
|
- **Constat** : Le service `AnalysisService` utilise `isinstance(self._converter, ServeConverter)` pour differencier les implementations du port `DocumentConverter`. Ceci viole LSP car :
|
|
1. Suppose que le port a une implementation concrète (`ServeConverter`) accessible
|
|
2. Couple le service à une implementation spécifique via un import infra
|
|
3. Empeche la substitution transparente d'autres adaptateurs (e.g., mock, Docling Cloud)
|
|
- **Regle violee** : 6.3.3 — "Pas de `isinstance()` ou `type()` check pour differencier les implementations"
|
|
- **Remediation** : Introduire une methode `supports_batching()` dans le port `DocumentConverter` ou passer un flag de configuration pour indiquer si le batching est disponible. Supprimer l'import infra du service.
|
|
|
|
### [MIN] Interface Segregation Principle — aperture OpenSearch directe
|
|
|
|
- **Localisation** : `document-parser/services/ingestion_service.py:197`
|
|
- **Constat** : `ping()` accede directement à `self._vector_store._client.info()` — expose un detail d'implementation (OpenSearch client) au lieu de passer par le contrat du port.
|
|
- **Regle violee** : 6.4.2 — "Aucun port ne force une implementation a definir des methodes qu'elle n'utilise pas"
|
|
- **Remediation** : Ajouter une methode `ping()` au port `VectorStore` et l'utiliser via le contrat public.
|
|
|
|
---
|
|
|
|
## Points positifs
|
|
|
|
1. **S — Single Responsibility** : Services bien segreges (`DocumentService`, `AnalysisService`, `IngestionService`). Chaque service a une responsabilité unique.
|
|
2. **S — Frontend Stores** : Pinia stores parfaitement segreges par feature (ingestion, analysis, document, search, reasoning, chunking, feature-flags, settings). Aucun store god-object.
|
|
3. **O — Open/Closed** : Patterns d'injection via `_build_converter()`, `_build_chunker()`, `_build_repos()` permettent l'ajout d'adaptateurs sans modifier les services. Architecture très extensible.
|
|
4. **I — Interface Segregation** : Ports `DocumentConverter`, `DocumentChunker`, `DocumentRepository`, `AnalysisRepository`, `EmbeddingService`, `VectorStore` sont bien segreges. Aucune god interface.
|
|
5. **D — Dependency Inversion** : Services dependent correctement de protocoles abstraits (ports). Injection se fait en composition root (`main.py:_build_*`). Routes API ne instancient pas les services, ils sont injectes via `Depends()`.
|
|
6. **API Router Organization** : Routes groupees par ressource (`documents.py`, `analyses.py`, `ingestion.py`, `reasoning.py`, `graph.py`) — pure OCP.
|
|
7. **Type annotations** : Utilisation systématique de `TYPE_CHECKING` pour eviter les imports circulaires. Protocols comme ports — excellent design.
|
|
8. **Frontend composables/stores** : Separation claire entre logique et UI. Chaque store est independant et recomposable.
|
|
|
|
---
|
|
|
|
## Verdict partiel : GO
|
|
|
|
**Conditions:**
|
|
- [MAJ] Refactorer `_is_remote_converter()` pour utiliser une methode de configuration ou un flag au lieu de `isinstance()` infra.
|
|
- [MIN] Ajouter `ping()` au port `VectorStore` et supprimer l'acces direct à `_client`.
|
|
|
|
Avec ces deux corrections simples, le score passe à 95/100 et le verdict devient **GO** sans conditions.
|
|
|