# Exploitation — Chat SPBoucher AI

## Emplacement

| | |
|---|---|
| Nœud | **M4M64c** (Mac Studio M4 Max, 16 c / 64 Go), épinglé dans le manifeste |
| Dossier | `~/apps/chat-spboucher-ai` (clone git, `origin` = spbgit `chat-spboucher-ai.git`) |
| Port | 8500 (PM2 `chat-spboucher-ai`) |
| Base | PostgreSQL 17 Homebrew local, base `chat_spboucher`, rôle `chat_spb`, extension `vector` |
| Fichiers | `~/apps/chat-spboucher-ai/data/uploads/` (mode 600) |
| Domaine | `chat.spboucher.ai` → MacLustr Tunnel (BHS64 Caddy → wg1 M4M64c:8500) ; DNS GoDaddy `A → 51.161.112.61` |
| Secrets | `M1M32:~/dispatch/apps/chat-spboucher-ai.json` (mode 600) et `~/Desktop/Cluster/secrets/chat-spboucher-ai.env` sur le laptop |
| Santé | `GET /api/health` → `{ok:true, db:true, modelsAvailable:N}` |

## Processus PM2 (déclarés dans le manifeste mld)

| Processus | Rôle | Planification |
|---|---|---|
| `chat-spboucher-ai` | `next start -H 0.0.0.0 -p 8500` | permanent, `max_memory_restart 2G` |
| `chat-spboucher-ai-registry` | `tsx scripts/registry-refresh.ts` — relit les listings OpenAI/Anthropic, marque les modèles disparus, importe les benchmarks | `17 5 * * *` |
| `chat-spboucher-ai-backup` | `scripts/backup.sh` — dump Postgres + uploads, chiffré AES-256 (`~/.config/chat-spboucher-ai/backup.pass`), 14 jours dans `~/backups/chat-spboucher-ai` | `45 3 * * *` |

## Déploiement initial (fait le 2026-11-01)

```bash
# laptop
cd ~/Desktop/cluster-skill
./mld stage ~/Desktop/Cluster/projets/chat-spboucher-ai chat-spboucher-ai
./mld deploy chat-spboucher-ai --node M4M64c     # post_sync : pnpm install, db:migrate, build, registry:refresh ; route tunnel posée
./mld adopt chat-spboucher-ai                     # le dossier du nœud devient un clone git (origin spbgit)
ssh M4M64c 'cd ~/apps/chat-spboucher-ai && set -a && . ./.env.production && set +a && pnpm setup:owner'   # mot de passe du propriétaire (interactif)
```

## Modifier l'app (remote-first)

```bash
ssh M4M64c
cd ~/apps/chat-spboucher-ai
# éditer, puis :
pnpm build && pm2 restart chat-spboucher-ai
git add -A && git commit -m "…" && git push origin main
```
Le laptop ne garde qu'un miroir (`git pull`). Nouvelle migration : ajouter `db/migrations/00N_*.sql`, puis `set -a; . ./.env.production; set +a; pnpm db:migrate`.

## Rollback

```bash
ssh M4M64c 'cd ~/apps/chat-spboucher-ai && git log --oneline -5'
ssh M4M64c 'cd ~/apps/chat-spboucher-ai && git checkout <commit> -- . && pnpm install --frozen-lockfile && pnpm build && pm2 restart chat-spboucher-ai'
# base : scripts/restore.sh ~/backups/chat-spboucher-ai/csa-<date>.tar.enc --yes  (arrête/relance PM2, remplace DB + uploads)
```
Testé le 2026-11-01 : `pm2 restart` + healthcheck < 5 s ; restauration sur la base locale de développement.

## Journaux

```bash
ssh M4M64c 'pm2 logs chat-spboucher-ai --lines 200'      # requêtes, erreurs fournisseurs (JSON Next.js)
ssh M4M64c 'psql chat_spboucher -c "select at, kind, model_id, status, left(error,80) from usage_events order by at desc limit 30"'
ssh M4M64c 'psql chat_spboucher -c "select * from tool_executions order by created_at desc limit 20"'
```

## Pannes courantes

| Symptôme | Cause probable | Action |
|---|---|---|
| 502 sur chat.spboucher.ai | PM2 arrêté ou wg1 tombé | `mld heal` (automatique toutes les 5 min) ; `mld health chat-spboucher-ai` |
| `/api/health` → `db:false` | Postgres arrêté | `ssh M4M64c 'brew services start postgresql@17'` |
| 402 « Limite quotidienne atteinte » | garde-fou local de dépenses | Réglages → Dépenses |
| Modèle « indisponible » soudainement | retiré par le fournisseur (404 deprecated) | normal : le rafraîchissement nocturne le masque ; choisir un autre modèle |
| Réponse vide d'un modèle de raisonnement OpenAI | budget de sortie consommé par le raisonnement | augmenter « jetons max » ou baisser l'effort |

## Sauvegarde / restauration

- Sauvegarde chiffrée nocturne (`scripts/backup.sh`) ; la phrase de passe est générée au premier lancement dans `~/.config/chat-spboucher-ai/backup.pass` **et doit être copiée** dans `~/Desktop/Cluster/secrets/`.
- Restauration : `scripts/restore.sh <fichier> --yes`.
- Export utilisateur : conversation (Markdown/JSON), mémoire (JSON/Markdown), rapport de recherche (MD/DOCX/PDF via impression).