docs(readme) : comprehensive project documentation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Matthieu
161
README.md
161
README.md
@@ -1,23 +1,25 @@
|
|||||||
# Inventory Frontend
|
# 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 |
|
| Technologie | Version | Rôle |
|
||||||
|------|---------|
|
|-------------|---------|------|
|
||||||
| Nuxt | 4 (SPA, SSR off) |
|
| [Nuxt](https://nuxt.com) | 4 | Framework (SPA, SSR désactivé) |
|
||||||
| Vue | 3 Composition API |
|
| [Vue 3](https://vuejs.org) | 3.5 | Composition API + `<script setup>` |
|
||||||
| TypeScript | 5.7 |
|
| [TypeScript](https://www.typescriptlang.org) | 5.7 | Typage strict sur l'ensemble du projet |
|
||||||
| CSS | TailwindCSS 4 + DaisyUI 5 |
|
| [TailwindCSS](https://tailwindcss.com) | 4 | Utility-first CSS |
|
||||||
| Icônes | unplugin-icons (Lucide) |
|
| [DaisyUI](https://daisyui.com) | 5 | Composants UI (alertes, modales, badges, etc.) |
|
||||||
| Tests | Vitest |
|
| [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
|
## Prérequis
|
||||||
|
|
||||||
- Node.js >= 20
|
- **Node.js** >= 20
|
||||||
- npm
|
- **npm**
|
||||||
- Backend Symfony démarré (API sur `http://localhost:8081/api`)
|
- **Backend Symfony** démarré avec l'API sur `http://localhost:8081/api`
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
@@ -31,48 +33,123 @@ npm install
|
|||||||
npm run dev
|
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
|
| Commande | Description |
|
||||||
npm run dev # Serveur de développement
|
|----------|-------------|
|
||||||
npm run build # Build production
|
| `npm run dev` | Serveur de développement avec HMR |
|
||||||
npm run lint:fix # Correction ESLint
|
| `npm run build` | Build de production |
|
||||||
npx nuxi typecheck # Vérification TypeScript (0 erreurs attendu)
|
| `npm run lint:fix` | Correction automatique ESLint |
|
||||||
npm run test # Tests unitaires Vitest
|
| `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/
|
app/
|
||||||
├── pages/ # Pages Nuxt (file-based routing)
|
├── pages/ # 36 pages (file-based routing)
|
||||||
├── components/ # Composants Vue (auto-imported)
|
├── components/ # 57 composants Vue (auto-imported par Nuxt)
|
||||||
├── composables/ # Composables Vue (auto-imported)
|
│ ├── common/ # Composants UI réutilisables (modales, pagination, recherche)
|
||||||
├── shared/ # Types, utils, validation
|
│ ├── form/ # Champs de formulaire (email, téléphone)
|
||||||
│ └── utils/ # Utilitaires partagés
|
│ ├── layout/ # Navbar principale
|
||||||
├── middleware/ # Auth middleware global
|
│ ├── machine/ # Vue détail et création de machines
|
||||||
├── services/ # Service layer (wrappers useApi)
|
│ │ └── create/ # Wizard de création machine
|
||||||
└── utils/ # Utilitaires Nuxt
|
│ ├── 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)`
|
### Composables
|
||||||
- **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/`
|
|
||||||
|
|
||||||
## 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
|
2. Commiter dans le repo principal pour mettre à jour le pointeur submodule
|
||||||
3. Pousser les deux repos
|
3. Pousser les deux repos
|
||||||
|
|||||||
Reference in New Issue
Block a user