Discord-Raid-bot/CLAUDE.md

# CLAUDE.md

## Contexte

Bot Discord de tracking de Personal Best (PB) pour les clan bosses du jeu Raid Shadow Legends.
Communauté RTF (3 clans : RTF, RTFC, RTFR).

## Branches

| Branche | Environnement | Chemin NAS |
|---------|--------------|------------|
| `main` | Production | `/share/CACHEDEV1_DATA/discord-bot-prod` |
| `dev` | Développement | `/share/CACHEDEV1_DATA/discord-bot-dev` |

`dev` est une branche permanente — ne jamais merger dans `main`.

## Déploiement

CI/CD via Forgejo Actions → runner `vm-runner` (192.168.1.53, Alpine) → rsync vers NAS QNAP (192.168.1.208).

Push sur `main` ou `dev` déclenche le déploiement automatique.

Secret requis dans Forgejo : `NAS_SSH_KEY` — **doit être encodé en base64** :
```bash
base64 -w 0 ~/.ssh/runner-nas
```
Coller le résultat dans le secret (pas le contenu brut du fichier).

## Persistance des données (NE PAS écraser)

Ces dossiers vivent sur le NAS et sont montés dans le container — jamais dans le repo, jamais écrasés par rsync :

| Dossier | Contenu |
|---------|---------|
| `data/` | Base SQLite (`bot_data.db`) |
| `screenshots/` | Captures d'écran des PBs |
| `logs/` | Logs du bot |

## Variables d'environnement (.env sur le NAS)

Fichier `.env` à créer manuellement sur le NAS dans chaque `DEPLOY_PATH` :

```
DISCORD_TOKEN=...
AUTHORIZED_CHANNEL_ID=...
```

## Structure

```
bot.py              # Point d'entrée, charge les cogs
config.py           # Config centralisée (token, chemins, boss, clans)
cogs/               # Commandes Discord (un fichier par fonctionnalité)
utils/              # Managers (DB, screenshots, mercy) et handlers
Dockerfile          # Image Python 3.9-slim
docker-compose.yml  # Déploiement container
```

## Boss supportés

- **Hydra** : normal, hard, brutal, nightmare
- **Chimera** : easy, normal, hard, brutal, nightmare, ultra
- **CvC** : Clan vs Clan

## Pièges connus — CI/CD

- **NAS_SSH_KEY doit être en base64** — `echo "..." > fichier` dans Alpine sh casse les sauts de ligne de la clé brute
- **Runner tourne dans Alpine** — `actions/checkout@v4` ne fonctionne pas (pas de Node.js) → utiliser `git clone`; `rsync` et `openssh-client` doivent être installés via `apk add`
- **Chemin Docker sur QNAP** : `/share/CACHEDEV1_DATA/.qpkg/container-station/usr/bin/docker` — `docker` n'est pas dans le `$PATH` SSH
- **Pas de `--build`** — le code est monté en volume (`./:/app`), un simple redémarrage suffit
- **Pas de `container_name`** — les envs prod et dev partagent le même NAS, un nom hardcodé crée un conflit ; Docker Compose dérive le nom depuis le dossier
- **rsync exclut `__pycache__/`** — créés par Docker (root), l'user Elewyn ne peut pas les supprimer via rsync `--delete`
- **rsync exclut `.github/`** — vestige de l'ancien CI GitHub Actions, ne pas envoyer sur le NAS
- **Clé SSH workstation** : `~/.ssh/runner-nas` (ed25519, autorisée dans `~/.ssh/authorized_keys` sur le NAS pour l'user Elewyn)