karbe/README.md

# Karbé

> Marketplace de location de **carbets fluviaux** de Guyane.

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.

## Sommaire

- [Présentation](#présentation)
- [Fonctionnalités](#fonctionnalités)
- [Stack technique](#stack-technique)
- [Prérequis](#prérequis)
- [Installation](#installation)
- [Variables d'environnement](#variables-denvironnement)
- [Déploiement production (karbe.cosmolan.fr)](#déploiement-production-karbecosmolanfr)
- [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**
- **npm** (fourni avec Node.js)
- Une base de données **PostgreSQL** accessible (locale ou distante)

## Installation

1. Installer les dépendances :

   ```bash
   npm install
   ```

   Le script `postinstall` génère automatiquement le client Prisma dans
   `src/generated/prisma`.

2. Configurer les variables d'environnement :

   ```bash
   cp .env.example .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`. |
| `NEXT_PUBLIC_SITE_URL` / `APP_URL` | URL publique de l'application (ex: `https://karbe.cosmolan.fr`). |
| `STRIPE_SECRET_KEY` | Clé secrète Stripe (mode test pour MVP). |
| `STRIPE_WEBHOOK_SECRET` | Secret du webhook Stripe. |
| `STRIPE_OWNER_SUBSCRIPTION_PRICE_ID` | Price ID de l'abonnement loueur Stripe. |

> 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éploiement production (karbe.cosmolan.fr)

Le repo inclut une stack de self-hosting Docker pour le MVP:

- `Dockerfile` (build Next.js standalone)
- `docker-compose.prod.yml` (app + PostgreSQL + MinIO + reverse proxy Caddy HTTPS)
- `docker/Caddyfile`
- `.env.production.example`

### 1) Préparer le serveur

- Docker Engine + Docker Compose plugin installés.
- DNS `A`/`AAAA` de `karbe.cosmolan.fr` pointant vers le serveur.
- Ports `80` et `443` ouverts.

### 2) Configurer l'environnement

```bash
cp .env.production.example .env.production
```

Renseigner toutes les variables, en particulier:
`POSTGRES_PASSWORD`, `MINIO_ROOT_PASSWORD`,
`DATABASE_URL`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`,
`STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_OWNER_SUBSCRIPTION_PRICE_ID`,
`APP_URL` et `NEXT_PUBLIC_SITE_URL`.

`docker-compose.prod.yml` crée automatiquement le bucket MinIO défini par
`S3_BUCKET` au démarrage via le service `minio-init`.

### 3) Appliquer les migrations Prisma

Les migrations doivent être appliquées avant le premier démarrage :

```bash
npx prisma migrate deploy
```

### 4) Lancer la stack

```bash
docker compose -f docker-compose.prod.yml up -d --build
```

Vérifier la santé:

```bash
curl -fsS https://karbe.cosmolan.fr/api/health
```

### 5) Connecter le webhook Stripe (TEST)

Depuis un poste ayant Stripe CLI:

```bash
stripe listen --forward-to https://karbe.cosmolan.fr/api/stripe/webhook
```

Copier le secret affiché (`whsec_...`) dans `STRIPE_WEBHOOK_SECRET`, puis redéployer.

## Développement

```bash
npm run dev
```

L'application est disponible sur [http://localhost:3000](http://localhost:3000).

## Base de données (Prisma)

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 Prisma après une modification du schéma
npx prisma generate

# Créer / appliquer une migration en développement
npx prisma migrate dev --name <nom_de_la_migration>

# Inspecter la base via une interface web
npx prisma studio
```

## 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. |

## 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/<sujet>`** (ou `fix/<sujet>`).
- 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).