first commit
This commit is contained in:
lfirmin
@@ -0,0 +1,139 @@
|
||||
# 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/`.
|
||||
Reference in New Issue
Block a user