prod: UI Optimisée mise en production
- Documentation archivée et réorganisée - Backend: Ajout tests, migrations, library service, rate limiting - Frontend: Suppression Flutter, focus sur interface web HTML/JS - Tailwind CSS ajouté pour le style - Améliorations UX et corrections bugs Generated with [Claude Code](https://claude.com/claude-code) via [Happy](https://happy.engineering) Co-Authored-By: Claude <noreply@anthropic.com> Co-Authored-By: Happy <yesreply@happy.engineering>
This commit is contained in:
root
@@ -0,0 +1,293 @@
|
||||
# Alembic Migration Guide - AudiOhm
|
||||
|
||||
## Overview
|
||||
|
||||
Ce guide explique comment utiliser les migrations Alembic pour gérer le schéma de base de données AudiOhm.
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
backend/
|
||||
├── alembic.ini # Configuration Alembic
|
||||
├── alembic/
|
||||
│ ├── env.py # Configuration de l'environnement
|
||||
│ ├── script.py.mako # Template pour les migrations
|
||||
│ ├── versions/ # Dossier des migrations
|
||||
│ │ └── 001_add_library_tables.py # Migration initiale
|
||||
│ └── README # Documentation Alembic
|
||||
```
|
||||
|
||||
## Migration Actuelle
|
||||
|
||||
### 001_add_library_tables.py
|
||||
|
||||
Cette migration crée deux tables pour la fonctionnalité de bibliothèque personnelle:
|
||||
|
||||
#### 1. Table `listening_history`
|
||||
Enregistre l'historique d'écoute des utilisateurs.
|
||||
|
||||
**Colonnes:**
|
||||
- `id` (UUID, PRIMARY KEY): Identifiant unique de l'historique
|
||||
- `user_id` (UUID, FOREIGN KEY → users.id): Référence à l'utilisateur
|
||||
- `track_id` (UUID, FOREIGN KEY → tracks.id): Référence à la musique
|
||||
- `played_for` (INTEGER): Durée d'écoute en secondes
|
||||
- `completed` (BOOLEAN): Si le morceau a été écouté entièrement
|
||||
- `source` (VARCHAR(50)): Source de lecture (library, playlist, search, etc.)
|
||||
- `played_at` (DATETIME): Quand la lecture a eu lieu
|
||||
- `created_at` (DATETIME): Date de création de l'enregistrement
|
||||
|
||||
**Index:**
|
||||
- `ix_listening_history_id`: Index sur l'ID (recherche rapide)
|
||||
- `ix_listening_history_user_id`: Index sur user_id (filtrage par utilisateur)
|
||||
- `ix_listening_history_track_id`: Index sur track_id (filtrage par morceau)
|
||||
- `ix_listening_history_played_at`: Index sur played_at (tri chronologique)
|
||||
- `ix_listening_history_user_played`: Index composite (user_id, played_at) pour l'historique
|
||||
- `ix_listening_history_user_track`: Index composite (user_id, track_id) pour vérifier les doublons
|
||||
|
||||
#### 2. Table `liked_tracks`
|
||||
Enregistre les morceaux aimés/favoris des utilisateurs.
|
||||
|
||||
**Colonnes:**
|
||||
- `id` (UUID, PRIMARY KEY): Identifiant unique
|
||||
- `user_id` (UUID, FOREIGN KEY → users.id): Référence à l'utilisateur
|
||||
- `track_id` (UUID, FOREIGN KEY → tracks.id): Référence à la musique
|
||||
- `notes` (VARCHAR(1000)): Notes personnelles de l'utilisateur sur le morceau
|
||||
- `created_at` (DATETIME): Date d'ajout aux favoris
|
||||
- `updated_at` (DATETIME): Date de dernière mise à jour
|
||||
|
||||
**Index:**
|
||||
- `ix_liked_tracks_id`: Index sur l'ID
|
||||
- `ix_liked_tracks_user_id`: Index sur user_id
|
||||
- `ix_liked_tracks_track_id`: Index sur track_id
|
||||
- `ix_liked_tracks_user_track`: Index UNIQUE composite (user_id, track_id) - empêche les doublons
|
||||
|
||||
## Commandes Alembic
|
||||
|
||||
### Vérifier l'état actuel
|
||||
|
||||
```bash
|
||||
cd /opt/audiOhm/backend
|
||||
alembic current
|
||||
```
|
||||
|
||||
Affiche la version actuelle de la base de données.
|
||||
|
||||
### Voir l'historique des migrations
|
||||
|
||||
```bash
|
||||
alembic history
|
||||
```
|
||||
|
||||
Affiche toutes les migrations et leur ordre.
|
||||
|
||||
### Voir les têtes de branches
|
||||
|
||||
```bash
|
||||
alembic heads
|
||||
```
|
||||
|
||||
Affiche les dernières versions de chaque branche.
|
||||
|
||||
### Voir les détails d'une migration
|
||||
|
||||
```bash
|
||||
alembic show 001_add_library_tables
|
||||
```
|
||||
|
||||
Affiche les détails d'une migration spécifique.
|
||||
|
||||
### Créer une nouvelle migration
|
||||
|
||||
```bash
|
||||
alembic revision -m "Description de la migration"
|
||||
```
|
||||
|
||||
Crée un nouveau fichier de migration vide à éditer manuellement.
|
||||
|
||||
### Créer une migration automatique
|
||||
|
||||
```bash
|
||||
alembic revision --autogenerate -m "Description de la migration"
|
||||
```
|
||||
|
||||
Génère automatiquement la migration en comparant les modèles SQLAlchemy avec la base de données.
|
||||
|
||||
**Note:** Pour utiliser `--autogenerate`, vous devez installer `psycopg2` ou modifier `env.py` pour utiliser le bon pilote.
|
||||
|
||||
### Appliquer les migrations (upgrade)
|
||||
|
||||
```bash
|
||||
# Appliquer toutes les migrations
|
||||
alembic upgrade head
|
||||
|
||||
# Appliquer une migration spécifique
|
||||
alembic upgrade 001_add_library_tables
|
||||
|
||||
# Appliquer les n prochaines migrations
|
||||
alembic upgrade +1
|
||||
```
|
||||
|
||||
### Annuler les migrations (downgrade)
|
||||
|
||||
```bash
|
||||
# Annuler la dernière migration
|
||||
alembic downgrade -1
|
||||
|
||||
# Annuler jusqu'à la base (tout annuler)
|
||||
alembic downgrade base
|
||||
|
||||
# Annuler jusqu'à une migration spécifique
|
||||
alembic downgrade <revision_id>
|
||||
```
|
||||
|
||||
### Vérifier le SQL sans l'exécuter
|
||||
|
||||
```bash
|
||||
# Voir le SQL de l'upgrade
|
||||
alembic upgrade head --sql
|
||||
|
||||
# Voir le SQL du downgrade
|
||||
alembic downgrade -1 --sql
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Fichier alembic.ini
|
||||
|
||||
Le fichier `/opt/audiOhm/backend/alembic.ini` contient:
|
||||
|
||||
- `script_location`: Emplacement des scripts de migration (alembic)
|
||||
- `sqlalchemy.url`: URL de connexion à la base de données
|
||||
- `file_template`: Format de nommage des fichiers de migration
|
||||
|
||||
### Fichier env.py
|
||||
|
||||
Le fichier `/opt/audiOhm/backend/alembic/env.py`:
|
||||
|
||||
- Charge les variables d'environnement depuis `.env`
|
||||
- Importe les modèles SQLAlchemy
|
||||
- Configure la connexion à la base de données
|
||||
- Convertit l'URL async en sync pour Alembic
|
||||
|
||||
## Utilisation Typique
|
||||
|
||||
### Première installation
|
||||
|
||||
1. **Assurez-vous que PostgreSQL est installé et configuré**
|
||||
|
||||
2. **Créez la base de données:**
|
||||
```bash
|
||||
sudo -u postgres psql
|
||||
CREATE DATABASE spotify_le_2;
|
||||
CREATE USER spotify WITH PASSWORD 'spotify_password';
|
||||
GRANT ALL PRIVILEGES ON DATABASE spotify_le_2 TO spotify;
|
||||
\q
|
||||
```
|
||||
|
||||
3. **Configurez les variables d'environnement:**
|
||||
```bash
|
||||
cd /opt/audiOhm/backend
|
||||
cp .env.example .env
|
||||
# Éditez .env avec vos paramètres
|
||||
```
|
||||
|
||||
4. **Appliquez les migrations:**
|
||||
```bash
|
||||
cd /opt/audiOhm/backend
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
### Développement
|
||||
|
||||
Lorsque vous modifiez les modèles SQLAlchemy:
|
||||
|
||||
1. **Créez une nouvelle migration:**
|
||||
```bash
|
||||
alembic revision --autogenerate -m "Description des changements"
|
||||
```
|
||||
|
||||
2. **Vérifiez le fichier généré:**
|
||||
```bash
|
||||
cat alembic/versions/xxx_description.py
|
||||
```
|
||||
|
||||
3. **Appliquez la migration:**
|
||||
```bash
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
### Production
|
||||
|
||||
1. **Sauvegardez la base de données avant la migration:**
|
||||
```bash
|
||||
pg_dump spotify_le_2 > backup_before_migration.sql
|
||||
```
|
||||
|
||||
2. **Appliquez les migrations:**
|
||||
```bash
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
3. **Vérifiez que l'application fonctionne toujours**
|
||||
|
||||
## Dépannage
|
||||
|
||||
### Erreur: "No module named 'psycopg2'"
|
||||
|
||||
Alembic essaie d'utiliser psycopg2 par défaut. Pour utiliser asyncpg:
|
||||
|
||||
1. Installez psycopg2:
|
||||
```bash
|
||||
pip install psycopg2-binary
|
||||
```
|
||||
|
||||
2. OU modifiez la migration pour ne pas utiliser de connexions réelles
|
||||
|
||||
### Erreur: "No config file 'alembic.ini' found"
|
||||
|
||||
Vous n'êtes pas dans le bon répertoire. Exécutez:
|
||||
```bash
|
||||
cd /opt/audiOhm/backend
|
||||
```
|
||||
|
||||
### Vérifier si les tables existent
|
||||
|
||||
```bash
|
||||
sudo -u postgres psql spotify_le_2
|
||||
\dt
|
||||
SELECT * FROM alembic_version;
|
||||
\q
|
||||
```
|
||||
|
||||
### Réinitialiser complètement la base de données
|
||||
|
||||
```bash
|
||||
# Supprimer toutes les migrations (DANGER!)
|
||||
alembic downgrade base
|
||||
|
||||
# Supprimer toutes les tables
|
||||
sudo -u postgres psql spotify_le_2
|
||||
DROP SCHEMA public CASCADE;
|
||||
CREATE SCHEMA public;
|
||||
GRANT ALL ON SCHEMA public TO spotify;
|
||||
GRANT ALL ON SCHEMA public TO public;
|
||||
\q
|
||||
|
||||
# Réappliquer les migrations
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
## Bonnes Pratiques
|
||||
|
||||
1. **Toujours vérifier** le SQL généré avant d'appliquer une migration
|
||||
2. **Faire des sauvegardes** avant les migrations en production
|
||||
3. **Tester les migrations** dans un environnement de développement d'abord
|
||||
4. **Utiliser des transactions** Alembic utilise déjà des transactions automatiques
|
||||
5. **Documenter** les migrations avec des messages clairs
|
||||
6. **Ne pas modifier** les migrations déjà appliquées (créez-en une nouvelle)
|
||||
|
||||
## Références
|
||||
|
||||
- [Documentation Alembic](https://alembic.sqlalchemy.org/)
|
||||
- [Documentation SQLAlchemy](https://docs.sqlalchemy.org/)
|
||||
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
|
||||
Reference in New Issue
Block a user