docs(readme) : comprehensive project documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-04 10:45:32 +01:00
parent 8f5f25b3e7
commit 89dc2e93b8
1 changed files with 119 additions and 42 deletions
--- a/README.md
+++ b/README.md
@@ -1,23 +1,25 @@
 # Inventory Frontend

-Frontend de l'application de gestion d'inventaire industriel Malio.
+Interface web de gestion d'inventaire industriel pour **Malio**. Application SPA complète permettant la gestion du parc machines, des pièces, composants, produits, fournisseurs et documents associés.

-## Stack
+## Stack technique

-| Tech | Version |
-|------|---------|
-| Nuxt | 4 (SPA, SSR off) |
-| Vue | 3 Composition API |
-| TypeScript | 5.7 |
-| CSS | TailwindCSS 4 + DaisyUI 5 |
-| Icônes | unplugin-icons (Lucide) |
-| Tests | Vitest |
+| Technologie | Version | Rôle |
+|-------------|---------|------|
+| [Nuxt](https://nuxt.com) | 4 | Framework (SPA, SSR désactivé) |
+| [Vue 3](https://vuejs.org) | 3.5 | Composition API + `<script setup>` |
+| [TypeScript](https://www.typescriptlang.org) | 5.7 | Typage strict sur l'ensemble du projet |
+| [TailwindCSS](https://tailwindcss.com) | 4 | Utility-first CSS |
+| [DaisyUI](https://daisyui.com) | 5 | Composants UI (alertes, modales, badges, etc.) |
+| [Lucide](https://lucide.dev) | via unplugin-icons | Icônes SVG |
+| [Vitest](https://vitest.dev) | 4 | Tests unitaires |
+| [Playwright](https://playwright.dev) | 1.58 | Tests E2E |

 ## Prérequis

- Node.js >= 20
- npm
- Backend Symfony démarré (API sur `http://localhost:8081/api`)
+- **Node.js** >= 20
+- **npm**
+- **Backend Symfony** démarré avec l'API sur `http://localhost:8081/api`

 ## Installation

@@ -31,48 +33,123 @@ npm install
 npm run dev
 ```

-Le serveur de dev est accessible sur `http://localhost:3001`.
+L'application est accessible sur **http://localhost:3001**.

-## Commandes
+## Commandes disponibles

-```bash
-npm run dev          # Serveur de développement
-npm run build        # Build production
-npm run lint:fix     # Correction ESLint
-npx nuxi typecheck   # Vérification TypeScript (0 erreurs attendu)
-npm run test         # Tests unitaires Vitest
-```
+| Commande | Description |
+|----------|-------------|
+| `npm run dev` | Serveur de développement avec HMR |
+| `npm run build` | Build de production |
+| `npm run lint:fix` | Correction automatique ESLint |
+| `npx nuxi typecheck` | Vérification TypeScript (0 erreurs attendu) |
+| `npm run test` | Tests unitaires Vitest |
+| `npm run test:watch` | Tests unitaires en mode watch |
+| `npm run test:e2e` | Tests E2E Playwright (Chrome) |

-## Structure
+## Fonctionnalités
+
+### Gestion du parc
+
+- **Machines** : création, édition, vue détaillée avec structure hiérarchique (composants, pièces, produits)
+- **Squelettes machines** : templates réutilisables pour créer des machines à partir d'un modèle type
+- **Sites** : gestion multi-sites avec coordonnées de contact
+
+### Catalogues
+
+- **Composants**, **Pièces**, **Produits** : catalogues avec recherche serveur, tri, pagination et filtres
+- **Catégories** : système de types avec champs personnalisés configurables et exigences (contraintes de structure)
+- **Fournisseurs** : gestion des constructeurs/fabricants avec liaison multi-entités
+
+### Documents et traçabilité
+
+- **Documents** : upload, prévisualisation PDF/images, stockage sur système de fichiers avec compression PDF automatique
+- **Journal d'activité** : audit trail complet sur toutes les entités (création, modification, suppression)
+- **Commentaires** : système de tickets/commentaires sur les fiches avec statut ouvert/résolu
+
+### Administration
+
+- **Rôles** : ADMIN, GESTIONNAIRE, VIEWER avec permissions granulaires
+- **Profils** : gestion des utilisateurs et attribution des rôles
+- **Notifications** : badge compteur de commentaires ouverts avec polling
+
+## Architecture

 ```
 app/
-├── pages/              # Pages Nuxt (file-based routing)
-├── components/         # Composants Vue (auto-imported)
-├── composables/        # Composables Vue (auto-imported)
-├── shared/             # Types, utils, validation
-│   └── utils/          # Utilitaires partagés
-├── middleware/          # Auth middleware global
-├── services/           # Service layer (wrappers useApi)
-└── utils/              # Utilitaires Nuxt
+├── pages/                  # 36 pages (file-based routing)
+├── components/             # 57 composants Vue (auto-imported par Nuxt)
+│   ├── common/             #   Composants UI réutilisables (modales, pagination, recherche)
+│   ├── form/               #   Champs de formulaire (email, téléphone)
+│   ├── layout/             #   Navbar principale
+│   ├── machine/            #   Vue détail et création de machines
+│   │   └── create/         #   Wizard de création machine
+│   ├── model-types/        #   Gestion des types/catégories
+│   └── sites/              #   Modales site (création, édition)
+├── composables/            # 45 composables (logique métier)
+├── shared/                 # Types, utilitaires, validation
+│   ├── utils/              #   Helpers API, champs personnalisés, affichage, erreurs
+│   ├── validation/         #   Validation email, téléphone
+│   └── model/              #   Définitions de structures
+├── services/               # Service layer (wrappers API spécialisés)
+├── middleware/              # Middleware d'auth global (session cookie)
+└── utils/                  # Formatage dates, montants, événements
 ```

-## Conventions
+## Conventions de code

- **Composables** : `interface Deps { ... }` + `export function useXxx(deps: Deps)`
- **Communication** : Props + Events uniquement (pas de provide/inject)
- **API** : `useApi.ts` avec `credentials: 'include'` (auth session/cookie)
- **Content-Type** : `application/ld+json` pour POST/PUT, `application/merge-patch+json` pour PATCH
- **Auto-imports** : Nuxt auto-importe `components/` et `composables/`
+### Composables

-## Auth
+Pattern avec injection de dépendances explicite :

-Authentification par session (cookies), pas de JWT. Le middleware global `profile.global.ts` protège les routes.
+```typescript
+interface Deps {
+  machineId: Ref<string>
+  onSave: () => void
+}

-## Submodule
+export function useMachineDetail(deps: Deps) {
+  // ...
+}
+```

-Ce repo est un submodule git du repo principal [Inventory](https://gitea.malio.fr/MALIO-DEV/Inventory). Workflow :
+### Communication entre composants

-1. Commiter ici d'abord
+**Props + Events uniquement** — pas de `provide/inject` dans le projet.
+
+### Appels API
+
+Le composable `useApi.ts` centralise tous les appels HTTP :
+- Cookies de session inclus automatiquement (`credentials: 'include'`)
+- `application/ld+json` pour POST/PUT
+- `application/merge-patch+json` pour PATCH
+- Gestion d'erreurs centralisée avec traduction des messages backend en français
+
+### Styles
+
+Classes DaisyUI standard :
+- Input : `input input-bordered input-sm md:input-md`
+- Select : `select select-bordered select-sm md:select-md`
+- Button : `btn btn-sm md:btn-md btn-primary`
+
+## Authentification
+
+L'application utilise une **authentification par session (cookies)**, pas de JWT.
+
+Le middleware global `profile.global.ts` vérifie la session à chaque navigation :
+- Utilisateur non connecté → redirection vers `/profiles`
+- Route `/admin/*` → accès restreint à `ROLE_ADMIN`
+
+## Tests
+
+- **13 tests unitaires** (Vitest + happy-dom) couvrant composables, utils et composants
+- **3 specs E2E** (Playwright + Chrome) avec setup d'authentification
+
+## Submodule Git
+
+Ce repo est un **submodule** du repo principal [Inventory](https://gitea.malio.fr/MALIO-DEV/Inventory).
+
+Workflow de commit :
+1. Commiter dans ce repo (frontend) en premier
 2. Commiter dans le repo principal pour mettre à jour le pointeur submodule
 3. Pousser les deux repos