140 lines
5.0 KiB
Markdown
140 lines
5.0 KiB
Markdown
# ticketbot — Bot Discord de gestion de tickets (Phase 1)
|
|
|
|
Bot Discord en Go pour la gestion de tickets : claim system, re-up automatique, transcripts HTML, hot reload de config.
|
|
|
|
## Stack
|
|
|
|
- **Go 1.22+** · bwmarrin/discordgo · modernc.org/sqlite (pas de CGO) · gopkg.in/yaml.v3 · fsnotify · log/slog
|
|
|
|
## Installation
|
|
|
|
### Prérequis
|
|
|
|
- Go 1.22+ **ou** Docker + Docker Compose
|
|
- Un bot Discord configuré (voir ci-dessous)
|
|
|
|
### Configurer le bot Discord
|
|
|
|
1. Aller sur [discord.com/developers](https://discord.com/developers/applications)
|
|
2. Créer une application → Bot
|
|
3. Activer les **Privileged Gateway Intents** suivants :
|
|
- `Server Members Intent` (GUILD_MEMBERS)
|
|
- `Message Content Intent` (MESSAGE_CONTENT)
|
|
4. Récupérer le **Token** et l'**Application ID**
|
|
5. Inviter le bot avec les permissions suivantes (valeur `536890374208`) :
|
|
- Manage Channels
|
|
- Manage Roles *(seulement pour les rôles en dessous du rôle du bot)*
|
|
- Read Messages / View Channels
|
|
- Send Messages
|
|
- Read Message History
|
|
- Attach Files
|
|
- Manage Messages
|
|
|
|
> **Hiérarchie de rôles** : le bot ne peut gérer que des rôles **en dessous** de son rôle le plus haut dans le serveur. Placez le rôle du bot au-dessus des staff roles concernés.
|
|
|
|
### Configuration
|
|
|
|
```bash
|
|
cp config.yaml.example config.yaml
|
|
cp .env.example .env
|
|
```
|
|
|
|
Editer `.env` :
|
|
```env
|
|
DISCORD_TOKEN=ton_token_ici
|
|
DISCORD_APP_ID=ton_app_id_ici
|
|
GUILD_ID=ton_guild_id_ici
|
|
LOG_LEVEL=info # debug / info / warn / error
|
|
LOG_FORMAT=text # text (dev) ou json (prod)
|
|
```
|
|
|
|
Editer `config.yaml` en remplaçant tous les `*_ID` par les vrais IDs Discord (clic droit → Copier l'ID avec mode développeur activé).
|
|
|
|
## Démarrage
|
|
|
|
### Sans Docker
|
|
|
|
```bash
|
|
go build -o ticketbot ./cmd/bot
|
|
./ticketbot
|
|
```
|
|
|
|
### Avec Docker Compose
|
|
|
|
```bash
|
|
docker compose up -d
|
|
docker compose logs -f
|
|
```
|
|
|
|
## Commandes Discord
|
|
|
|
| Commande | Permission | Description |
|
|
|----------|-----------|-------------|
|
|
| `/panel_send <panel> <channel>` | `admin_role` | Envoie un panel de tickets dans un channel |
|
|
| `/ticket close [reason]` | staff du ticket ou admin | Ferme le ticket (génère transcript) |
|
|
| `/ticket add <user>` | staff du ticket ou admin | Ajoute un user au channel ticket |
|
|
| `/ticket remove <user>` | staff du ticket ou admin | Retire un user du channel ticket |
|
|
| `/ticket rename <name>` | staff du ticket ou admin | Renomme le channel ticket |
|
|
| `/ticket transcript` | staff du ticket ou admin | Génère le transcript HTML à la volée |
|
|
| `/ticket reclaim` | staff du type du ticket ou admin | Reprend un ticket claimé par un staff parti |
|
|
| `/convocation <user> <reason>` | tout staff (n'importe quel type) | Crée une convocation |
|
|
|
|
> Toutes les commandes `/ticket *` doivent être utilisées **dans** le channel du ticket.
|
|
|
|
## Système de claim
|
|
|
|
- À l'ouverture d'un ticket, un message est posté dans `claim_channel` avec un bouton **Claim**
|
|
- Après `claim_reup_minutes` minutes sans claim, le message est re-posté avec un ping `<@&staff_role>`
|
|
- Le re-up continue jusqu'au claim
|
|
- Au redémarrage du bot, les boucles re-up sont automatiquement reprises depuis la DB
|
|
|
|
## Autorisation
|
|
|
|
**Toute la logique d'autorisation repose sur les rôles configurés dans `config.yaml`**, jamais sur les permissions Discord natives.
|
|
|
|
- `admin_role` : accès à toutes les commandes admin et staff
|
|
- `staff_role` par type : claim du type concerné, toutes les actions `/ticket *` sur les tickets de ce type
|
|
- `/convocation` : tout membre ayant au moins un staff_role (tous types confondus)
|
|
|
|
## Hot reload
|
|
|
|
Modifier `config.yaml` → le bot recharge automatiquement dans les 500ms.
|
|
- Si la config est invalide, l'ancienne est conservée et l'erreur est loggée
|
|
- Les tickets ouverts ne sont pas impactés par les changements de config
|
|
|
|
## Structure des fichiers
|
|
|
|
```
|
|
ticketbot/
|
|
├── cmd/bot/main.go # Point d'entrée
|
|
├── internal/
|
|
│ ├── config/ # Config YAML + hot reload
|
|
│ ├── db/ # SQLite + repos
|
|
│ ├── tickets/ # Logique métier + AuthService
|
|
│ ├── claim/ # Gestionnaire claim + re-up
|
|
│ ├── transcript/ # Génération HTML
|
|
│ ├── discord/ # Session, router, commandes, composants
|
|
│ └── logger/ # Logs channel Discord
|
|
├── transcripts/ # Transcripts HTML générés (gitignore)
|
|
├── data/ # Base SQLite (gitignore)
|
|
├── config.yaml.example
|
|
├── .env.example
|
|
├── Dockerfile
|
|
└── docker-compose.yml
|
|
```
|
|
|
|
## Logs
|
|
|
|
- Format `text` en dev, `json` en prod (via `LOG_FORMAT`)
|
|
- Niveaux : `debug` / `info` / `warn` / `error` (via `LOG_LEVEL`)
|
|
- En `debug` : log de chaque interaction, action claim/re-up/close, hot reload, requêtes DB lentes
|
|
|
|
## Déploiement
|
|
|
|
1. Cloner le repo
|
|
2. Configurer `.env` et `config.yaml`
|
|
3. `docker compose up -d`
|
|
4. Vérifier les logs : `docker compose logs -f`
|
|
|
|
Les données SQLite sont persistées dans `./data/`, les transcripts dans `./transcripts/`.
|