🎶 SoundVault CLI

Una aplicación de línea de comandos profesional para gestionar y valorar tu colección de álbumes musicales con arquitectura modular, manejo de errores robusto y funcionalidades avanzadas.

📋 Características

Gestión de Álbumes

• ✅ Añadir álbumes con información detallada (artista, año, género, rating, mood, etc.)
• ✏️ Editar álbumes existentes con todos sus campos
• 🗑️ Eliminar álbumes con confirmación de seguridad
• 📊 Sistema de valoración dual: estrellas (1-5) y rating decimal (0-10)
• 🎧 Plataformas flexibles: Elige de la lista o escribe cualquier plataforma personalizada
• 😌 Moods personalizables: Usa los ejemplos o escribe el mood que quieras

Búsqueda y Filtros

• 🔍 Búsqueda de texto completo: busca en nombre, artista, género, estilo y review
• 🔎 Filtros avanzados: por artista, plataforma, año, género, mood, rango de rating
• 📋 Listado completo con ordenamiento personalizado

Estadísticas y Análisis

• 📈 Estadísticas completas: promedios, totales, distribuciones
• 🏆 Top N álbumes: encuentra tus mejores valorados
• 📊 Análisis por categorías: plataforma, mood, género

Importar/Exportar

• 📤 Exportar a CSV/JSON: comparte tu colección
• 📥 Importar desde CSV/JSON: carga álbumes masivamente
• 💾 Sistema de backups: backups automáticos antes de importar y manuales

🚀 Instalación

Requisitos

• Python 3.7+
• SQLite3 (incluido en Python)

Configuración

# Clona o descarga el proyecto
cd albums-cli

# (Opcional) Crea un entorno virtual
python -m venv venv
venv\Scripts\activate  # Windows
# source venv/bin/activate  # Linux/Mac

# No se requieren dependencias externas (solo stdlib)
# Para desarrollo, puedes instalar:
# pip install mypy pytest black

# Ejecuta la aplicación
python main.py

La base de datos y los logs se crearán automáticamente en la carpeta data/ la primera vez que ejecutes el programa.

💻 Uso

Menú Principal

Al ejecutar el programa, verás el menú principal con todas las opciones organizadas:

==================================================
🎶 SoundVault CLI
==================================================

Gestión de álbumes:
  1. ➕ Añadir un álbum
  2. 📋 Listar todos los álbumes
  3. 🔍 Buscar álbumes
  4. 🔎 Filtrar álbumes (avanzado)
  5. ✏️  Editar un álbum
  6. 🗑️  Eliminar un álbum

Estadísticas y análisis:
  7. 📊 Ver estadísticas
  8. 🏆 Top álbumes

Importar/Exportar:
  9. 📤 Exportar datos (CSV/JSON)
  10. 📥 Importar datos (CSV/JSON)
  11. 💾 Crear backup

Otros:
  0. 🚪 Salir

📁 Estructura del Proyecto

albums-cli/
├── main.py              # Archivo principal - ¡EJECUTA ESTE!
├── README.md            # Documentación
├── requirements.txt     # Dependencias
├── .gitignore          # Configuración de Git
│
├── src/                 # Código fuente modular
│   ├── __init__.py
│   ├── config.py        # Configuración y constantes
│   ├── models.py        # Modelos de datos (Album)
│   ├── database.py      # Operaciones de base de datos
│   ├── validators.py    # Validadores de entrada
│   └── import_export.py # Importación/exportación
│
├── data/                # Datos (creado automáticamente)
│   ├── soundvault.db    # Base de datos SQLite
│   ├── soundvault.log   # Archivo de logs
│   └── soundvault_backup_*.db  # Backups
│
├── examples/            # Archivos de ejemplo
│   ├── example_import.json
│   └── example_import.csv
│

🏗️ Arquitectura

El proyecto sigue principios de diseño modular:

• Separación de responsabilidades: Cada módulo en src/ tiene una función específica
• Manejo de errores: Excepciones personalizadas (DatabaseError)
• Logging: Sistema de logs completo en archivo y consola
• Type hints: Anotaciones de tipo para mejor mantenibilidad
• Dataclasses: Modelos de datos inmutables y tipados
• Validadores: Funciones reutilizables de validación
• Índices de BD: Optimización de consultas frecuentes

📊 Formato de Importación

CSV

album_name,artists,release_year,genre,style,stars,decimal_rating,mood,relisten,platform,review,listened_date
OK Computer,Radiohead,1997,Rock,Alternative Rock,5,9.6,Chill,True,Spotify,Amazing album,2025-12-15

JSON

[
  {
    "album_name": "OK Computer",
    "artists": "Radiohead",
    "release_year": 1997,
    "genre": "Rock",
    "style": "Alternative Rock",
    "stars": 5,
    "decimal_rating": 9.6,
    "mood": "Chill",
    "relisten": true,
    "platform": "Spotify",
    "review": "Amazing album",
    "listened_date": "2025-12-15"
  }
]

🐛 Debugging y Logs

Los logs se guardan automáticamente en data/soundvault.log con información de:

• Operaciones de base de datos (INSERT, UPDATE, DELETE)
• Errores y excepciones
• Importaciones y exportaciones
• Creación de backups

🤝 Contribuciones

Siéntete libre de hacer fork del proyecto y enviar pull requests con mejoras.

📝 Licencia

Este proyecto es de código abierto y está disponible para uso personal y educativo.