path: root/DOC_TECHNIQUE.md

# 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

## 1.1) Redis (pourquoi et comment)

Redis est une base cle-valeur en memoire, utilisee pour :
- **cache** : accelerer certaines lectures.
- **event bus** : diffuser des evenements internes (ex: `order.created`).
- **queue legere** : traitement asynchrone simple.

Dans ce projet, Medusa utilise :
- `@medusajs/event-bus-redis` (event bus)
- `@medusajs/cache-redis` (cache)

Flux simple :
1) Une action se produit (ex: produit cree).
2) Medusa emet un evenement.
3) Redis relaie l'evenement aux modules abonnes.

Ou le voir :
- `backend/medusa-config.js` -> `eventBus` et `cacheService`.
- `docker-compose.yml` -> service `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.

## 3.1) D'ou vient le code (YAML vs depot)

Le fichier `docker-compose.yml` **ne contient pas le code** :
- il **decrit** comment lancer les conteneurs (services, ports, variables).
- le **code** vient du depot Git (`backend/` et `storefront/`).

Flux reel :
1) On recupere le code via Git.
2) `docker compose build` construit les images depuis les Dockerfile.
3) `docker compose up` lance les conteneurs avec les variables `.env`.

## 3.2) Medusa (backend) - installation technique

Etapes principales :
1) `backend/Dockerfile` copie `package.json`, installe les deps.
2) `postinstall` lance `scripts/patch-medusa.js` (patch TypeORM).
3) Le code est copie dans l'image.
4) Le conteneur demarre `medusa start`.
5) Connexion a PostgreSQL via `DATABASE_URL`.
6) Connexion a Redis pour cache/event bus.

Medusa tourne bien avec **Node.js** (runtime JavaScript).

Briques logicielles principales :
- **Node.js** : runtime qui execute Medusa.
- **Express** : serveur HTTP sous-jacent.
- **TypeORM** : ORM pour PostgreSQL.
- **PostgreSQL** : base de donnees principale.
- **Redis** : cache + event bus.
- **MedusaJS** : API ecommerce (services, modules, plugins).

## 3.3) Storefront (frontend) - fonctionnement

- Next.js compile le site au build (`npm run build`).
- La variable `NEXT_PUBLIC_MEDUSA_BACKEND_URL` est **injectee au build**.
- Le conteneur expose le site sur le port `8000`.

## 3.4) Schema technique (ASCII)

```
                 +----------------------+
                 |     Storefront       |
                 |  Next.js (Node)      |
                 |  :8000               |
                 +----------+-----------+
                            |
                            | HTTP (API)
                            v
                 +----------------------+
                 |      MedusaJS        |
                 |  Node + Express      |
                 |  :9000 (API/Admin)   |
                 +-----+----------+-----+
                       |          |
              SQL      |          |  Cache/Event bus
                       v          v
              +---------------+  +----------------+
              |  PostgreSQL   |  |     Redis      |
              |  :5432        |  |     :6379      |
              +---------------+  +----------------+
```

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

### 4.1) Exemple reel (ce que nous avons fait)

Contexte : backend sur `192.168.99.22:9000`, storefront sur `192.168.99.22:8000`.

1) Variables d'environnement (exemple utilise) :
```
DATABASE_URL=postgres://luciensbdb:********@192.168.99.35:5432/sens_bon_db
JWT_SECRET=supersecret
COOKIE_SECRET=supersecret
ADMIN_CORS=http://192.168.99.22:9000
STORE_CORS=http://192.168.99.22:8000
NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://192.168.99.22:9000
NODE_ENV=development
```

2) Rebuild complet (pour appliquer les patches) :
```
sudo docker compose build --no-cache backend
sudo docker compose up -d backend
sudo docker compose up -d --build storefront
```

3) Verification rapide :
```
curl -v http://localhost:9000/store/products
curl -v http://192.168.99.22:8000
```

4) Seed (donnees demo) :
```
sudo docker compose run --rm backend npm run seed
```

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

### 5.1) Logs systeme avec journalctl (systemd)

Utiliser `journalctl` pour diagnostiquer les services systeme (Apache, dnsmasq, Docker).

Ou sont stockes les logs systeme :
- **Persistant** : `/var/log/journal/` (apres reboot)
- **Volatile** : `/run/log/journal/` (perdu au reboot)

Verifier le stockage et la retention :
```
sudo journalctl --disk-usage
sudo journalctl --list-boots
```

Options courantes (rappel rapide) :
- `-u <service>` : filtre sur un service (ex: `dnsmasq`, `apache2`, `docker`)
- `-n N` : N dernieres lignes
- `-f` : suivi en direct (tail -f)
- `-b` : logs du dernier boot
- `-o short|short-iso` : format de sortie
- `-S "<date>"` : depuis une date/heure (ex: `"10 min ago"`)
- `--no-pager` : pas de pagination

Exemples utiles :
```
# 50 derniers logs dnsmasq
sudo journalctl -u dnsmasq -n 50 --no-pager

# Logs Apache en direct
sudo journalctl -u apache2 -f

# Logs Docker (service systemd)
sudo journalctl -u docker -n 100 --no-pager

# Logs depuis le dernier boot
sudo journalctl -b -u dnsmasq --no-pager

# Logs avec horodatage court
sudo journalctl -u dnsmasq -n 50 --no-pager -o short

# Derniers logs "pousses" (ecrits recemment)
sudo journalctl -n 50 --no-pager
sudo journalctl -u dnsmasq -S "10 min ago" --no-pager
```

### 5.2) Tests CORS (exemple utilise)

```
curl -i -H "Origin: http://192.168.99.22:8000" http://192.168.99.22:9000/store/products
```

- Confirme que `Access-Control-Allow-Origin` autorise le 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`

Si le backend repond, mais que rien ne s'affiche :
- verifier que le storefront a ete **rebuild** apres changement de `.env` :
```
sudo docker compose up -d --build storefront
```
- verifier que `storefront/pages/_app.js` utilise
`process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL` (pas `localhost` en dur).

### Admin Medusa (login qui boucle)

Symptome : l'admin reste sur la page de login.
Cause frequente : cookies `Secure` bloques en HTTP si `NODE_ENV=production`.

Solution appliquee :
1) Rendre `NODE_ENV` configurable dans `docker-compose.yml`.
2) Mettre `NODE_ENV=development` dans `.env`.
3) Rebuild backend :
```
sudo docker compose up -d --build backend
```

### CORS admin/storefront (procedure)

Objectif : autoriser le navigateur a appeler l'API depuis le storefront et l'admin.

1) Verifier `.env` :
```
ADMIN_CORS=http://<IP_DU_SERVEUR>:9000
STORE_CORS=http://<IP_DU_SERVEUR>:8000
```

2) Rebuild backend pour appliquer les variables :
```
sudo docker compose up -d --build backend
```

3) Test CORS (storefront) :
```
curl -i -H "Origin: http://<IP_DU_SERVEUR>:8000" http://<IP_DU_SERVEUR>:9000/store/products
```

### Admin en HTTP (procedure NODE_ENV)

Objectif : eviter le blocage des cookies `Secure` en HTTP.

1) Rendre `NODE_ENV` configurable dans `docker-compose.yml` :
```
NODE_ENV=${NODE_ENV}
```

2) Dans `.env` :
```
NODE_ENV=development
```

3) Rebuild backend :
```
sudo docker compose up -d --build backend
```

### Patch Medusa (TypeORM update vide)

Probleme :
- Erreur TypeORM `Empty criteria(s) are not allowed for the update method`.
- Medusa appelle `update({}, { is_installed: false })` sans criteres.

Correctif applique :
1) Script de patch : `backend/scripts/patch-medusa.js`
2) Execution automatique : `postinstall` dans `backend/package.json`
3) Dockerfile : `COPY scripts ./scripts` avant `npm install`

Fichiers Medusa patches :
- `node_modules/@medusajs/medusa/dist/services/payment-provider.js`
- `node_modules/@medusajs/medusa/dist/services/notification.js`
- `node_modules/@medusajs/medusa/dist/services/fulfillment-provider.js`
- `node_modules/@medusajs/medusa/dist/services/tax-provider.js`

Remplacement effectue (exemple) :
- Avant : `model.update({}, { is_installed: false })`
- Apres : `model.createQueryBuilder().update().set({ is_installed: false }).where('1=1').execute()`

Rebuild obligatoire pour appliquer le patch :
```
sudo docker compose build --no-cache backend
sudo docker compose up -d backend
```

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

## 11) Procedure Git (push + alignement serveur)

Objectif : pousser le code vers `chillka`, puis aligner `huitral` **sans perdre de changements**.

### 11.1 Depuis votre machine de dev
```
git status
git add -A
git commit -m "feat: mise a jour storefront + checkout"
git push origin main
```
Explication rapide :
- `git status` : voir les fichiers modifies.
- `git add -A` : ajouter tous les changements a l'index.
- `git commit -m "..."` : creer un snapshot local.
- `git push origin main` : envoyer le snapshot sur chillka (branche `main`).

### 11.2 Sur `huitral` avec changements locaux
Option recommandee (garder les changements) :
```
cd /var/www/lucien-sens-bon
git status
git add -A
git commit -m "wip: changements locaux huitral"
git push origin HEAD
git fetch origin
git checkout main
git merge origin/main
```
Explication rapide :
- `git status` : verifier l'etat local.
- `git add -A` + `git commit` : sauvegarder les changements locaux pour ne rien perdre.
- `git push origin HEAD` : publier ces changements sur chillka.
- `git fetch origin` : recuperer les nouvelles refs.
- `git checkout main` : se replacer sur la branche principale.
- `git merge origin/main` : integrer la version centrale dans huitral.

Option rapide (stocker temporairement) :
```
cd /var/www/lucien-sens-bon
git status
git stash push -m "wip huitral"
git fetch origin
git checkout main
git merge origin/main
git stash pop
git add -A
git commit -m "merge: main + wip huitral"
git push origin main
```
Explication rapide :
- `git stash push` : mettre les modifs de cote sans commit.
- `git fetch` / `git checkout` / `git merge` : mettre a jour huitral.
- `git stash pop` : remettre les changements au-dessus.
- `git add -A` + `git commit` + `git push` : enregistrer et publier.

### 11.3 Si vous voulez ecraser les changements locaux (attention)
```
cd /var/www/lucien-sens-bon
git fetch origin
git checkout main
git reset --hard origin/main
git clean -fd
```
Explication rapide :
- `git reset --hard origin/main` : ecrase tout avec la version centrale.
- `git clean -fd` : supprime les fichiers non suivis.

Notes :
- Ne pas committer `.env` (fichier local, secrets).
- En cas de blocage, supprimer `.git/index.lock` avant de relancer Git.

### 11.4 Comprendre les references Git (local vs distant)

Git stocke des pointeurs vers des commits. Ces pointeurs sont des references.

- Locales : `refs/heads/<branche>` (ex: `refs/heads/main`)
- Distantes : `refs/remotes/<remote>/<branche>` (ex: `refs/remotes/origin/main`)
- Tags : `refs/tags/<tag>`

Comment les voir :
```
git branch -a
```
Affiche les branches locales et distantes. Les distantes apparaissent sous `remotes/origin/...`.

```
git show-ref --heads
```
Liste les branches locales (refs/heads) et le commit pointe par chaque branche.

```
git show-ref --tags
```
Liste les tags (refs/tags). Si rien n'apparait, il n'y a pas de tags.

```
git show-ref --heads --tags --dereference
```
Affiche toutes les references et leurs commits. Utile si des tags pointent vers des objets annexes.

```
git show-ref --heads --quiet origin/main
```
Test silencieux : retourne un code de sortie 0 si la reference existe, 1 sinon.

Representation locale d'une branche distante :
- `origin/main` n'est pas une branche locale. C'est un **pointeur local** qui represente
  l'etat de la branche distante `main` a la date du dernier `git fetch`.
- Quand on fait `git fetch`, Git met a jour `refs/remotes/origin/main`.
- Quand on fait `git merge origin/main`, on integre cette reference distante dans la branche locale `main`.

### 11.5 Recuperer sur antel et nettoyer les fichiers .txt

#### a) Recuperer les mises a jour depuis chillka
Sur antel :
```
cd /mnt/e/Dev/Web-Works/Lucien-sens-bon
git fetch origin
git checkout main
git pull --ff-only
```
Explication rapide :
- `git fetch origin` : telecharge les refs distantes sans modifier la branche locale.
- `git checkout main` : se place sur la branche principale.
- `git pull --ff-only` : met a jour la branche locale **uniquement** si l'historique est lineaire.

Si antel a des changements locaux :
```
git status
git add -A
git commit -m "wip antel"
git pull --rebase
```
Explication rapide :
- `git commit` : sauvegarder les changements locaux.
- `git pull --rebase` : rejouer ces commits au-dessus de `origin/main` pour eviter un merge commit.

#### b) Retirer des fichiers .txt deja stages
Si des fichiers .txt ne doivent pas etre versionnes :
```
git restore --staged _fichier-avec-erreurs/*.txt
rm -f _fichier-avec-erreurs/*.txt
```
Explication rapide :
- `git restore --staged` : retire les fichiers de l'index sans toucher le disque.
- `rm -f` : supprime les fichiers localement.