From 72672eec1d5c587497ad7913f45a4a06c36f3a27 Mon Sep 17 00:00:00 2001 From: Etienne Santoul <30403047+esantoul@users.noreply.github.com> Date: Thu, 20 Nov 2025 22:01:32 +0100 Subject: [PATCH 01/25] docs: add comprehensive project documentation Add detailed documentation to help contributors and developers: - Add ARCHITECTURE.md with system design and component overview - Add CONFIGURATION.md with environment and deployment setup - Add CONTRIBUTING.md with contribution guidelines and standards - Add DEVELOPMENT.md with setup and development workflow - Update README.md with links to new documentation This documentation provides a complete guide for new contributors to understand the project structure, set up their development environment, and follow best practices. --- README.md | 107 ++++++- docs/ARCHITECTURE.md | 537 +++++++++++++++++++++++++++++++++++ docs/CONFIGURATION.md | 369 ++++++++++++++++++++++++ docs/CONTRIBUTING.md | 520 ++++++++++++++++++++++++++++++++++ docs/DEVELOPMENT.md | 643 ++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 2165 insertions(+), 11 deletions(-) create mode 100644 docs/ARCHITECTURE.md create mode 100644 docs/CONFIGURATION.md create mode 100644 docs/CONTRIBUTING.md create mode 100644 docs/DEVELOPMENT.md diff --git a/README.md b/README.md index 2f58607..12b13c4 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,106 @@ -## Description +# Arrhes + +[](LICENSE) +[](https://www.typescriptlang.org/) +[](https://nodejs.org/) Application **open source** de gestion de comptabilité en partie double pour les associations et entreprises françaises. Elle permet de configurer les comptes, d'ajouter les écritures comptables, les pièces justificatives et de consulter les différents états financiers tels que le bilan ou le compte de résultat. +## Table des matières + +- [À propos](#à-propos) +- [Fonctionnalités](#fonctionnalités) +- [Démarrage rapide](#démarrage-rapide) +- [Documentation](#documentation) +- [Licence](#licence) +- [Support](#support) + +## À propos + +Arrhes est une solution complète de comptabilité conçue spécifiquement pour répondre aux besoins des associations et entreprises françaises. L'application adopte une architecture monorepo et une interface utilisateur simple et intuitive. + +**Public cible :** +- Associations loi 1901 +- Petites et moyennes entreprises +- Comptables et experts-comptables +- Trésoriers d'associations ## Fonctionnalités -- Configuration des comptes -- Création et gestion des écritures comptables -- Gestion des pièces justificatives -- Configuration et consultation des états financiers (bilan, compte de résultat, etc.) -- Gestion des exercices comptables -- Gestion des utilisateurs et des rôles +- ✅ Configuration et gestion des comptes comptables +- ✅ Création et gestion des écritures comptables en partie double +- ✅ Gestion des pièces justificatives avec stockage sécurisé +- ✅ Configuration et consultation des états financiers (bilan, compte de résultat) +- ✅ Gestion des exercices comptables +- ✅ Gestion multi-utilisateurs avec rôles et permissions +- ✅ Authentification sécurisée par magic link +- ✅ Support des journaux comptables multiples +- ✅ Calculs automatiques et validation des écritures + +## Démarrage rapide + +### Prérequis + +- Node.js 24.5+ +- pnpm +- PostgreSQL + +### Installation + +```bash +# Cloner le repository +git clone https://github.com/arrhes/arrhes.git +cd arrhes + +# Installer les dépendances +pnpm install + +# Configurer les variables d'environnement +cp packages/api/.env.example packages/api/.env +cp packages/tools/.env.example packages/tools/.env +# Éditer les fichiers .env avec vos valeurs + +# Initialiser la base de données +pnpm --filter tools run push +pnpm --filter tools run seed +# Lancer l'application +pnpm run dev +``` + +L'API sera accessible sur le port configuré (par défaut `http://localhost:3000`) et la plateforme sur `http://localhost:5173`. + +**Identifiants de démonstration :** `demo@arrhes.com` / `demo` + +## Documentation + +- 📚 [Architecture](docs/ARCHITECTURE.md) - Vue d'ensemble de l'architecture et du stack technique +- ⚙️ [Configuration](docs/CONFIGURATION.md) - Variables d'environnement et configuration des services +- 🛠️ [Développement](docs/DEVELOPMENT.md) - Guide complet pour les développeurs +- 🤝 [Contribution](docs/CONTRIBUTING.md) - Guidelines pour contribuer au projet ## Packages -- API -- metadata -- platform -- tools +Le projet est organisé en monorepo avec les packages suivants : + +- **@arrhes/api** - Backend REST API (Hono, PostgreSQL) +- **@arrhes/platform** - Interface web (React, TanStack Router) +- **@arrhes/metadata** - Schémas et modèles partagés (Valibot, Drizzle ORM) +- **@arrhes/tools** - Outils de migration et seed de base de données +- **@arrhes/website** - Site vitrine + +Pour plus de détails, consultez la [documentation d'architecture](docs/ARCHITECTURE.md). + +## Licence + +Ce projet est sous licence MIT. Voir le fichier [LICENSE](LICENSE) pour plus de détails. + +## Support + +- 🐛 [Signaler un bug](https://github.com/arrhes/arrhes/issues) +- 💡 [Proposer une fonctionnalité](https://github.com/arrhes/arrhes/issues) +- 📧 Contact : demo@arrhes.com + +--- + +Développé avec ❤️ pour la communauté française diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..816644f --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,537 @@ +# Architecture + +Ce document décrit l'architecture globale du projet Arrhes, un système de comptabilité en partie double pour associations et entreprises françaises. + +## Table des matières + +- [Vue d'ensemble](#vue-densemble) +- [Architecture monorepo](#architecture-monorepo) +- [Packages](#packages) +- [Stack technique](#stack-technique) +- [Flux de données](#flux-de-données) +- [Authentification](#authentification) +- [Base de données](#base-de-données) + +## Vue d'ensemble + +Arrhes est construit sur une architecture monorepo moderne utilisant **pnpm workspaces**. Le projet est divisé en plusieurs packages indépendants mais interconnectés, chacun ayant une responsabilité spécifique. + +``` +┌─────────────────────────────────────────────────────────┐ +│ Utilisateurs │ +└────────────────────────────┬────────────────────────────┘ + │ + ┌──────────▼──────────┐ + │ @arrhes/platform │ (Frontend React) + │ Port: 5173 │ + └──────────┬──────────┘ + │ + │ HTTP/REST + │ + ┌──────────▼──────────┐ + │ @arrhes/api │ (Backend Hono) + │ Port: 3000 │ + └──────────┬──────────┘ + │ + ┌───────────┼───────────┐ + │ │ │ + ┌────▼────┐ ┌───▼────┐ ┌───▼────┐ + │ DB │ │ S3 │ │ SMTP │ + │ (SQL) │ │ (File) │ │ (Mail) │ + └─────────┘ └────────┘ └────────┘ +``` + +## Architecture monorepo + +Le projet utilise **pnpm workspaces** pour gérer plusieurs packages dans un seul repository. Cette approche offre plusieurs avantages : + +- **Partage de code** : Les packages peuvent facilement partager du code via `@arrhes/metadata` +- **Dépendances optimisées** : pnpm déduplique les dépendances communes +- **Développement simplifié** : Build et développement coordonnés entre packages +- **Versioning cohérent** : Toutes les parties du projet évoluent ensemble + +### Structure du workspace + +``` +arrhes/ +├── packages/ +│ ├── api/ # Backend API +│ ├── platform/ # Interface utilisateur +│ ├── metadata/ # Schémas et types partagés +│ ├── tools/ # Outils de migration DB +│ └── website/ # Site vitrine +├── pnpm-workspace.yaml +└── package.json +``` + +## Packages + +### @arrhes/api + +**Rôle :** Backend REST API pour toutes les opérations métier + +**Technologies :** +- **Hono** : Framework web léger et performant +- **TypeScript** : Typage statique +- **Drizzle ORM** : ORM pour PostgreSQL +- **Valibot** : Validation des données +- **Nodemailer** : Envoi d'emails +- **AWS SDK** : Stockage de fichiers (S3-compatible) +- **Puppeteer** : Génération de PDF + +**Structure :** +``` +api/src/ +├── api.ts # Configuration de l'app Hono +├── server.ts # Point d'entrée du serveur +├── clients/ # Clients pour services externes +│ ├── sqlClient.ts +│ ├── emailClient.ts +│ └── storageClient.ts +├── factories/ # Factories Hono avec types +│ ├── apiFactory.ts +│ ├── authFactory.ts +│ └── publicFactory.ts +├── middlewares/ # Middlewares d'authentification +│ ├── authMiddleware.ts +│ ├── publicMiddleware.ts +│ └── userVerificationMiddleware.ts +├── routes/ # Routes de l'API +│ ├── auth/ # Routes authentifiées +│ │ ├── organizations/ # Gestion organisations +│ │ ├── settings/ # Paramètres utilisateur +│ │ └── support/ # Support +│ └── public/ # Routes publiques +│ ├── signIn.ts +│ ├── signUp.ts +│ ├── signOut.ts +│ └── sendMagicLink.ts +└── utilities/ # Utilitaires + ├── email/ # Templates et envoi emails + ├── sql/ # Helpers SQL + ├── storage/ # Helpers S3 + ├── cookies/ # Gestion cookies sécurisés + └── workspace/ # Logique métier +``` + +**Points d'entrée :** +- `server.ts` : Lance le serveur HTTP +- `api.ts` : Configure l'application Hono avec middlewares et routes + +**Responsabilités :** +- Gestion de l'authentification (magic links, sessions) +- CRUD pour toutes les entités (organisations, comptes, écritures, etc.) +- Validation des écritures comptables +- Génération des états financiers +- Gestion des pièces justificatives (upload/download via S3) +- Envoi d'emails transactionnels + +### @arrhes/platform + +**Rôle :** Interface utilisateur web pour interagir avec l'application + +**Technologies :** +- **React 19** : Framework UI +- **TanStack Router** : Routing type-safe +- **TanStack Query** : Gestion d'état serveur et cache +- **TanStack Table** : Tableaux de données performants +- **TanStack Virtual** : Virtualisation pour grandes listes +- **Radix UI** : Composants accessibles headless +- **Tailwind CSS** : Framework CSS utility-first +- **React Hook Form** : Gestion de formulaires +- **Valibot** : Validation côté client +- **Vite** : Build tool et dev server + +**Structure :** +``` +platform/src/ +├── root.tsx # Point d'entrée React +├── index.html # HTML principal +├── assets/ # Ressources statiques +│ ├── css/ +│ ├── fonts/ +│ ├── images/ +│ └── manifest/ # PWA manifest +├── components/ # Composants réutilisables +│ ├── buttons/ +│ ├── formats/ # Formatage de données +│ ├── forms/ +│ ├── inputs/ +│ ├── layouts/ +│ └── overlays/ # Modals, dropdowns, tooltips +├── contexts/ # Contexts React +│ ├── data/ # Context de données globales +│ ├── router/ # Configuration du router +│ └── toasts/ # Notifications +├── features/ # Features par domaine métier +│ ├── authLayout.tsx +│ ├── organizations/ # Gestion organisations +│ ├── settings/ +│ ├── signIn/ +│ ├── signUp/ +│ └── support/ +├── routes/ # Définition des routes +│ ├── platformRouter.tsx +│ ├── platformTree.ts +│ └── root/ # Routes de l'app +└── utilities/ # Utilitaires + ├── postAPI.ts # Client API + ├── useHTTPData.ts # Hook pour data fetching + └── cookies/ # Gestion cookies +``` + +**Responsabilités :** +- Interface utilisateur complète +- Formulaires de saisie avec validation +- Tableaux de données avec tri, filtrage, pagination +- Visualisation des états financiers +- Gestion des documents et pièces justificatives +- Notifications et retours utilisateur + +### @arrhes/metadata + +**Rôle :** Package partagé contenant tous les schémas, modèles et types utilisés par l'API et la plateforme + +**Technologies :** +- **Drizzle ORM** : Définition des schémas de base de données +- **Valibot** : Schémas de validation +- **TypeScript** : Types partagés + +**Structure :** +``` +metadata/src/ +├── models/ # Modèles Drizzle ORM +│ ├── user.ts +│ ├── organization.ts +│ ├── account.ts +│ ├── journal.ts +│ ├── record.ts # Écritures comptables +│ ├── recordRow.ts # Lignes d'écriture +│ ├── document.ts +│ ├── attachment.ts +│ ├── year.ts +│ ├── balanceSheet.ts +│ ├── incomeStatement.ts +│ └── computation.ts +├── schemas/ # Schémas Valibot pour validation +│ └── [mêmes fichiers que models/] +├── routes/ # Définitions de routes typées +│ ├── auth/ +│ └── public/ +├── components/ # Composants métier partagés +│ ├── models/ +│ ├── schemas/ +│ └── values/ # Valeurs par défaut et constantes +└── utilities/ # Utilitaires + ├── generate.ts + ├── generateId.ts + └── routeDefinition.ts +``` + +**Exports :** +```typescript +// Utilisable par l'API et la plateforme +import { models } from '@arrhes/metadata/models' +import { schemas } from '@arrhes/metadata/schemas' +import { routes } from '@arrhes/metadata/routes' +import { generateId } from '@arrhes/metadata/utilities' +``` + +**Responsabilités :** +- Définition unique des schémas de base de données +- Validation cohérente des données entre frontend et backend +- Types TypeScript partagés +- Génération d'IDs uniques (nanoid) +- Définitions de routes type-safe + +### @arrhes/tools + +**Rôle :** Outils de gestion de la base de données (migrations, seed, maintenance) + +**Technologies :** +- **Drizzle Kit** : CLI pour migrations +- **tsx** : Exécution TypeScript +- **Postgres** : Client PostgreSQL + +**Scripts disponibles :** +```bash +# Générer les migrations depuis le schéma +pnpm --filter tools run generate + +# Pousser le schéma directement vers la DB +pnpm --filter tools run push + +# Appliquer les migrations +pnpm --filter tools run migrate + +# Seed avec données de démonstration +pnpm --filter tools run seed + +# Vider la base de données +pnpm --filter tools run clear + +# Reset complet (clear + push + seed) +pnpm --filter tools run reset + +# Supprimer les migrations +pnpm --filter tools run drop +``` + +**Structure :** +``` +tools/src/ +├── env.ts # Configuration environnement +├── schemas.ts # Import des schémas metadata +├── migrate.ts # Script de migration +├── clearDB.ts # Script de nettoyage +└── seed/ # Scripts de seed + ├── seed.ts # Seed principal + ├── migration.ts # Migrations de données + ├── records2022.ts # Données exemple 2022 + └── records2023.ts # Données exemple 2023 +``` + +**Responsabilités :** +- Gestion du schéma de base de données +- Migrations de structure et de données +- Génération de données de test +- Maintenance de la base de données + +### @arrhes/website + +**Rôle :** Site vitrine pour présenter l'application + +**Technologies :** +- **React** : Framework UI +- **Vite** : Build tool + +**Note :** Package actuellement minimal, prévu pour évoluer en site marketing/landing page. + +## Stack technique + +### Backend (API) + +| Composant | Technologie | Rôle | +|-----------|-------------|------| +| Runtime | Node.js 24.5+ | Environnement d'exécution | +| Language | TypeScript 5.9 | Langage de programmation | +| Framework | Hono 4.9 | Framework web minimaliste | +| ORM | Drizzle 0.44 | Mapping objet-relationnel | +| Validation | Valibot 1.1 | Validation de schémas | +| Database | PostgreSQL | Base de données relationnelle | +| Storage | AWS S3 SDK | Stockage de fichiers | +| Email | Nodemailer 7.0 | Envoi d'emails | +| PDF | Puppeteer 24.22 | Génération de PDF | + +### Frontend (Platform) + +| Composant | Technologie | Rôle | +|-----------|-------------|------| +| Framework | React 19.1 | UI framework | +| Routing | TanStack Router 1.132 | Routing type-safe | +| State | TanStack Query 5.90 | Server state management | +| Tables | TanStack Table 8.21 | Data tables | +| Virtual | TanStack Virtual 3.13 | Virtualisation listes | +| UI | Radix UI | Composants accessibles | +| Styling | Tailwind CSS 4.1 | CSS utility-first | +| Forms | React Hook Form 7.63 | Gestion de formulaires | +| Validation | Valibot 1.1 | Validation client-side | +| Icons | Tabler Icons 3.35 | Icônes | +| Build | Vite 7.1 | Build tool moderne | + +### Tooling + +| Outil | Version | Rôle | +|-------|---------|------| +| pnpm | Latest | Package manager | +| TypeScript | 5.9 | Compilateur TypeScript | +| ESLint | 9.36 | Linter JavaScript/TypeScript | +| Drizzle Kit | 0.31 | Migrations de base de données | +| tsx | 4.20 | Exécution TypeScript | + +## Flux de données + +### Authentification par Magic Link + +``` +1. Utilisateur entre son email + └─> POST /api/public/sendMagicLink + └─> Génération token + envoi email + +2. Utilisateur clique sur le lien + └─> GET /api/public/signIn?token=xxx + └─> Validation token + └─> Création session + └─> Cookie sécurisé (httpOnly, signed) + └─> Redirection vers plateforme + +3. Requêtes authentifiées + └─> Cookie envoyé automatiquement + └─> authMiddleware vérifie session + └─> Accès aux routes protégées +``` + +### CRUD standard + +``` +Platform API Database +──────────────────────────────────────────────────────────── +1. User action + └─> postAPI() + └─> POST /api/auth/... + └─> authMiddleware + └─> Validation données (Valibot) + └─> Drizzle ORM + └─> SQL Query + └─> PostgreSQL + +2. Response + ┌─ JSON + └─ TanStack Query cache + └─ Invalidation automatique + └─ Re-fetch et mise à jour UI +``` + +### Upload de fichiers + +``` +1. Sélection fichier + └─> Demande URL signée PUT + └─> POST /api/auth/.../generatePutSignedUrl + └─> S3 génère URL temporaire (expires 15min) + +2. Upload direct vers S3 + └─> PUT https://s3.../file + (pas de passage par l'API) + +3. Sauvegarde référence + └─> POST /api/auth/.../attachment + └─> Stocke storageKey en DB +``` + +### Download de fichiers + +``` +1. Demande URL signée GET + └─> POST /api/auth/.../generateGetSignedUrl + └─> S3 génère URL temporaire (expires 1h) + +2. Download direct depuis S3 + └─> GET https://s3.../file + (pas de passage par l'API) +``` + +## Authentification + +### Stratégie + +Arrhes utilise une **authentification par magic link** (lien temporaire envoyé par email) combinée à des **sessions persistantes** côté serveur. + +### Flow complet + +1. **Inscription** (`/api/public/signUp`) + - Validation email + alias + - Hash du mot de passe (PBKDF2, 128000 itérations) + - Création user + - Envoi email de vérification + +2. **Connexion** (`/api/public/sendMagicLink`) + - Génération token de vérification unique + - Stockage temporaire en DB + - Envoi email avec lien + +3. **Validation** (`/api/public/signIn`) + - Vérification du token + - Création d'une session + - Cookie signé et httpOnly + - Redirection vers l'application + +4. **Requêtes authentifiées** + - Cookie envoyé automatiquement + - `authMiddleware` vérifie la session + - Charge l'utilisateur en contexte + - Vérifie l'appartenance à l'organisation si nécessaire + +5. **Déconnexion** (`/api/public/signOut`) + - Suppression de la session en DB + - Suppression du cookie + +### Sécurité + +- **Cookies signés** : Vérification de l'intégrité avec `COOKIES_KEY` +- **httpOnly** : Protection contre XSS +- **sameSite** : Protection contre CSRF +- **CORS configuré** : Origine autorisée uniquement +- **Tokens temporaires** : Expiration des magic links +- **Hashing sécurisé** : PBKDF2 avec salt unique par utilisateur + +## Base de données + +### Schéma principal + +Le schéma PostgreSQL contient les tables suivantes (via Drizzle ORM) : + +**Utilisateurs et organisations :** +- `user` : Utilisateurs de l'application +- `organization` : Organisations (entreprises/associations) +- `organizationUser` : Relation many-to-many avec rôles +- `userSession` : Sessions actives + +**Comptabilité :** +- `year` : Exercices comptables +- `account` : Plan comptable +- `journal` : Journaux comptables +- `record` : Écritures comptables +- `recordRow` : Lignes d'écriture (débit/crédit) +- `document` : Documents comptables +- `attachment` : Pièces justificatives + +**États financiers :** +- `balanceSheet` : Configuration du bilan +- `incomeStatement` : Configuration du compte de résultat +- `computation` : Calculs personnalisés +- `computationIncomeStatement` : Relation calculs/compte de résultat + +### Relations clés + +``` +organization 1──n organizationUser n──1 user + │ + ├── 1──n year + ├── 1──n account + ├── 1──n journal + └── 1──n document + │ + └── 1──n record + │ + └── 1──n recordRow + │ + └── n──1 account +``` + +### Migrations + +Les migrations sont gérées par **Drizzle Kit** : +- Le schéma source est défini dans `@arrhes/metadata` +- Drizzle Kit génère automatiquement les migrations SQL +- Application via `drizzle-kit migrate` ou `push` (dev) + +## Diagramme de dépendances + +``` +@arrhes/platform ──depends on──> @arrhes/metadata + ▲ + │ +@arrhes/api ──depends on───────────┘ + ▲ + │ +@arrhes/tools ──depends on───────────┘ + +@arrhes/website (indépendant) +``` + +Tous les packages dépendent de `@arrhes/metadata` pour partager les schémas, modèles et types. Cette architecture assure une cohérence totale entre le frontend et le backend. + +--- + +Pour plus d'informations sur la configuration, consultez [CONFIGURATION.md](CONFIGURATION.md). diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md new file mode 100644 index 0000000..888e3a6 --- /dev/null +++ b/docs/CONFIGURATION.md @@ -0,0 +1,369 @@ +# Configuration + +Ce document décrit toutes les variables d'environnement et les configurations nécessaires pour faire fonctionner Arrhes en développement local. + +## Table des matières + +- [Vue d'ensemble](#vue-densemble) +- [Variables d'environnement - API](#variables-denvironnement---api) +- [Variables d'environnement - Tools](#variables-denvironnement---tools) +- [Configuration PostgreSQL](#configuration-postgresql) +- [Configuration S3 (Stockage)](#configuration-s3-stockage) +- [Configuration SMTP (Email)](#configuration-smtp-email) +- [Exemples de configuration](#exemples-de-configuration) +- [Sécurité](#sécurité) + +## Vue d'ensemble + +Arrhes nécessite deux fichiers de configuration `.env` : + +1. **`packages/api/.env`** : Configuration du backend API +2. **`packages/tools/.env`** : Configuration des outils de base de données + +Ces fichiers ne sont **pas versionnés** (`.gitignore`) pour des raisons de sécurité. + +## Variables d'environnement - API + +Fichier : `packages/api/.env` + +### Environnement général + +| Variable | Type | Description | Exemple | +|----------|------|-------------|---------| +| `ENV` | `"development"` \| `"production"` | Environnement d'exécution | `development` | +| `VERBOSE` | `"true"` \| `"false"` | Mode verbeux (logs détaillés) | `true` | +| `PORT` | `string` | Port d'écoute du serveur | `3000` | + +### CORS et Cookies + +| Variable | Type | Description | Exemple | +|----------|------|-------------|---------| +| `CORS_ORIGIN` | `string` | Origines autorisées (séparées par virgule) | `http://localhost:5173` | +| `COOKIES_DOMAIN` | `string` | Domaine des cookies | `localhost` | +| `COOKIES_KEY` | `string` | Clé secrète pour signer les cookies (min 32 chars) | `your-super-secret-key-min-32-characters-long` | + +### URLs des services + +| Variable | Type | Description | Exemple | +|----------|------|-------------|---------| +| `API_BASE_URL` | `string` | URL de base de l'API | `http://localhost:3000` | +| `PLATFORM_BASE_URL` | `string` | URL de la plateforme frontend | `http://localhost:5173` | +| `WEBSITE_BASE_URL` | `string` | URL du site vitrine | `http://localhost:5174` | + +### Base de données + +| Variable | Type | Description | Exemple | +|----------|------|-------------|---------| +| `SQL_DATABASE_URL` | `string` | URL de connexion PostgreSQL | `postgres://user:password@localhost:5432/arrhes` | + +### Stockage S3 + +| Variable | Type | Description | Exemple | +|----------|------|-------------|---------| +| `STORAGE_ENDPOINT` | `string` | Endpoint S3 (ou compatible) | `http://localhost:9000` (MinIO) | +| `STORAGE_NAME` | `string` | Nom du bucket S3 | `arrhes-files` | +| `STORAGE_ACCESS_KEY` | `string` | Clé d'accès S3 | `minioadmin` | +| `STORAGE_SECRET_KEY` | `string` | Clé secrète S3 | `minioadmin` | + +### Email SMTP + +| Variable | Type | Description | Exemple | +|----------|------|-------------|---------| +| `EMAIL_ENDPOINT` | `string` | Serveur SMTP | `smtp.gmail.com` | +| `EMAIL_USER` | `string` | Utilisateur SMTP | `your-email@gmail.com` | +| `EMAIL_PASSWORD` | `string` | Mot de passe ou app password SMTP | `your-app-password` | + +## Variables d'environnement - Tools + +Fichier : `packages/tools/.env` + +| Variable | Type | Description | Exemple | +|----------|------|-------------|---------| +| `DATABASE_URL` | `string` | URL de connexion PostgreSQL | `postgres://user:password@localhost:5432/arrhes` | + +**Note :** Cette variable doit être identique à `SQL_DATABASE_URL` de l'API. + +## Configuration PostgreSQL + +### Installation + +**Ubuntu/Debian :** +```bash +sudo apt update +sudo apt install postgresql postgresql-contrib +``` + +**macOS (Homebrew) :** +```bash +brew install postgresql@16 +brew services start postgresql@16 +``` + +**Windows :** +Télécharger l'installeur depuis [postgresql.org](https://www.postgresql.org/download/windows/) + +### Création de la base de données + +```bash +# Se connecter à PostgreSQL +sudo -u postgres psql + +# Créer un utilisateur +CREATE USER arrhes_user WITH PASSWORD 'your-secure-password'; + +# Créer la base de données +CREATE DATABASE arrhes OWNER arrhes_user; + +# Donner tous les privilèges +GRANT ALL PRIVILEGES ON DATABASE arrhes TO arrhes_user; + +# Quitter +\q +``` + +### URL de connexion + +Format : `postgres://[user]:[password]@[host]:[port]/[database]` + +Exemple : `postgres://arrhes_user:your-secure-password@localhost:5432/arrhes` + +### Vérification de la connexion + +```bash +psql postgres://arrhes_user:your-secure-password@localhost:5432/arrhes +``` + +## Configuration S3 (Stockage) + +Le système de stockage utilise l'API AWS S3 mais fonctionne avec n'importe quel service compatible S3. + +### Option 1 : MinIO (Développement local recommandé) + +**Installation avec Docker :** +```bash +docker run -d \ + -p 9000:9000 \ + -p 9001:9001 \ + --name minio \ + -e "MINIO_ROOT_USER=minioadmin" \ + -e "MINIO_ROOT_PASSWORD=minioadmin" \ + -v ~/minio/data:/data \ + quay.io/minio/minio server /data --console-address ":9001" +``` + +**Configuration :** +```env +STORAGE_ENDPOINT=http://localhost:9000 +STORAGE_NAME=arrhes-files +STORAGE_ACCESS_KEY=minioadmin +STORAGE_SECRET_KEY=minioadmin +``` + +**Création du bucket :** +1. Accéder à la console MinIO : http://localhost:9001 +2. Se connecter avec `minioadmin` / `minioadmin` +3. Créer un bucket nommé `arrhes-files` +4. Configurer la politique en lecture/écriture si nécessaire + +### Option 2 : AWS S3 (Production) + +**Configuration :** +```env +STORAGE_ENDPOINT=https://s3.eu-west-3.amazonaws.com +STORAGE_NAME=your-bucket-name +STORAGE_ACCESS_KEY=YOUR_AWS_ACCESS_KEY +STORAGE_SECRET_KEY=YOUR_AWS_SECRET_KEY +``` + +**Prérequis :** +- Créer un bucket S3 dans votre région +- Créer un utilisateur IAM avec les permissions S3 appropriées +- Générer des clés d'accès pour cet utilisateur + +### Option 3 : Autre service compatible S3 + +Cloudflare R2, DigitalOcean Spaces, Scaleway Object Storage, etc. sont également compatibles. + +## Configuration SMTP (Email) + +L'application envoie des emails pour : +- Magic links d'authentification +- Notifications importantes +- Invitations d'utilisateurs + +### Option 1 : Gmail (Développement) + +**Configuration :** +```env +EMAIL_ENDPOINT=smtp.gmail.com +EMAIL_USER=your-email@gmail.com +EMAIL_PASSWORD=your-app-specific-password +``` + +**Étapes :** +1. Activer l'authentification à deux facteurs sur votre compte Google +2. Générer un "mot de passe d'application" : https://myaccount.google.com/apppasswords +3. Utiliser ce mot de passe dans `EMAIL_PASSWORD` + +### Option 2 : Services SMTP dédiés + +**Brevo (ex-Sendinblue) :** +```env +EMAIL_ENDPOINT=smtp-relay.brevo.com +EMAIL_USER=your-email@example.com +EMAIL_PASSWORD=your-smtp-key +``` + +**SendGrid :** +```env +EMAIL_ENDPOINT=smtp.sendgrid.net +EMAIL_USER=apikey +EMAIL_PASSWORD=your-sendgrid-api-key +``` + +**Mailgun :** +```env +EMAIL_ENDPOINT=smtp.mailgun.org +EMAIL_USER=postmaster@your-domain.mailgun.org +EMAIL_PASSWORD=your-smtp-password +``` + +### Option 3 : Serveur SMTP local (Test) + +Pour tester sans envoyer de vrais emails, utilisez [MailHog](https://github.com/mailhog/MailHog) : + +```bash +# Avec Docker +docker run -d -p 1025:1025 -p 8025:8025 mailhog/mailhog +``` + +```env +EMAIL_ENDPOINT=localhost:1025 +EMAIL_USER=test +EMAIL_PASSWORD=test +``` + +Interface web disponible sur http://localhost:8025 + +## Exemples de configuration + +### Configuration complète - Développement local + +**`packages/api/.env` :** +```env +# Environnement +ENV=development +VERBOSE=true +PORT=3000 + +# CORS et Cookies +CORS_ORIGIN=http://localhost:5173 +COOKIES_DOMAIN=localhost +COOKIES_KEY=my-super-secret-development-key-at-least-32-chars + +# URLs +API_BASE_URL=http://localhost:3000 +PLATFORM_BASE_URL=http://localhost:5173 +WEBSITE_BASE_URL=http://localhost:5174 + +# Base de données +SQL_DATABASE_URL=postgres://arrhes_user:arrhes_password@localhost:5432/arrhes + +# Stockage MinIO +STORAGE_ENDPOINT=http://localhost:9000 +STORAGE_NAME=arrhes-files +STORAGE_ACCESS_KEY=minioadmin +STORAGE_SECRET_KEY=minioadmin + +# Email (MailHog pour test) +EMAIL_ENDPOINT=localhost:1025 +EMAIL_USER=test +EMAIL_PASSWORD=test +``` + +**`packages/tools/.env` :** +```env +DATABASE_URL=postgres://arrhes_user:arrhes_password@localhost:5432/arrhes +``` + +### Configuration avec services externes + +**`packages/api/.env` :** +```env +# Environnement +ENV=development +VERBOSE=true +PORT=3000 + +# CORS et Cookies +CORS_ORIGIN=http://localhost:5173 +COOKIES_DOMAIN=localhost +COOKIES_KEY=generate-a-strong-random-key-here-minimum-32-characters + +# URLs +API_BASE_URL=http://localhost:3000 +PLATFORM_BASE_URL=http://localhost:5173 +WEBSITE_BASE_URL=http://localhost:5174 + +# Base de données (PostgreSQL hébergé) +SQL_DATABASE_URL=postgres://user:pass@db.provider.com:5432/arrhes + +# Stockage AWS S3 +STORAGE_ENDPOINT=https://s3.eu-west-3.amazonaws.com +STORAGE_NAME=my-arrhes-bucket +STORAGE_ACCESS_KEY=AKIAIOSFODNN7EXAMPLE +STORAGE_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY + +# Email (Gmail) +EMAIL_ENDPOINT=smtp.gmail.com +EMAIL_USER=myemail@gmail.com +EMAIL_PASSWORD=abcd efgh ijkl mnop +``` + +## Sécurité + +### Bonnes pratiques + +1. **Ne jamais commiter les fichiers `.env`** + - Vérifiez que `.env` est dans `.gitignore` + - Utilisez des templates `.env.example` sans valeurs sensibles + +2. **Générer des secrets forts** + ```bash + # Générer une clé aléatoire pour COOKIES_KEY + openssl rand -base64 32 + ``` + +3. **Permissions de fichiers** + ```bash + # Restreindre l'accès aux fichiers .env + chmod 600 packages/api/.env + chmod 600 packages/tools/.env + ``` + +4. **Variables séparées par environnement** + - Dev : `.env.development` + - Production : `.env.production` + - Ne jamais mélanger les credentials + +5. **Rotation des secrets** + - Changez régulièrement `COOKIES_KEY` + - Renouvelez les clés API et mots de passe + - Révoquez les accès inutilisés + +### Vérification de la configuration + +Pour vérifier que toutes les variables sont correctement définies, l'API affichera une erreur au démarrage si des variables sont manquantes ou invalides (validation via Valibot dans `getEnv.ts`). + +### Valeurs recommandées + +| Variable | Recommandation | +|----------|----------------| +| `COOKIES_KEY` | Minimum 32 caractères aléatoires | +| `SQL_DATABASE_URL` | Connexion SSL en production (`?sslmode=require`) | +| `STORAGE_*` | Credentials avec permissions minimales (lecture/écriture bucket uniquement) | +| `EMAIL_*` | Utiliser des app passwords, pas le mot de passe principal | + +--- + +Pour poursuivre l'installation, consultez [DEVELOPMENT.md](DEVELOPMENT.md). diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..0ba7cd9 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,520 @@ +# Guide de contribution + +Merci de votre intérêt pour contribuer à Arrhes ! Ce document explique comment participer au développement du projet. + +## Table des matières + +- [Code de conduite](#code-de-conduite) +- [Comment contribuer](#comment-contribuer) +- [Configuration de l'environnement](#configuration-de-lenvironnement) +- [Standards de code](#standards-de-code) +- [Convention de commits](#convention-de-commits) +- [Process de pull request](#process-de-pull-request) +- [Tests](#tests) +- [Code review](#code-review) +- [Signaler un bug](#signaler-un-bug) +- [Proposer une fonctionnalité](#proposer-une-fonctionnalité) + +## Code de conduite + +En participant à ce projet, vous vous engagez à maintenir un environnement respectueux et inclusif. Nous attendons de tous les contributeurs : + +- Respect et courtoisie envers les autres contributeurs +- Ouverture d'esprit face aux critiques constructives +- Concentration sur ce qui est le mieux pour la communauté +- Empathie envers les autres membres de la communauté + +Les comportements inacceptables incluent le harcèlement, les insultes, et tout comportement discriminatoire. + +## Comment contribuer + +Il existe plusieurs façons de contribuer à Arrhes : + +### 🐛 Signaler des bugs +Ouvrez une issue sur GitHub avec le label `bug` + +### 💡 Proposer des fonctionnalités +Ouvrez une issue sur GitHub avec le label `enhancement` + +### 📝 Améliorer la documentation +La documentation est aussi importante que le code ! + +### 💻 Contribuer du code +Suivez le process décrit dans ce document + +### 🌍 Traductions +Aidez à traduire l'application dans d'autres langues + +### 🎨 Design et UX +Proposez des améliorations d'interface + +## Configuration de l'environnement + +Avant de commencer à contribuer, configurez votre environnement de développement : + +1. **Fork le repository** sur votre compte GitHub + +2. **Cloner votre fork** + ```bash + git clone https://github.com/votre-username/arrhes.git + cd arrhes + ``` + +3. **Ajouter le repository principal comme remote** + ```bash + git remote add upstream https://github.com/arrhes/arrhes.git + ``` + +4. **Installer les dépendances** + ```bash + pnpm install + ``` + +5. **Configurer l'environnement** + Suivez les instructions dans [DEVELOPMENT.md](DEVELOPMENT.md) + +6. **Créer une branche pour votre contribution** + ```bash + git checkout -b feature/ma-fonctionnalite + # ou + git checkout -b fix/mon-correctif + ``` + +## Standards de code + +### TypeScript + +- **Utiliser TypeScript strict** : Pas de `any`, sauf exception justifiée +- **Typage explicite** pour les fonctions publiques +- **Interfaces vs Types** : Préférer `type` pour les objets simples, `interface` pour l'extension + +**Bon exemple :** +```typescript +type User = { + id: string + email: string + alias: string +} + +function createUser(data: { email: string, alias: string }): User { + return { + id: generateId(), + ...data, + } +} +``` + +**Mauvais exemple :** +```typescript +function createUser(data: any) { // ❌ any + return { + id: generateId(), + ...data, + } +} +``` + +### Naming conventions + +- **Variables et fonctions** : `camelCase` +- **Types et interfaces** : `PascalCase` +- **Constantes** : `UPPER_SNAKE_CASE` (si vraiment constante) +- **Fichiers** : `camelCase.ts` +- **Composants React** : `PascalCase.tsx` + +```typescript +// Variables et fonctions +const userName = 'John' +function getUserById(id: string) { } + +// Types +type UserProfile = { } +interface ApiResponse { } + +// Constantes +const MAX_RETRY_COUNT = 3 + +// Fichiers +// api/routes/auth/userProfile.ts +// platform/components/buttons/PrimaryButton.tsx +``` + +### Structure du code + +**Ordre des imports :** +```typescript +// 1. Imports de packages externes +import { Hono } from 'hono' +import * as v from 'valibot' + +// 2. Imports de workspace packages +import { models } from '@arrhes/metadata/models' +import { schemas } from '@arrhes/metadata/schemas' + +// 3. Imports relatifs du package actuel +import { authFactory } from '#/factories/authFactory.js' +import { validate } from '#/utilities/validate.js' +``` + +**Ordre dans les fichiers :** +```typescript +// 1. Imports +import { ... } from '...' + +// 2. Types et interfaces +type MyType = { } + +// 3. Constantes +const MY_CONSTANT = 'value' + +// 4. Fonctions/composants +export function myFunction() { } + +// 5. Export par défaut (si applicable) +export default MyComponent +``` + +### ESLint + +Le projet utilise ESLint pour maintenir la qualité du code. + +**Vérifier le linting :** +```bash +pnpm --filter platform run lint +``` + +**Fix automatique :** +```bash +pnpm --filter platform run lint --fix +``` + +**Configuration :** +- ESLint est configuré pour TypeScript et React +- Les règles sont définies dans `packages/platform/eslint.config.js` + +### Formatage + +**Indentation :** 4 espaces (pas de tabs) + +**Longueur de ligne :** Pas de limite stricte, mais restez raisonnable (~120 caractères) + +**Points-virgules :** Non requis (sauf cas spécifiques) + +**Quotes :** Simples `'` ou doubles `"` (soyez cohérent dans un fichier) + +**Trailing commas :** Oui pour les objets et arrays multilignes + +```typescript +const user = { + id: '123', + name: 'John', + email: 'john@example.com', // trailing comma +} +``` + +### React + +**Composants fonctionnels uniquement** +```typescript +export function MyComponent() { + return
Exemple : {props.title}
+ )} +{props.label}
++ {props.children} +
+ ) +} diff --git a/packages/dashboard/src/components/document/docSection.tsx b/packages/dashboard/src/components/document/docSection.tsx new file mode 100644 index 0000000..4cd5df8 --- /dev/null +++ b/packages/dashboard/src/components/document/docSection.tsx @@ -0,0 +1,23 @@ +import { css } from "../../utilities/cn.js" + + +export function DocSection(props: { + title: string + children: React.ReactNode +}) { + return ( +| + {header} + | + ))} +
|---|
| + {cell} + | + ))} +
- {body} -
- ) -}) +import { css, cx } from "../../utilities/cn.js" +import { forwardRef } from "react" +import { useFormField } from "./useFormField.js" + + +export const FormError = forwardRef< + HTMLParagraphElement, + React.HTMLAttributes+ {body} +
+ ) +}) diff --git a/packages/dashboard/src/components/forms/formItem.tsx b/packages/dashboard/src/components/forms/formItem.tsx index 25fe3ef..da9dc82 100644 --- a/packages/dashboard/src/components/forms/formItem.tsx +++ b/packages/dashboard/src/components/forms/formItem.tsx @@ -1,19 +1,29 @@ -import { cn } from "#/utilities/cn.js" -import { HTMLAttributes, useId } from "react" -import { FormItemContext } from "./formItemContext.js" - - -type FormItem = HTMLAttributes