From 0c0f372d56cf8229e5d2be3eda48ae3c4248f10d Mon Sep 17 00:00:00 2001 From: Steven Ferey Date: Sat, 14 Feb 2026 16:14:15 +0100 Subject: [PATCH] docs: update documentation to match current codebase - Update versions: ESLint 10, PostgreSQL 18, React 19, TypeScript 5.9, Vite 7 - Add missing env vars: VITE_SITE_URL, VITE_INDEXABLE (SEO) - Add missing directories: schemas/, constants/, plugins/, auth/, pdf/ - Add missing routes: companies/new, companies/:id/edit - Add users table, signature fields, owner_id to backend DB docs - Add upload and verify-email endpoints to backend API docs - List all migrations (002-007) in backend architecture - Remove obsolete reference to activities table cascade Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 26 ++++++++++--- PROJECT.md | 19 +++++---- README.md | 29 +++++++++----- backend/README.md | 99 +++++++++++++++++++++++++++++++++++++++++------ 4 files changed, 139 insertions(+), 34 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c8e935b..9778eba 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -48,7 +48,7 @@ mcp__context7__get-library-docs({ - **Build Tool**: Vite 7 - **Styling**: Tailwind CSS v4 avec `@tailwindcss/postcss` - **Router**: React Router DOM v7 -- **Linting**: ESLint 9 avec TypeScript ESLint +- **Linting**: ESLint 10 avec TypeScript ESLint - **Formatting**: Prettier - **Utilitaires**: clsx + tailwind-merge (via fonction `cn()`) @@ -69,6 +69,10 @@ VITE_APP_NAME=Crafter # Donation addresses (optionnel, pour afficher les boutons de dons) VITE_DONATION_BTC= VITE_DONATION_ETH= + +# SEO (optionnel, pour génération sitemap/robots.txt et meta tags) +VITE_SITE_URL= +VITE_INDEXABLE= ``` **Important** : @@ -102,13 +106,18 @@ npm run type-check # Vérifie les erreurs TypeScript sans émettre de fich src/ ├── components/ │ ├── ui/ # Composants UI réutilisables (Button, Input, etc.) -│ ├── layout/ # Composants de mise en page (Header, Footer, etc.) -│ └── features/ # Composants spécifiques aux fonctionnalités +│ ├── layout/ # Composants de mise en page (AppLayout) +│ ├── auth/ # Composants d'authentification (ProtectedRoute) +│ ├── features/ # Composants spécifiques aux fonctionnalités +│ └── pdf/ # Composants de génération PDF +├── constants/ # Constantes de l'application ├── hooks/ # Custom React hooks ├── lib/ # Fonctions utilitaires et helpers ├── pages/ # Composants de pages/routes +├── plugins/ # Plugins Vite (SEO, sitemap, robots.txt) +├── schemas/ # Schémas de validation Zod ├── services/ # Services API et logique métier -├── stores/ # State management (Context, Zustand, etc.) +├── stores/ # State management (Zustand) └── types/ # Types et interfaces TypeScript partagés ``` @@ -128,7 +137,7 @@ src/ - Router défini dans `src/router.tsx` avec `createBrowserRouter` - Routes organisées avec la propriété `children` pour les routes imbriquées - Layout principal dans `src/components/layout/AppLayout.tsx` avec `` - - Pages dans `src/pages/` (Dashboard, CreateCRA, EditCRA, PreviewCRA) + - Pages dans `src/pages/` - Navigation avec `` et `useNavigate()` - Paramètres dynamiques avec `useParams()` - Routes principales : @@ -142,6 +151,8 @@ src/ - `/dashboard/cra/:id/edit` → EditCRA - `/dashboard/cra/:id/preview` → PreviewCRA - `/dashboard/companies` → Liste des sociétés + - `/dashboard/companies/new` → CreateCompany + - `/dashboard/companies/:id/edit` → EditCompany - `/dashboard/settings` → Paramètres (changement de mot de passe) Exemple de configuration du router : @@ -156,16 +167,21 @@ export const router = createBrowserRouter([ { path: '/register', element: }, { path: '/forgot-password', element: }, { path: '/reset-password/:token', element: }, + { path: '/verify-email/:token', element: }, // Routes protégées (utilisateurs connectés) { path: '/dashboard', element: , + errorElement: , children: [ { index: true, element: }, { path: 'cra/new', element: }, { path: 'cra/:id/edit', element: }, + { path: 'cra/:id/preview', element: }, { path: 'companies', element: }, + { path: 'companies/new', element: }, + { path: 'companies/:id/edit', element: }, { path: 'settings', element: }, ], }, diff --git a/PROJECT.md b/PROJECT.md index 6a412d6..9566658 100644 --- a/PROJECT.md +++ b/PROJECT.md @@ -17,25 +17,28 @@ Crafter est une application web moderne construite avec React, TypeScript et Vit Le projet suit une architecture modulaire avec une séparation claire des responsabilités : -- **components/** - Composants React organisés par type (ui, layout, features) +- **components/** - Composants React organisés par type (ui, layout, auth, features, pdf) +- **constants/** - Constantes de l'application - **hooks/** - Custom React hooks pour la logique réutilisable - **lib/** - Fonctions utilitaires et helpers - **pages/** - Composants de pages pour le routing +- **plugins/** - Plugins Vite (SEO, sitemap, robots.txt) +- **schemas/** - Schémas de validation Zod - **services/** - Services API et logique métier -- **stores/** - Gestion d'état global +- **stores/** - Gestion d'état global (Zustand) - **types/** - Définitions TypeScript partagées ### Stack Technique #### Frontend -- **React 18.3** - Bibliothèque UI avec concurrent features -- **TypeScript 5.6** - Typage statique strict -- **Vite 6** - Build tool rapide avec HMR +- **React 19** - Bibliothèque UI avec concurrent features +- **TypeScript 5.9** - Typage statique strict +- **Vite 7** - Build tool rapide avec HMR - **Tailwind CSS v4** - Framework CSS utility-first - **React Router DOM v7** - Routing client-side #### Développement -- **ESLint 9** - Linting du code JavaScript/TypeScript +- **ESLint 10** - Linting du code JavaScript/TypeScript - **Prettier** - Formatage automatique du code - **TypeScript ESLint** - Rules ESLint pour TypeScript @@ -80,6 +83,8 @@ Le projet utilise les variables d'environnement Vite (préfixe `VITE_`): - `VITE_APP_NAME` - Nom de l'application - `VITE_DONATION_BTC` - Adresse Bitcoin pour les dons (optionnel) - `VITE_DONATION_ETH` - Adresse Ethereum ERC20 pour les dons (optionnel) +- `VITE_SITE_URL` - URL du site pour SEO (optionnel) +- `VITE_INDEXABLE` - Activer l'indexation SEO (optionnel) Fichiers de configuration : - `.env.example` - Template (versionné) @@ -240,6 +245,6 @@ Pour toute question concernant le projet, la licence ou les contributions : --- -**Dernière mise à jour** : 2025 +**Dernière mise à jour** : 2026 **Version** : 0.0.0 **Mainteneur** : DiscoData diff --git a/README.md b/README.md index 2fae00d..fcc5e19 100644 --- a/README.md +++ b/README.md @@ -93,14 +93,14 @@ npm run type-check - **Build Tool**: Vite 7 - **Styling**: Tailwind CSS v4 avec PostCSS - **Router**: React Router DOM v7 -- **Linting**: ESLint 9 + Prettier +- **Linting**: ESLint 10 + Prettier - **API Client**: Fetch API avec hooks personnalisés ### Backend - **Runtime**: Node.js 24+ - **Framework**: Express 5.x - **Language**: TypeScript 5.x -- **Base de données**: PostgreSQL 16 +- **Base de données**: PostgreSQL 18 - **Client DB**: node-postgres (pg) - **Dev Tools**: tsx, nodemon @@ -120,22 +120,29 @@ crafter/ │ │ ├── components/ # Composants React réutilisables │ │ │ ├── ui/ # Composants UI de base │ │ │ ├── layout/ # Composants de mise en page -│ │ │ └── features/ # Composants spécifiques +│ │ │ ├── auth/ # Composants d'authentification +│ │ │ ├── features/ # Composants spécifiques +│ │ │ └── pdf/ # Composants de génération PDF +│ │ ├── constants/ # Constantes de l'application │ │ ├── hooks/ # Custom React hooks │ │ ├── lib/ # Fonctions utilitaires │ │ ├── pages/ # Composants de pages/routes -│ │ ├── services/ # Services API (craService, api) -│ │ ├── stores/ # State management +│ │ ├── plugins/ # Plugins Vite (SEO, sitemap, robots.txt) +│ │ ├── schemas/ # Schémas de validation Zod +│ │ ├── services/ # Services API (cra, company, auth, upload) +│ │ ├── stores/ # State management (Zustand) │ │ └── types/ # Types TypeScript partagés │ ├── .env.local # Variables d'environnement frontend │ └── package.json │ ├── backend/ (Express + TypeScript + PostgreSQL) │ ├── src/ -│ │ ├── config/ # Configuration (database.ts) -│ │ ├── controllers/ # Logique métier (cra.controller.ts) -│ │ ├── models/ # Modèles et requêtes SQL (cra.model.ts) -│ │ ├── routes/ # Routes Express (cra.routes.ts) +│ │ ├── config/ # Configuration (database, jwt, email, upload) +│ │ ├── controllers/ # Logique métier (auth, cra, company, upload) +│ │ ├── middleware/ # Middleware Express (auth, role) +│ │ ├── models/ # Modèles et requêtes SQL (user, cra, company) +│ │ ├── routes/ # Routes Express (auth, cra, company, upload) +│ │ ├── services/ # Services (token, email) │ │ ├── types/ # Types TypeScript backend │ │ └── server.ts # Point d'entrée Express │ ├── migrations/ # Schéma de base de données (schema.sql) @@ -192,6 +199,8 @@ VITE_AI_API_KEY= VITE_APP_NAME=Crafter VITE_DONATION_BTC= # Adresse Bitcoin (optionnel) VITE_DONATION_ETH= # Adresse Ethereum ERC20 (optionnel) +VITE_SITE_URL= # URL du site pour SEO (optionnel) +VITE_INDEXABLE= # Activer l'indexation SEO (optionnel) ``` #### Backend (`backend/.env`) @@ -362,4 +371,4 @@ Voir le fichier [LICENSE](LICENSE) pour plus de détails. --- -© 2025 DiscoData. Tous droits réservés. +© 2025-2026 DiscoData. Tous droits réservés. diff --git a/backend/README.md b/backend/README.md index 5eb533d..53b6b59 100644 --- a/backend/README.md +++ b/backend/README.md @@ -7,7 +7,7 @@ Backend API REST pour l'application Crafter CRA (Compte Rendu d'Activité). - **Runtime**: Node.js 24+ - **Framework**: Express 5.x - **Language**: TypeScript 5.x -- **Base de données**: PostgreSQL 16 +- **Base de données**: PostgreSQL 18 - **ORM**: pg (node-postgres) - Client PostgreSQL natif - **Dev Tools**: tsx, nodemon @@ -17,7 +17,7 @@ Backend API REST pour l'application Crafter CRA (Compte Rendu d'Activité). - Node.js 24+ et npm - Docker et Docker Compose (pour PostgreSQL) -- PostgreSQL 16+ (si pas d'utilisation de Docker) +- PostgreSQL 18+ (si pas d'utilisation de Docker) ### Installation des dépendances @@ -102,6 +102,19 @@ Le serveur démarre sur **http://localhost:3001** ### Structure +#### Table `users` +```sql +- id (UUID, primary key) +- email (VARCHAR, unique, required) - Email de connexion +- password_hash (VARCHAR, required) - Mot de passe hashé (bcrypt) +- first_name (VARCHAR, required) - Prénom +- last_name (VARCHAR, required) - Nom +- role (ENUM: user, admin) - Rôle utilisateur +- email_verified (BOOLEAN) - Email vérifié +- created_at (TIMESTAMP) +- updated_at (TIMESTAMP) +``` + #### Table `companies` ```sql - id (UUID, primary key) @@ -122,6 +135,10 @@ Le serveur démarre sur **http://localhost:3001** - code (VARCHAR, optional) - Code d'activité - exemption (BOOLEAN) - Exemption TVA (Art.293 B du CGI) - tva_number (VARCHAR, optional) - Numéro TVA intracommunautaire +- default_signatory_name (VARCHAR, optional) - Nom du signataire par défaut +- default_signatory_title (VARCHAR, optional) - Titre du signataire par défaut +- default_signature_image (TEXT, optional) - Image de signature en base64 +- owner_id (UUID, foreign key → users.id) - Propriétaire - created_at (TIMESTAMP) - updated_at (TIMESTAMP) ``` @@ -136,13 +153,20 @@ Le serveur démarre sur **http://localhost:3001** - client_id (UUID, foreign key → companies.id) - Société cliente - provider_id (UUID, foreign key → companies.id) - Société prestataire - status (ENUM: draft, submitted, approved, rejected) +- client_signatory_name (VARCHAR, optional) - Nom du signataire client +- client_signatory_title (VARCHAR, optional) - Titre du signataire client +- client_signature_image (TEXT, optional) - Image de signature client en base64 +- provider_signatory_name (VARCHAR, optional) - Nom du signataire prestataire +- provider_signatory_title (VARCHAR, optional) - Titre du signataire prestataire +- provider_signature_image (TEXT, optional) - Image de signature prestataire en base64 +- signature_location (VARCHAR, optional) - Lieu de signature +- signature_date (DATE, optional) - Date de signature +- owner_id (UUID, foreign key → users.id) - Propriétaire - created_at (TIMESTAMP) - updated_at (TIMESTAMP) - CONSTRAINT: client_id <> provider_id (une société ne peut pas être à la fois client et prestataire) ``` -**Note:** La table `activities` a été supprimée. Les CRA sont maintenant mensuels avec un simple tableau de jours travaillés. - ### Gestion de la base de données #### Accéder à Adminer (interface web) @@ -572,6 +596,49 @@ POST /api/auth/reset-password } ``` +#### Vérifier l'email + +``` +POST /api/auth/verify-email +``` + +**Body:** +```json +{ + "token": "verification-token-from-email" +} +``` + +### Upload Endpoints + +#### Upload une image de signature + +``` +POST /api/upload/signature +Authorization: Bearer {accessToken} +Content-Type: multipart/form-data +``` + +**Body:** `signature` (file, PNG/JPEG, max 2MB) + +**Response:** +```json +{ + "success": true, + "data": { + "filename": "signature-uuid.png", + "url": "/uploads/signatures/signature-uuid.png" + } +} +``` + +#### Supprimer une image de signature + +``` +DELETE /api/upload/signature/:filename +Authorization: Bearer {accessToken} +``` + ## 🏗️ Architecture ``` @@ -580,11 +647,13 @@ backend/ │ ├── config/ │ │ ├── database.ts # Configuration PostgreSQL │ │ ├── jwt.config.ts # Configuration JWT (tokens) -│ │ └── email.config.ts # Configuration emails (templates) +│ │ ├── email.config.ts # Configuration emails (templates) +│ │ └── upload.config.ts # Configuration Multer (upload fichiers) │ ├── controllers/ │ │ ├── auth.controller.ts # Logique métier authentification │ │ ├── cra.controller.ts # Logique métier des CRA -│ │ └── company.controller.ts # Logique métier des sociétés +│ │ ├── company.controller.ts # Logique métier des sociétés +│ │ └── upload.controller.ts # Logique métier des uploads │ ├── middleware/ │ │ ├── auth.middleware.ts # Middleware JWT (authenticate) │ │ └── role.middleware.ts # Middleware rôles (admin, user) @@ -595,18 +664,25 @@ backend/ │ ├── routes/ │ │ ├── auth.routes.ts # Routes Express pour Auth │ │ ├── cra.routes.ts # Routes Express pour CRA -│ │ └── company.routes.ts # Routes Express pour Companies +│ │ ├── company.routes.ts # Routes Express pour Companies +│ │ └── upload.routes.ts # Routes Express pour Uploads │ ├── services/ │ │ ├── token.service.ts # Service JWT (génération, validation) │ │ └── email.service.ts # Service emails (envoi via Resend) │ ├── types/ │ │ ├── auth.types.ts # Types TypeScript Auth │ │ ├── cra.types.ts # Types TypeScript CRA -│ │ └── company.types.ts # Types TypeScript Company +│ │ ├── company.types.ts # Types TypeScript Company +│ │ └── express.d.ts # Extensions de types Express │ └── server.ts # Point d'entrée Express ├── migrations/ -│ ├── schema.sql # Schéma de la DB -│ ├── 004_add_users.sql # Migration utilisateurs +│ ├── schema.sql # Schéma de base (companies, cras) +│ ├── 002_add_signature_fields.sql # Champs signature +│ ├── 003_add_signature_location_date.sql # Lieu/date signature +│ ├── 004_add_users.sql # Table utilisateurs +│ ├── 005_add_user_ownership.sql # Relations user-company/cra +│ ├── 006_remove_google_auth.sql # Suppression OAuth +│ ├── 007_signatures_base64.sql # Signatures en base64 │ ├── run-all.sh # Script d'initialisation │ └── README.md # Documentation du schéma ├── .env # Variables d'environnement (non versionné) @@ -720,7 +796,6 @@ npm run db:migrate - Les timestamps utilisent `CURRENT_TIMESTAMP` avec timezone - Les transactions sont gérées pour les opérations complexes (create, update) - Un trigger met à jour automatiquement `updated_at` sur les CRA et les Companies -- La suppression d'un CRA supprime en cascade ses activités - La suppression d'une Company est protégée si elle est référencée par des CRA (contrainte FK) - Une société ne peut pas être à la fois client et prestataire sur un même CRA (contrainte CHECK) - Les champs `client_id` et `provider_id` sont requis pour tous les CRA @@ -736,5 +811,5 @@ npm run db:migrate - [Express.js](https://expressjs.com/) - [node-postgres](https://node-postgres.com/) -- [PostgreSQL 16](https://www.postgresql.org/docs/16/) +- [PostgreSQL 18](https://www.postgresql.org/docs/18/) - [TypeScript](https://www.typescriptlang.org/)