Skip to content

README.md

Latest commit

 

History

History
328 lines (243 loc) · 13.8 KB

README.md

File metadata and controls

328 lines (243 loc) · 13.8 KB
Raw

Piloti

Application de gestion du matériel pour un groupe scout SGDF. Inventaire, prêts, incidents, tableau de bord — interface entièrement en français.

Stack : Next.js 16 (App Router) · React 19 · TypeScript strict · Tailwind v4 · Prisma 7 · SQLite · better-auth

Licence : GNU AGPL v3 ou ultérieure — logiciel libre.

Démarrage rapide (développement)

1. Prérequis

  • Node.js 22+
  • pnpm 11+ — si absent : corepack enable && corepack prepare pnpm@latest --activate

2. Cloner et installer

git clone <url-du-repo>
cd piloti
pnpm install

3. Variables d'environnement

cp .env.example .env

Éditer .env : les valeurs par défaut suffisent pour le développement local. Seule BETTER_AUTH_SECRET doit être changée (voir le fichier .env.example).

4. Base de données

pnpm db:migrate    # Crée dev.db et applique toutes les migrations
pnpm db:seed       # Peuple avec des données de test (optionnel)

5. Lancer

pnpm dev           # http://localhost:3000

Premier lancement sans seed : l'application redirige automatiquement vers /setup pour créer le compte administrateur (comme n8n). Pas besoin de seed en production.

Avec seed — tous les comptes factices partagent le même mot de passe : celui de la variable d'environnement SEED_PASSWORD (sinon un mot de passe aléatoire, affiché en fin de pnpm db:seed). Comptes de test disponibles (liste non exhaustive — un chef par branche et douze familles supplémentaires sont aussi générés) :

Email Rôle(s) Statut Connexion
admin@piloti.fr Admin Actif Oui
thomas.martin@example.invalid Chef (Pionniers) Actif Oui
julie.bernard@example.invalid Chef (Scouts) Actif Oui
paul.durand@example.invalid Chef (Compagnons) En attente Non (compte non actif)
chef.farfadets@piloti.fr Chef (Farfadets) + Trésorier Actif Oui
rg@example.invalid Responsable de groupe Actif Oui
materiel@example.invalid Responsable matériel Actif Oui
secretaire@example.invalid Secrétaire Actif Oui
membre.local@example.invalid Membre du local Actif Oui
parent1@example.invalid, parent.test@example.invalid… Parent Actif Oui
jeune.pionnier@example.invalid Jeune (Pionniers, 16 ans) Actif Oui
jeune.compagnon@example.invalid Jeune (Compagnons, 19 ans) Actif Oui
enfants @piloti.invalid (Farfadets/Louveteaux, < 15 ans) Jeune Actif Non (US-CM-01 : géré par un parent)

Commandes

pnpm dev              # Serveur de développement (http://localhost:3000)
pnpm build            # Build de production
pnpm start            # Servir le build de production
pnpm lint             # ESLint
pnpm typecheck        # Vérification TypeScript (sans compilation)

pnpm db:migrate       # Appliquer les migrations Prisma (crée dev.db si absent)
pnpm db:seed          # Remplir la base avec des données de test réalistes
pnpm db:studio        # Prisma Studio — interface graphique pour la base
pnpm db:reset         # Réinitialiser la base et réappliquer toutes les migrations
pnpm db:generate      # Régénérer le client Prisma (après modification du schéma)

pnpm icons:generate   # Régénérer favicon.ico et les icônes PWA depuis les SVG

Structure du projet

piloti/
├── prisma/
│   ├── schema.prisma          # Schéma de base de données (SQLite)
│   ├── seed.ts                # Données de test réalistes
│   └── migrations/            # Migrations versionnées
├── public/
│   ├── logo/                  # SVG source du design system Piloti/SGDF
│   └── icons/                 # PNG générés (PWA, apple-touch-icon)
├── scripts/
│   └── gen-icons.mjs          # Génère favicon.ico + icônes PWA via sharp
├── src/
│   ├── app/
│   │   ├── (app)/             # Pages protégées (authentification requise)
│   │   │   ├── dashboard/     # Tableau de bord
│   │   │   ├── stock/         # Inventaire matériel
│   │   │   ├── prets/         # Prêts
│   │   │   ├── incidents/     # Signalements d'incidents
│   │   │   └── admin/         # Administration (inscriptions, utilisateurs, catégories, audit)
│   │   ├── (auth)/            # Pages publiques
│   │   │   ├── login/         # Connexion
│   │   │   ├── register/      # Demande d'accès (validation admin requise)
│   │   │   ├── setup/         # Premier lancement — création du compte admin
│   │   │   ├── forgot-password/
│   │   │   └── reset-password/
│   │   ├── api/
│   │   │   ├── auth/[...all]/ # Route better-auth (sessions, reset password…)
│   │   │   ├── upload/        # Upload de photos d'incidents
│   │   │   └── health/        # Health check Docker
│   │   ├── globals.css        # Design tokens Tailwind v4 (@theme) + palette SGDF
│   │   ├── layout.tsx         # Layout racine (polices, Toaster)
│   │   └── favicon.ico / icon.png / icon.svg  # Favicon multi-format
│   ├── components/
│   │   ├── ui/                # Primitives shadcn/ui (Button, Input, Dialog…)
│   │   ├── layout/            # Sidebar, MobileHeader, UserMenu, nav-items
│   │   ├── dashboard/         # Widgets du tableau de bord
│   │   ├── equipment/         # CategoryChip, EquipmentForm
│   │   ├── loans/             # LoanCard
│   │   └── incidents/         # IncidentForm, IncidentTypeGrid
│   ├── lib/
│   │   ├── auth.ts            # Configuration better-auth (emailAndPassword + Resend)
│   │   ├── auth-client.ts     # Client better-auth (côté navigateur)
│   │   ├── db.ts              # Client Prisma (singleton, adapter better-sqlite3)
│   │   ├── audit.ts           # withAudit() — wrappeur transaction + AuditLog
│   │   ├── permissions.ts     # can(user, "permission") — contrôle d'accès
│   │   ├── password-policy.ts # Schéma Zod + hint texte pour la politique de mdp
│   │   ├── enums.ts           # Constantes TS (ROLES, UNITS, statuts…)
│   │   ├── get-current-user.ts
│   │   └── incident-categories.ts
│   ├── modules/
│   │   ├── admin/
│   │   │   ├── actions.ts     # Server Actions admin (approuver, suspendre, supprimer…)
│   │   │   └── queries.ts     # Requêtes admin (utilisateurs, audit log)
│   │   └── inventory/
│   │       ├── actions.ts     # CRUD matériel
│   │       ├── loan-actions.ts
│   │       ├── incident-actions.ts
│   │       ├── category-actions.ts
│   │       ├── queries.ts
│   │       └── types.ts       # Schémas Zod pour la validation
│   └── proxy.ts               # Protection des routes (Next.js 16 = proxy.ts, pas middleware.ts)
└── traefik/
    └── config/                # Configuration Traefik (security headers…)

Concepts clés

Protection des routes — src/proxy.ts

⚠️ Next.js 16 a renommé middleware.ts en proxy.ts. Tout exemple en ligne utilisant middleware.ts ne fonctionnera pas.

Le proxy gère trois cas :

  1. Base vide (premier lancement) → redirige vers /setup
  2. Non authentifié → redirige vers /login (sauf routes publiques)
  3. Compte non ACTIVE → efface le cookie, redirige vers /login

Mutations — withAudit()

Toute modification de données passe par withAudit() qui execute la mutation ET crée une entrée AuditLog dans la même transaction Prisma. Jamais de mutation sans trace.

await withAudit(
  (tx) => tx.equipment.update({ where: { id }, data }),
  { action: "EQUIPMENT_UPDATED", userId: user.id, equipmentId: id }
);

Contrôle d'accès — can()

import { can } from "@/lib/permissions";
if (!can(user, "admin.access")) return { error: "Accès refusé." };

Server Actions

Pattern standard du projet :

// actions.ts
export async function monAction(
  _prev: ActionResult,
  formData: FormData,
): Promise<ActionResult> { ... }

// composant client
const [state, action, pending] = useActionState(monAction, { error: null });

Politique de mot de passe

Définie dans src/lib/password-policy.ts : 12 caractères minimum, majuscule, minuscule, chiffre. Partagée entre l'inscription, le reset de mot de passe et le changement admin.

Ajouter une fonctionnalité

Nouveau modèle de données

  1. Modifier prisma/schema.prisma
  2. pnpm db:migrate (génère la migration + regénère le client)
  3. Ajouter les requêtes dans src/modules/<module>/queries.ts
  4. Ajouter les Server Actions dans src/modules/<module>/actions.ts (avec withAudit)
  5. Créer les composants dans src/components/<module>/ et les pages dans src/app/(app)/

Nouvelle page protégée

Créer src/app/(app)/ma-page/page.tsx. Le proxy protège automatiquement tout ce qui est sous (app)/.

Nouvelle catégorie de matériel

Depuis l'interface admin → Catégories, ou directement dans Prisma Studio (pnpm db:studio).

Déploiement Docker (production)

Prérequis

  • Docker Engine 29+ et Docker Compose v2
  • Un tunnel Cloudflare Zero Trust configuré (zéro port exposé sur la machine)
  • Un compte Resend avec domaine vérifié (pour les emails de reset de mot de passe)

Configuration

Créer .env.production (ne jamais commiter ce fichier) :

DATABASE_URL="file:/data/piloti.db"
BETTER_AUTH_SECRET="<openssl rand -hex 32>"
BETTER_AUTH_URL="https://piloti.votre-domaine.fr"
TRAEFIK_DOMAIN="piloti.votre-domaine.fr"
CLOUDFLARE_TUNNEL_TOKEN="<token Zero Trust>"
RESEND_API_KEY="re_<votre-cle>"
RESEND_FROM_EMAIL="noreply@votre-domaine.fr"
# Optionnel — durée de conservation du journal d'audit, en années (vide = 10).
AUDIT_RETENTION_YEARS=""

Lancer

docker compose --env-file .env.production build
docker compose --env-file .env.production up -d

Les migrations Prisma s'appliquent automatiquement au démarrage via le service migrate. L'application est accessible uniquement via le tunnel Cloudflare, sans aucun port exposé.

Premier lancement en production

À la première ouverture dans le navigateur, l'application redirige vers /setup pour créer le compte administrateur. Aucun seed à lancer manuellement.

Mise à jour

docker compose --env-file .env.production build app
docker compose --env-file .env.production up -d app

Commandes utiles

docker compose --env-file .env.production logs -f app   # Logs en direct
docker compose --env-file .env.production down           # Arrêter (données conservées)
docker compose --env-file .env.production down -v        # Arrêter + effacer les données

Architecture

Internet → Cloudflare CDN/WAF
        → cloudflared (tunnel sortant, pas de port entrant)
        → Traefik (reverse proxy interne, security headers)
        → Next.js (port 3000, réseau Docker isolé)

Réseaux Docker :

  • internal (internal: true) — app ↔ Traefik uniquement, pas d'accès Internet
  • tunnel — cloudflared ↔ Traefik

Volumes Docker :

  • piloti-data — base SQLite (/data/piloti.db)
  • piloti-uploads — photos d'incidents (/app/public/uploads)

Notes techniques

  • Tailwind v4 : configuration CSS-first dans src/app/globals.css (@theme inline), pas de tailwind.config.*. Les tokens bg-forest, text-earth, bg-primary (shadcn) viennent tous du même bloc.
  • Prisma 7 : utilise l'adapter better-sqlite3 au lieu du moteur Rust natif — plus léger en Docker, pas de binaire plateforme-spécifique.
  • better-auth : gestion des sessions, hash scrypt des mots de passe, reset par email (Resend). Pas de plugin admin — les actions d'administration sont des Server Actions protégées par can().
  • Audit : AuditLog est immuable et transactionnel. Chaque mutation de données laisse une trace avec userId, action, et un champ metadata JSON libre.

Licence

Piloti est un logiciel libre distribué sous licence GNU AGPL v3 ou ultérieure (AGPL-3.0-or-later). Copyright © 2026 Mathis Capart.

Vous êtes libre d'utiliser, déployer, étudier, modifier et redistribuer Piloti. En contrepartie, l'AGPL impose deux obligations :

  • Toute redistribution — du code source comme d'une version modifiée — se fait sous cette même licence.
  • Article 13, la clause réseau — si vous hébergez une version modifiée de Piloti et que des personnes s'en servent à distance, vous devez leur offrir l'accès au code source de cette version. C'est ce qui empêche qu'un fork amélioré de Piloti devienne un service fermé.

L'application expose déjà cet accès : footer de l'application (présent sur toute page authentifiée), footer des pages légales, et section dédiée des mentions légales.

Si vous modifiez Piloti, faites pointer SOURCE_URL dans src/lib/legal/license.ts vers votre propre dépôt. C'est le code réellement exécuté qui doit être accessible, pas celui d'amont.

Ce que la licence ne couvre pas

Le nom « Scouts et Guides de France », le sigle « SGDF » et les éléments visuels de l'association nationale sont des marques protégées. L'AGPL porte sur le droit d'auteur du code, jamais sur le droit des marques : un fork peut réutiliser ce code, il ne peut pas se présenter comme un outil officiel SGDF.

Dépendances

Les dépendances de production sont sous licences MIT, Apache-2.0, BSD-2-Clause, ISC et MPL-2.0 — toutes compatibles avec l'AGPL-3.0. Elles restent régies par leurs licences respectives.