99 lines
4.1 KiB
Markdown
99 lines
4.1 KiB
Markdown
# Docling Studio
|
|
|
|
Plateforme d'analyse documentaire visuelle : upload de PDFs, extraction (texte, tableaux, images, formules, bounding boxes), export Markdown/HTML.
|
|
|
|
## Stack
|
|
|
|
- **Frontend** : Vue 3, TypeScript (strict), Vite, Pinia, Vitest
|
|
- **Backend** : FastAPI, Python 3.12+, Docling 2.x, aiosqlite (SQLite), pytest
|
|
- **Infra** : Docker Compose, Nginx (reverse proxy), GitHub Actions CI/CD
|
|
|
|
## Structure
|
|
|
|
```
|
|
frontend/ # Vue 3 SPA (feature-based: features/{name}/api/, store/, ui/)
|
|
document-parser/ # FastAPI backend (Clean Architecture: domain/, api/, persistence/, infra/, services/)
|
|
docs/ # MkDocs documentation
|
|
```
|
|
|
|
## Commandes
|
|
|
|
### Backend (depuis `document-parser/`)
|
|
|
|
```bash
|
|
ruff check . # Lint
|
|
ruff check . --fix # Lint + auto-fix
|
|
ruff format . # Format
|
|
pytest tests/ -v # Tests (199 tests, asyncio_mode=auto)
|
|
uvicorn main:app --reload --port 8000 # Dev server
|
|
```
|
|
|
|
### Frontend (depuis `frontend/`)
|
|
|
|
```bash
|
|
npm run lint # ESLint
|
|
npm run lint:fix # ESLint + auto-fix
|
|
npm run format # Prettier
|
|
npm run format:check # Prettier check
|
|
npm run test:run # Vitest (129 tests)
|
|
npm run type-check # vue-tsc --noEmit
|
|
npm run build # Type-check + build
|
|
npm run dev # Dev server port 3000
|
|
```
|
|
|
|
### Docker
|
|
|
|
```bash
|
|
docker compose up # Dev (frontend + backend)
|
|
```
|
|
|
|
## Git
|
|
|
|
- **Ne jamais push** : Claude ne doit jamais exécuter `git push`.
|
|
- **Pas de co-auteur** : aucune mention de Claude dans les commits (pas de `Co-Authored-By`, pas de signature).
|
|
- **Branches** : `feature/*`, `fix/*`, `release/*`. PR vers `main`. Ne jamais empiler de branches sur des branches feature — toujours partir de `main`.
|
|
- **Commits** : messages concis en anglais, verbe impératif (`Fix`, `Add`, `Refactor`), orientés "why" plutôt que "what".
|
|
|
|
## Validation pipeline
|
|
|
|
**Obligatoire avant de considérer toute tâche terminée.** Exécuter dans l'ordre :
|
|
|
|
### Backend (depuis `document-parser/`)
|
|
|
|
```bash
|
|
cd document-parser
|
|
.venv/bin/ruff check . --fix # 1. Lint + auto-fix
|
|
.venv/bin/ruff format . # 2. Format
|
|
.venv/bin/ruff check . # 3. Vérifier zéro violation restante
|
|
.venv/bin/ruff format --check . # 4. Vérifier zéro diff de format
|
|
.venv/bin/pytest tests/ -v # 5. Tous les tests passent
|
|
```
|
|
|
|
### Frontend (depuis `frontend/`)
|
|
|
|
```bash
|
|
cd frontend
|
|
PATH="/usr/local/bin:$PATH" npm run lint:fix # 1. ESLint auto-fix
|
|
PATH="/usr/local/bin:$PATH" npm run format # 2. Prettier format
|
|
PATH="/usr/local/bin:$PATH" npm run lint # 3. Vérifier zéro violation restante
|
|
PATH="/usr/local/bin:$PATH" npm run format:check # 4. Vérifier zéro diff de format
|
|
PATH="/usr/local/bin:$PATH" npm run type-check # 5. vue-tsc --noEmit
|
|
PATH="/usr/local/bin:$PATH" npm run test:run # 6. Tous les tests passent
|
|
```
|
|
|
|
### Critères de validation
|
|
|
|
- **Zéro violation** de lint ou format sur les deux projets.
|
|
- **Tous les tests passent** — aucun skip, aucun xfail non justifié.
|
|
- **Tout nouveau code a des tests** — pas de code non couvert dans un commit.
|
|
- Si un fichier a été modifié, relancer la pipeline complète du projet concerné (backend, frontend, ou les deux).
|
|
|
|
## Conventions
|
|
|
|
- **API contracts** : camelCase (Pydantic `alias_generator` + frontend). snake_case pour le Python interne.
|
|
- **Frontend** : architecture feature-based, path alias `@/` = `src/`, tests colocalisés (`*.test.ts`).
|
|
- **Backend** : Clean Architecture — domain pur (pas de dépendances externes), repository pattern, ports abstraits, converters pluggables (local/remote). Imports first-party : `api`, `domain`, `persistence`, `services`.
|
|
- **Linting** : Ruff (backend, line-length 100), ESLint 9 flat config + Prettier (frontend, 100 chars, sans semicolons, single quotes).
|
|
- **Tests** : toujours lancer les tests et le lint avant de considérer une tâche terminée (voir section Validation pipeline ci-dessus).
|
|
- **Pas de fichiers inutiles** : préférer modifier l'existant plutôt que créer de nouveaux fichiers.
|
|
- **Voir aussi** : `CONTRIBUTING.md` pour le guide de contribution complet.
|