# Documentation technique - Lucien-sens-bon

Ce document explique l'architecture, les technologies, la mise en place, les tests
et la sauvegarde/restauration du magasin en ligne. Il est ecrit pour une personne
junior afin de pouvoir prendre en main le projet en autonomie.

## 1) Vue d'ensemble

Le projet est compose de :
- **Backend MedusaJS** : API ecommerce (produits, panier, commandes).
- **Storefront Next.js** : site web public.
- **PostgreSQL** : base de donnees principale (clients, commandes, produits).
- **Redis** : cache et event bus.
- **Docker Compose** : orchestration des services.
- **Apache** (optionnel) : reverse proxy pour publier en 80/443.

Ports principaux :
- `8000` : storefront (site public)
- `9000` : backend (API + admin)
- `6379` : redis

## 2) Technologies utilisees (liens utiles)

- MedusaJS : https://docs.medusajs.com/
- Next.js : https://nextjs.org/docs
- Docker : https://docs.docker.com/get-started/
- Docker Compose : https://docs.docker.com/compose/
- PostgreSQL : https://www.postgresql.org/docs/
- Redis : https://redis.io/docs/latest/
- Apache reverse proxy : https://httpd.apache.org/docs/2.4/howto/reverse_proxy.html

## 3) Fichiers importants

- `docker-compose.yml` : configuration des conteneurs.
- `backend/` : code et config Medusa.
- `storefront/` : code Next.js.
- `.env` : variables d'environnement (non versionne).
- `env-example` : modele de variables d'environnement.

## 4) Installation rapide (serveur)

1. Copier la configuration :
```
cp env-example .env
```

2. Completer `.env` (exemple) :
```
DATABASE_URL=postgres://user:password@host:5432/nom_db
NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://api.exemple.com
ADMIN_CORS=http://api.exemple.com
STORE_CORS=http://exemple.com
JWT_SECRET=change_me
COOKIE_SECRET=change_me
```

3. Lancer les services :
```
docker compose up -d --build
```

## 5) Tests rapides

Verifier que les conteneurs tournent :
```
docker compose ps
```

Tester le storefront :
```
curl http://localhost:8000
```

Tester l'API Medusa :
```
curl http://localhost:9000/store/products
```

Voir les logs :
```
docker compose logs -f backend
docker compose logs -f storefront
```

## 6) Ou se trouve la base de donnees ?

Le backend lit la base de donnees via `DATABASE_URL` dans `.env`.
Le format est :
```
postgres://user:password@host:5432/nom_db
```

Si PostgreSQL est externe au serveur, verifier l'ouverture du port `5432`
et les autorisations reseau (pg_hba.conf cote PostgreSQL).

## 7) Debogage courant

### Backend qui redemarre en boucle
Ca arrive si :
- `DATABASE_URL` est incorrect
- les migrations ne sont pas faites
- le backend tente de compiler TypeScript sans dossier `src/`

Commandes utiles :
```
docker compose logs -f backend
docker exec -it medusa-backend npm run seed
```

### Storefront affiche "Chargement des produits..."
Le storefront attend l'API backend. Verifier :
- `NEXT_PUBLIC_MEDUSA_BACKEND_URL` dans `.env`
- le backend repond sur `:9000`

## 8) Mise en production (reverse proxy)

Pour exposer en HTTP/HTTPS, utiliser Apache ou Nginx. Exemple Apache :
- `apache-vhost.conf` dans le repo
- activer `proxy` et `proxy_http`

## 9) Sauvegarde et restauration

Objectif : pouvoir recuperer **tout le site** et **l'historique**.
Il faut sauvegarder :
- la base PostgreSQL
- les fichiers uploads (si utilises)
- le fichier `.env`
- le depot Git (historique du code)

### 9.1 Sauvegarde PostgreSQL
Sur le serveur de DB :
```
pg_dump -Fc -U user nom_db > /backups/lucien-sens-bon.dump
```
Doc officielle : https://www.postgresql.org/docs/current/app-pgdump.html

### 9.2 Sauvegarde des uploads
Si le backend stocke des fichiers :
```
tar -czf /backups/medusa-uploads.tgz /var/www/lucien-sens-bon/backend/uploads
```

### 9.3 Sauvegarde du depot Git
Si le depot est sur un serveur Git (bare) :
```
git clone --mirror toshiro@chillka:/var/data/git/repositories/lucien-sens-bon.git /backups/lucien-sens-bon.git
```

### 9.4 Sauvegarde complete (exemple simple)
```
tar -czf /backups/lucien-sens-bon-config.tgz \
  /var/www/lucien-sens-bon/.env \
  /var/www/lucien-sens-bon/docker-compose.yml
```

### 9.5 Restauration rapide
1) Restaurer la DB :
```
pg_restore -U user -d nom_db /backups/lucien-sens-bon.dump
```
Doc : https://www.postgresql.org/docs/current/app-pgrestore.html

2) Restaurer les fichiers :
```
tar -xzf /backups/medusa-uploads.tgz -C /
tar -xzf /backups/lucien-sens-bon-config.tgz -C /
```

3) Relancer les conteneurs :
```
docker compose up -d --build
```

## 10) Bonnes pratiques

- Toujours versionner le code via Git (ne pas modifier uniquement sur serveur).
- Sauvegarder la DB quotidiennement.
- Garder un backup hors serveur (S3, autre machine).
- Tester les restaurations une fois par trimestre.