From f9310c380fa8b2f39b626034ccaef0834aea8312 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karb=C3=A9=20Architect?= Date: Fri, 29 May 2026 04:42:28 +0000 Subject: [PATCH] docs: README, roadmap produit et doc d'architecture MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README enrichi (présentation Karbé, fonctionnalités, setup dev, env, structure, conventions Git) - ROADMAP.md : phases MVP -> V2 -> V3 - docs/ARCHITECTURE.md : stack, modèle de données (Prisma) et flux principaux Co-Authored-By: Paperclip --- README.md | 167 +++++++++++++++++++++---- ROADMAP.md | 133 ++++++++++++++++++++ docs/ARCHITECTURE.md | 282 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 560 insertions(+), 22 deletions(-) create mode 100644 ROADMAP.md create mode 100644 docs/ARCHITECTURE.md diff --git a/README.md b/README.md index 8ec8b97..61b8977 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,85 @@ # Karbé -Karbé — marketplace de location de carbets fluviaux de Guyane. +> Marketplace de location de **carbets fluviaux** de Guyane. -Connecter voyageurs et hôtes pour des séjours authentiques le long des fleuves -de Guyane, au cœur de la forêt amazonienne. +Karbé connecte les voyageurs et les hôtes pour des séjours authentiques le long +des fleuves de Guyane, au cœur de la forêt amazonienne. La plateforme permet aux +propriétaires de publier leurs carbets, et aux voyageurs de rechercher, réserver +et payer leur séjour en ligne. -## Stack +## Sommaire -- [Next.js 16](https://nextjs.org/) (App Router, TypeScript) -- [Tailwind CSS v4](https://tailwindcss.com/) -- [Prisma](https://www.prisma.io/) (datasource PostgreSQL) +- [Présentation](#présentation) +- [Fonctionnalités](#fonctionnalités) +- [Stack technique](#stack-technique) +- [Prérequis](#prérequis) +- [Installation](#installation) +- [Variables d'environnement](#variables-denvironnement) +- [Développement](#développement) +- [Base de données (Prisma)](#base-de-données-prisma) +- [Scripts npm](#scripts-npm) +- [Structure du projet](#structure-du-projet) +- [Conventions Git & contribution](#conventions-git--contribution) +- [Documentation complémentaire](#documentation-complémentaire) +- [Licence](#licence) + +## Présentation + +Le **carbet** est l'habitat traditionnel amazonien : un abri ouvert, souvent en +bois, installé au bord des fleuves. En Guyane, les carbets fluviaux sont un mode +d'hébergement prisé pour découvrir la forêt, naviguer sur les fleuves (Maroni, +Oyapock, Approuague…) et vivre une expérience proche de la nature. + +Karbé est une **marketplace à deux faces** : + +- **Voyageurs** — recherchent un carbet, consultent les disponibilités, réservent + et paient en ligne, échangent avec l'hôte et laissent un avis après le séjour. +- **Hôtes (loueurs)** — créent leur profil, publient et gèrent leurs carbets + (photos, tarifs, calendrier de disponibilité) et suivent leurs réservations. + +La plateforme prévoit également une dimension **B2B** (créneaux réservés aux +comités d'entreprise) et un modèle d'**abonnement loueur**. Voir la +[roadmap produit](./ROADMAP.md) pour le détail des phases. + +## Fonctionnalités + +| Domaine | Description | +| --- | --- | +| Comptes multi-rôles | Voyageur, hôte et administrateur (authentification NextAuth). | +| Fiches carbet | Titre, description, fleuve, localité, géolocalisation, capacité, équipements, photos. | +| Recherche publique | Listing et fiche carbet rendus côté serveur (SSR) pour le SEO. | +| Disponibilités & tarifs | Calendrier par date, prix personnalisés, nuits minimum. | +| Réservation | Sélection de dates, calcul du prix (nuitée, ménage, frais de service). | +| Paiement | Encaissement via Stripe (réservation + abonnement loueur). | +| Messagerie | Conversation par réservation entre voyageur et hôte. | +| Avis & notes | Évaluation du séjour après le check-out. | +| Conformité | CGV, RGPD, mentions légales. | + +> Toutes ces fonctionnalités ne sont pas encore livrées : voir la +> [roadmap](./ROADMAP.md) pour l'état d'avancement par phase. + +## Stack technique + +- **[Next.js 16](https://nextjs.org/)** — App Router, TypeScript, rendu serveur. +- **[React 19](https://react.dev/)**. +- **[Tailwind CSS v4](https://tailwindcss.com/)** — styles utilitaires. +- **[Prisma 7](https://www.prisma.io/)** — ORM, datasource **PostgreSQL**. Le + client est généré dans `src/generated/prisma`. +- **[NextAuth](https://authjs.dev/)** — authentification multi-rôles. +- **[Stripe](https://stripe.com/)** — paiements (prévu). + +Pour les choix d'architecture et les flux détaillés, voir +[`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md). + +> **Note :** ce dépôt utilise une version de Next.js qui peut différer de la +> documentation publique. En cas de doute sur une API, consultez la +> documentation embarquée dans `node_modules/next/dist/docs/`. ## Prérequis -- Node.js >= 20 -- Une base de données PostgreSQL +- **Node.js >= 20** +- **npm** (fourni avec Node.js) +- Une base de données **PostgreSQL** accessible (locale ou distante) ## Installation @@ -33,8 +98,27 @@ de Guyane, au cœur de la forêt amazonienne. cp .env.example .env ``` - Puis renseignez `DATABASE_URL` (connexion PostgreSQL) et `NEXTAUTH_SECRET` - dans le fichier `.env`. + Renseignez ensuite les valeurs dans `.env` (voir ci-dessous). + +3. Préparer la base de données : + + ```bash + npx prisma migrate dev + ``` + +## Variables d'environnement + +Le fichier [`.env.example`](./.env.example) liste les variables attendues. +Copiez-le en `.env` et renseignez vos valeurs. + +| Variable | Rôle | +| --- | --- | +| `DATABASE_URL` | Chaîne de connexion PostgreSQL utilisée par Prisma. | +| `AUTH_SECRET` / `NEXTAUTH_SECRET` | Secret de signature des sessions NextAuth. Générer avec `openssl rand -base64 32`. | + +> Le fichier `.env` ne doit **jamais** être commité (il est ignoré par Git). +> Au fur et à mesure de l'ajout des intégrations (ex. Stripe), de nouvelles +> variables seront ajoutées à `.env.example`. ## Développement @@ -46,22 +130,61 @@ L'application est disponible sur [http://localhost:3000](http://localhost:3000). ## Base de données (Prisma) -Le schéma vit dans `prisma/schema.prisma` (volontairement minimal pour le -moment, les modèles seront ajoutés au fur et à mesure). +Le schéma vit dans [`prisma/schema.prisma`](./prisma/schema.prisma). Il décrit +les entités de Karbé (utilisateurs, carbets, réservations, paiements, avis, +messagerie…). Le modèle de données est détaillé dans +[`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md#modèle-de-données). ```bash -# Régénérer le client après une modification du schéma +# Régénérer le client Prisma après une modification du schéma npx prisma generate # Créer / appliquer une migration en développement -npx prisma migrate dev +npx prisma migrate dev --name + +# Inspecter la base via une interface web +npx prisma studio ``` -## Scripts +## Scripts npm -| Script | Description | -| --------------- | ------------------------------------ | -| `npm run dev` | Démarre le serveur de développement | -| `npm run build` | Build de production | -| `npm run start` | Démarre le serveur de production | -| `npm run lint` | Lance ESLint | +| Script | Description | +| --- | --- | +| `npm run dev` | Démarre le serveur de développement. | +| `npm run build` | Build de production. | +| `npm run start` | Démarre le serveur de production. | +| `npm run lint` | Lance ESLint. | + +## Structure du projet + +```text +karbe/ +├── prisma/ +│ ├── schema.prisma # Modèle de données (entités Karbé) +│ └── migrations/ # Migrations SQL générées par Prisma +├── public/ # Fichiers statiques +├── src/ +│ ├── app/ # Routes App Router (pages, layouts, route handlers) +│ └── generated/prisma/ # Client Prisma généré (ne pas éditer à la main) +├── docs/ +│ └── ARCHITECTURE.md # Documentation d'architecture +├── ROADMAP.md # Roadmap produit (MVP → V2 → V3) +└── README.md +``` + +## Conventions Git & contribution + +- La branche **`main` est protégée** : aucun commit direct. +- Travaillez sur une branche dédiée nommée **`feat/`** (ou `fix/`). +- Ouvrez une **Pull Request vers `main`** pour toute modification. +- Avant d'ouvrir la PR, vérifiez que `npm run lint` et `npm run build` passent. + +## Documentation complémentaire + +- [Roadmap produit](./ROADMAP.md) — phases MVP → V2 → V3. +- [Documentation d'architecture](./docs/ARCHITECTURE.md) — stack, modèle de + données et flux principaux. + +## Licence + +Voir le fichier [`LICENSE`](./LICENSE). diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..c3af243 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,133 @@ +# Roadmap produit — Karbé + +Cette roadmap décrit la trajectoire produit de **Karbé**, la marketplace de +location de carbets fluviaux de Guyane. Elle est organisée en trois phases : +**MVP** (premier produit utilisable de bout en bout), **V2** (montée en gamme et +expérience), **V3** (passage à l'échelle et nouveaux marchés). + +> Les phases sont indicatives et sont amenées à évoluer en fonction des retours +> utilisateurs et des priorités business. Les statuts ✅ / 🚧 / ⬜ reflètent +> l'avancement au moment de la rédaction. + +## Vision + +Devenir **la** plateforme de référence pour la découverte et la réservation +d'hébergements fluviaux et nature en Guyane, en valorisant l'offre des hôtes +locaux et en proposant aux voyageurs (particuliers comme comités d'entreprise) +une expérience de réservation simple, fiable et sécurisée. + +## Objectifs par phase + +| Phase | Objectif | Public visé | +| --- | --- | --- | +| **MVP** | Réserver et payer un carbet de bout en bout. | Voyageurs particuliers + hôtes | +| **V2** | Fidéliser, fluidifier et industrialiser l'usage. | Voyageurs récurrents, hôtes pros, comités d'entreprise | +| **V3** | Passer à l'échelle et ouvrir de nouveaux usages/marchés. | Partenaires, B2B, international | + +--- + +## Phase 1 — MVP + +**But :** un voyageur peut trouver un carbet, le réserver, le payer ; un hôte +peut publier et gérer son offre. La boucle économique de base fonctionne. + +### Périmètre fonctionnel + +| # | Fonctionnalité | Description | Statut | +| --- | --- | --- | --- | +| 1 | Socle technique | Scaffold Next.js + TypeScript + Prisma + Tailwind. | ✅ | +| 2 | Modèle de données | Schéma Prisma complet + migrations (entités Karbé). | ✅ | +| 3 | Authentification multi-rôles | Inscription / connexion Voyageur, Hôte, Admin (NextAuth). | 🚧 | +| 4 | Interface propriétaire | CRUD des carbets + upload des photos. | 🚧 | +| 5 | Recherche & fiche publique | Listing et fiche carbet en SSR (SEO). | ⬜ | +| 6 | Réservation & disponibilités | Calendrier de dispo, sélection de dates, créneaux comités d'entreprise. | ⬜ | +| 7 | Paiement | Encaissement Stripe (réservation + abonnement loueur). | ⬜ | +| 8 | Avis & notes | Évaluation du séjour après le check-out. | ⬜ | +| 9 | Conformité | CGV, RGPD, mentions légales. | 🚧 | +| 10 | Documentation | README, roadmap, doc d'architecture. | 🚧 | + +### Critères de sortie du MVP + +- Un voyageur peut s'inscrire, rechercher un carbet, réserver des dates + disponibles et payer. +- Un hôte peut publier un carbet avec photos, tarifs et calendrier. +- Les pages publiques sont indexables (SSR/SEO). +- Les obligations légales (CGV, RGPD, mentions légales) sont en place. + +--- + +## Phase 2 — V2 + +**But :** améliorer l'expérience, fidéliser les utilisateurs et outiller les +hôtes professionnels et le canal B2B (comités d'entreprise). + +### Pistes fonctionnelles + +- **Recherche avancée** — carte interactive (fleuves/localités), filtres + (équipements, capacité, prix, note), tri pertinent. +- **Favoris & wishlists** — exploitation du modèle de favoris pour sauvegarder + et comparer des carbets. +- **Messagerie enrichie** — notifications (e-mail / in-app), messages + pré-séjour et post-séjour, modèles de réponse pour les hôtes. +- **Tableau de bord hôte** — statistiques (taux d'occupation, revenus), + gestion des paiements/payouts, politiques d'annulation paramétrables. +- **Gestion des annulations & remboursements** — règles claires côté voyageur + et hôte, remboursements automatisés via Stripe. +- **Portail comités d'entreprise (CE)** — espace dédié, créneaux et tarifs + négociés, facturation centralisée. +- **Modération des avis** — signalement, réponses des hôtes, contrôle qualité. +- **Synchronisation de calendrier** — import/export iCal pour éviter les + doubles réservations. +- **Internationalisation (i18n)** — préparation multilingue (FR puis EN/PT, + pertinent pour la zone transfrontalière Brésil/Suriname). +- **Optimisation mobile** — parcours responsive soigné, performance sur réseaux + contraints. + +### Critères de sortie de la V2 + +- Les hôtes pilotent leur activité depuis un tableau de bord. +- Le canal comités d'entreprise est opérationnel. +- Le taux de conversion et la rétention sont mesurés et suivis. + +--- + +## Phase 3 — V3 + +**But :** passer à l'échelle, ouvrir de nouveaux usages et marchés, et +renforcer la confiance. + +### Pistes fonctionnelles + +- **Applications mobiles** (iOS / Android) ou PWA installable. +- **Tarification dynamique** — recommandations de prix selon la saison et la + demande. +- **Recommandations personnalisées** — moteur de suggestions de carbets. +- **Vérification d'identité (KYC)** et label « hôte vérifié » renforcé. +- **Assurance séjour / annulation** via un partenaire. +- **Intégrations partenaires** — tour-opérateurs, transport fluvial, + activités (pêche, randonnée, excursions). +- **Programme de fidélité** — points, parrainage, offres récurrentes. +- **API publique** — ouverture aux partenaires et revendeurs. +- **Mode hors-ligne / faible connectivité** — consultation et préparation de + réservation adaptées aux zones isolées de Guyane. +- **Expansion géographique** — autres territoires (Antilles, Amazonie + transfrontalière), multi-devises. + +### Critères de sortie de la V3 + +- Présence mobile native ou PWA. +- Écosystème de partenaires intégré via API. +- Modèle économique diversifié (commissions, abonnements, partenariats). + +--- + +## Synthèse + +```text +MVP ──▶ Réserver & payer un carbet de bout en bout + V2 ──▶ Expérience, fidélisation, hôtes pros & comités d'entreprise + V3 ──▶ Mobile, partenariats, API, passage à l'échelle +``` + +Pour le détail technique des fonctionnalités, voir +[`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md). diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..cf4183c --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,282 @@ +# Architecture — Karbé + +Ce document décrit l'architecture technique de **Karbé**, la marketplace de +location de carbets fluviaux de Guyane : la **stack**, le **modèle de données** +et les **flux principaux**. + +- Pour démarrer le projet, voir le [README](../README.md). +- Pour la trajectoire produit, voir la [roadmap](../ROADMAP.md). + +## Sommaire + +- [Vue d'ensemble](#vue-densemble) +- [Stack technique](#stack-technique) +- [Organisation du code](#organisation-du-code) +- [Modèle de données](#modèle-de-données) +- [Flux principaux](#flux-principaux) +- [Sécurité & conformité](#sécurité--conformité) + +## Vue d'ensemble + +Karbé est une application **Next.js (App Router)** full-stack : le même projet +sert le rendu des pages (React Server Components + Client Components) et expose +la logique serveur (route handlers, server actions). La persistance est assurée +par **PostgreSQL** via **Prisma**. L'authentification repose sur **NextAuth**, +et les paiements sur **Stripe**. + +```text + ┌─────────────────────────────────────────────┐ + Navigateur │ Next.js (App Router) │ + (voyageur / │ │ + hôte / admin)│ React Server / Client Components │ + │ │ Route handlers / Server actions │ + │ HTTPS │ │ │ │ + └───────▶│ NextAuth Prisma Client │ + │ (sessions, (requêtes) │ + │ rôles) │ │ + └─────────────────────────────────┼─────────────┘ + │ + ┌────────────────────────┼───────────────┐ + ▼ ▼ ▼ + PostgreSQL Stripe Stockage + (données) (paiements) médias (photos) +``` + +> **Note de version :** ce dépôt utilise une version récente de Next.js dont +> certaines API peuvent différer de la documentation publique. La référence +> embarquée se trouve dans `node_modules/next/dist/docs/`. + +## Stack technique + +| Couche | Technologie | Rôle | +| --- | --- | --- | +| Framework | **Next.js 16** (App Router) | Rendu SSR/RSC, routing, logique serveur. | +| UI | **React 19** + **Tailwind CSS v4** | Composants et styles. | +| Langage | **TypeScript** | Typage statique de bout en bout. | +| ORM | **Prisma 7** | Accès aux données, migrations, typage. Client généré dans `src/generated/prisma`. | +| Base de données | **PostgreSQL** | Persistance relationnelle. | +| Authentification | **NextAuth** | Sessions et contrôle d'accès par rôle. | +| Paiement | **Stripe** | Encaissement réservations + abonnement loueur. | +| Lint | **ESLint** (`eslint-config-next`) | Qualité de code. | + +## Organisation du code + +```text +src/ +├── app/ # App Router : pages, layouts, route handlers +│ ├── layout.tsx # Layout racine +│ ├── page.tsx # Page d'accueil +│ └── globals.css # Styles globaux (Tailwind) +└── generated/prisma/ # Client Prisma généré (NE PAS éditer à la main) + +prisma/ +├── schema.prisma # Source de vérité du modèle de données +└── migrations/ # Migrations SQL +``` + +Principes : + +- **App Router** — chaque dossier de `src/app` est un segment de route. Les + pages sont des **Server Components** par défaut ; on bascule en Client + Component (`"use client"`) seulement pour l'interactivité. +- **Accès données côté serveur** — les requêtes Prisma s'exécutent côté serveur + (Server Components, route handlers, server actions), jamais dans le + navigateur. +- **Client Prisma généré** — importé depuis `src/generated/prisma` ; il est + régénéré via `npx prisma generate` (script `postinstall`). + +## Modèle de données + +Le modèle est défini dans [`prisma/schema.prisma`](../prisma/schema.prisma) et +porté par PostgreSQL. Il couvre cinq grands domaines : **comptes**, **offre +(carbets)**, **réservation**, **paiement** et **relation (messagerie & avis)**. + +### Énumérations + +| Enum | Valeurs | +| --- | --- | +| `UserRole` | `TRAVELER`, `HOST`, `ADMIN` | +| `CarbetStatus` | `DRAFT`, `PUBLISHED`, `ARCHIVED` | +| `BookingStatus` | `PENDING`, `CONFIRMED`, `CANCELLED`, `COMPLETED` | +| `PaymentStatus` | `PENDING`, `AUTHORIZED`, `SUCCEEDED`, `FAILED`, `REFUNDED` | +| `MessageSenderType` | `TRAVELER`, `HOST`, `SYSTEM` | + +### Schéma relationnel + +```mermaid +erDiagram + User ||--o| HostProfile : "a (si hôte)" + User ||--o{ Booking : "réserve" + User ||--o{ Review : "rédige" + User ||--o{ FavoriteCarbet : "favoris" + HostProfile ||--o{ Carbet : "publie" + Carbet ||--o{ CarbetPhoto : "photos" + Carbet ||--o{ CarbetAvailability : "disponibilités" + Carbet ||--o{ Booking : "réservations" + Carbet ||--o{ Review : "avis" + Carbet ||--o{ FavoriteCarbet : "favoris" + Carbet }o--o{ Amenity : "équipements (CarbetAmenity)" + Booking ||--o{ Payment : "paiements" + Booking ||--o| Conversation : "fil de discussion" + Booking ||--o| Review : "avis" + Conversation ||--o{ Message : "messages" +``` + +### Entités principales + +#### Comptes + +- **`User`** — compte unique pour tous les rôles (`role` : `TRAVELER`, `HOST`, + `ADMIN`). Champs clés : `email` (unique), `passwordHash`, `firstName`, + `lastName`, `phone?`, `avatarUrl?`, `isActive`. Relations : un éventuel + `HostProfile`, ses `bookings`, ses `reviews`, ses `favoriteCarbets`, et ses + conversations (en tant que voyageur ou hôte). +- **`HostProfile`** — profil hôte en **1:1** avec `User` (relation optionnelle : + seuls les hôtes en ont un). Contient `bio?`, `verificationAt?` (date de + vérification), `payoutInfo?` (infos de versement) et la liste des `carbets`. + +#### Offre (carbets) + +- **`Carbet`** — l'annonce. Champs : `title`, `slug` (unique, pour le SEO), + `description`, localisation (`river`, `locality`, `latitude?`, `longitude?`), + capacité (`maxGuests`, `bedrooms`, `beds`, `bathrooms`), tarification + (`basePricePerNight`, `cleaningFee`, `serviceFee`), `status` + (`DRAFT`/`PUBLISHED`/`ARCHIVED`) et `publishedAt?`. Indexé par hôte, statut, + (fleuve, localité) et prix pour la recherche. +- **`Amenity`** / **`CarbetAmenity`** — catalogue d'équipements et table de + liaison **N:N** entre carbets et équipements (clé composite + `[carbetId, amenityId]`). +- **`CarbetPhoto`** — photos d'un carbet (`url`, `alt?`, `sortOrder`). +- **`CarbetAvailability`** — calendrier : une ligne par `date` et par carbet + (`@@unique([carbetId, date])`), avec `isAvailable`, `customPrice?` (tarif + spécifique) et `minNights` (séjour minimum). + +#### Réservation + +- **`Booking`** — réservation reliant un `Carbet` et un `User` (voyageur). + Champs : `checkIn`, `checkOut`, `guests`, `status`, instantané de + tarification (`nightlyRate`, `cleaningFee`, `serviceFee`, `totalAmount`, + `currency` = `EUR`), `notes?`, et champs d'annulation (`canceledAt?`, + `cancellationReason?`). Les suppressions de carbet/voyageur sont en + `Restrict` pour préserver l'historique des réservations. + +#### Paiement + +- **`Payment`** — un ou plusieurs paiements rattachés à une `Booking`. Champs : + `provider`, `providerPaymentId?` (unique, ex. id Stripe), `amount`, + `currency`, `status` (`PENDING` → `AUTHORIZED` → `SUCCEEDED`/`FAILED`, + `REFUNDED`), `paidAt?`, `refundedAt?` et détails d'échec + (`failureCode?`, `failureMessage?`). + +#### Relation : messagerie & avis + +- **`Conversation`** — un fil **1:1 avec une `Booking`**, reliant le voyageur + (`travelerId`) et l'hôte (`hostId`). +- **`Message`** — message d'une conversation (`senderType` : `TRAVELER`, + `HOST` ou `SYSTEM`, `senderUserId?`, `content`, `sentAt`, `readAt?`). +- **`Review`** — avis **1:1 avec une `Booking`** (un avis par séjour), portant + une `rating`, un `title?` et un `comment?`, rattaché au carbet et au voyageur. +- **`FavoriteCarbet`** — table de liaison **N:N** (wishlist) entre `User` et + `Carbet` (clé composite `[userId, carbetId]`). + +### Conventions + +- **Identifiants** : `cuid()` (chaînes) en clé primaire. +- **Horodatage** : `createdAt` / `updatedAt` sur la plupart des entités. +- **Montants** : `Decimal(10,2)` pour les prix, `Decimal(9,6)` pour les + coordonnées GPS. +- **Suppressions** : `Cascade` pour les données dépendantes (photos, messages, + disponibilités) ; `Restrict` pour préserver l'historique financier + (réservations, paiements, avis). +- **Index** : posés sur les colonnes de recherche/jointure fréquentes (statut, + fleuve+localité, prix, dates, clés étrangères). + +## Flux principaux + +### 1. Authentification & rôles + +```mermaid +sequenceDiagram + actor U as Utilisateur + participant App as Next.js + participant Auth as NextAuth + participant DB as PostgreSQL + + U->>App: Inscription / Connexion (email + mot de passe) + App->>Auth: Vérifie les identifiants + Auth->>DB: Lit User (passwordHash, role, isActive) + Auth-->>App: Session (id + role) + App-->>U: Accès adapté au rôle (TRAVELER / HOST / ADMIN) +``` + +Le `role` porté par la session conditionne l'accès : espace voyageur, interface +hôte (gestion des carbets), ou back-office admin. + +### 2. Publication d'un carbet (hôte) + +1. Un `User` de rôle `HOST` (avec `HostProfile`) crée un `Carbet` en `DRAFT`. +2. Il ajoute des `CarbetPhoto`, sélectionne des `Amenity` (via `CarbetAmenity`) + et renseigne le calendrier `CarbetAvailability` (dates, prix, nuits min). +3. Il publie : `status` passe à `PUBLISHED` et `publishedAt` est renseigné. Le + carbet devient visible dans la recherche publique. + +### 3. Recherche & consultation (public, SSR/SEO) + +1. La page de listing interroge les `Carbet` en `PUBLISHED` (filtres : fleuve, + localité, capacité, prix…), rendue **côté serveur** pour l'indexation. +2. La fiche carbet est servie via son `slug` unique (URL stable, SEO-friendly) + et affiche photos, équipements, disponibilités et avis. + +### 4. Réservation & paiement + +```mermaid +sequenceDiagram + actor V as Voyageur + participant App as Next.js + participant DB as PostgreSQL + participant Stripe as Stripe + + V->>App: Choisit des dates + nombre de voyageurs + App->>DB: Vérifie CarbetAvailability (dispo + minNights) + App->>App: Calcule le total (nuitées, ménage, frais de service) + App->>DB: Crée Booking (status = PENDING) + V->>App: Procède au paiement + App->>Stripe: Crée l'intention de paiement + Stripe-->>App: Webhook / callback (succès ou échec) + alt Paiement réussi + App->>DB: Payment = SUCCEEDED, Booking = CONFIRMED + App-->>V: Confirmation de réservation + else Paiement échoué + App->>DB: Payment = FAILED, Booking reste PENDING + App-->>V: Échec, nouvelle tentative possible + end +``` + +À l'issue du séjour, la `Booking` passe en `COMPLETED`. Une annulation renseigne +`canceledAt`/`cancellationReason` et peut déclencher un `REFUNDED` côté +`Payment`. + +### 5. Messagerie + +À la création d'une réservation, une `Conversation` (1:1 avec la `Booking`) est +ouverte entre le voyageur et l'hôte. Les `Message` portent un `senderType` +(`TRAVELER`, `HOST`, `SYSTEM` pour les notifications automatiques) et un statut +de lecture (`readAt`). + +### 6. Avis + +Après un séjour `COMPLETED`, le voyageur peut déposer un `Review` (un seul par +réservation, contrainte d'unicité sur `bookingId`). La note alimente la +réputation du carbet affichée sur sa fiche. + +## Sécurité & conformité + +- **Mots de passe** stockés hachés (`passwordHash`), jamais en clair. +- **Secrets** (`AUTH_SECRET`/`NEXTAUTH_SECRET`, clés Stripe, `DATABASE_URL`) en + variables d'environnement, hors du dépôt (voir `.env.example`). +- **Contrôle d'accès** par rôle (`UserRole`) appliqué côté serveur. +- **Intégrité financière** : suppressions en `Restrict` sur les réservations, + paiements et avis pour conserver l'historique. +- **RGPD & mentions légales** : pages dédiées (CGV, politique de + confidentialité, mentions légales) — voir la [roadmap](../ROADMAP.md). +```