StockTracker - Seguimiento de Empresas Cotizadas

StockTracker es una aplicación web moderna para monitorear precios de acciones en tiempo real, visualizar gráficos históricos y gestionar alertas de precio. Permite seguimiento centralizado de múltiples empresas cotizadas con datos de hasta 1 año de histórico.

🎯 Características Principales

Dashboard

• Índices de Mercado: Visualización de SPY, QQQ, DIA, VIX en tiempo real
• Mis Empresas: Vista rápida de todas las empresas en tu portfolio con precios actuales y cambios
• Estadísticas: Total de empresas, alertas activas y noticias guardadas

Gestión de Empresas

• Búsqueda y adición de empresas por símbolo bursátil
• Almacenamiento automático de 1 año de datos históricos al agregar una empresa
• Gestión de lista personal de empresas monitoradas
• Eliminación de empresas del seguimiento

Detalles de Empresa (Vista Dedicada)

• Gráfico Interactivo: Visualización de precios de cierre y volumen con Plotly
• Noticias Recientes: Panel lateral con últimas noticias de la empresa
• Tema light/dark automático según preferencias del usuario
• Datos de hasta 365 días de histórico

Sistema de Alertas

• Alertas de precio subiendo a un nivel específico
• Alertas de precio bajando a un nivel específico
• Alertas de pico de volumen
• Notificaciones en navegador
• Gestión completa: crear, editar, eliminar alertas

Noticias y Sentimiento

• Noticias en tiempo real de empresas monitoreadas
• Análisis de sentimiento (positivo, negativo, neutral)
• Guardar/marcar noticias importantes
• Filtrado por noticias guardadas

Tema Adaptable

• Soporte completo para modo Light y Dark
• Persistencia de preferencias en localStorage
• Gráficos y UI adaptativos al tema seleccionado

🛠️ Stack Tecnológico

Backend

• Flask: Framework web Python
• SQLAlchemy: ORM para base de datos
• SQLite: Base de datos por defecto
• Finnhub API: Datos de mercado en tiempo real (con fallback a yfinance)
• Flask-CORS: Soporte CORS

Frontend

• Vue 3: Framework JavaScript reactivo
• Tailwind CSS: Estilos utility-first
• Plotly.js: Gráficos interactivos
• Axios: Cliente HTTP
• Font Awesome: Iconografía

Servicios de Datos

• Finnhub: API principal para datos de mercado (requiere API key)
• yfinance: Fallback automático para obtener datos históricos

📋 Requisitos Previos

• Python 3.8+
• pip o conda
• Navegador moderno (Chrome, Firefox, Safari, Edge)
• (Opcional) Clave API de Finnhub para datos premium

🚀 Instalación y Configuración

1. Clonar el repositorio

git clone https://github.com/tu-usuario/StockTracker.git
cd StockTracker

🏷️ GitHub Topics

python · flask · stock-market · portfolio-tracker · financial-analysis · plotly · vuejs · tailwindcss · candlestick-chart · investing · rest-api · stock-tracker

2. Crear entorno virtual

python -m venv venv
source venv/bin/activate  # En Windows: venv\Scripts\activate

3. Instalar dependencias

pip install -r requirements.txt

4. Configurar variables de entorno

# Opcional: Clave API de Finnhub
export FINNHUB_API_KEY="tu_clave_api_aqui"

# Opcional: Seleccionar proveedor de datos
export DATA_PROVIDER="yfinance"  # o "finnhub" (defecto)

# Opcional: Clave secreta para sesiones
export SECRET_KEY="una-clave-secreta-fuerte"

5. Inicializar base de datos (opcional)

python seed_prices.py  # Genera datos de prueba

6. Ejecutar la aplicación

python app.py

La aplicación estará disponible en http://localhost:5000

📁 Estructura del Proyecto

StockTrackerKimi/
├── app.py                 # Aplicación principal Flask
├── models.py              # Modelos de base de datos (SQLAlchemy)
├── services.py            # Servicios de datos (Finnhub, yfinance)
├── requirements.txt       # Dependencias Python
├── seed_prices.py         # Script para generar datos de prueba
├── instance/              # Base de datos SQLite (generada automáticamente)
├── static/
│   ├── css/
│   │   └── styles.css     # Estilos personalizados
│   └── js/
│       └── app.js         # Lógica principal Vue 3
└── templates/
    ├── index.html         # Página principal (dashboard, empresas, alertas, noticias)
    └── company.html       # Página de detalles de empresa (gráfico + noticias)

🔌 API Endpoints

Empresas

• GET /api/companies - Listar todas las empresas
• POST /api/companies - Agregar nueva empresa
• DELETE /api/companies/<id> - Eliminar empresa
• GET /api/companies/search/<keyword> - Buscar empresas

Precios

• GET /api/companies/<id>/prices - Histórico de precios (últimos 30 días)
• GET /api/companies/<id>/quote - Cotización en tiempo real

Alertas

• GET /api/alerts - Listar alertas
• POST /api/alerts - Crear alerta
• PUT /api/alerts/<id> - Actualizar alerta
• DELETE /api/alerts/<id> - Eliminar alerta

Noticias

• GET /api/companies/<id>/news - Noticias de una empresa
• PUT /api/news/<id> - Actualizar estado (guardada/importante)
• GET /api/news/saved - Noticias guardadas

Dashboard

• GET /api/dashboard - Datos del dashboard (índices, empresas, estadísticas)

📊 Modelos de Datos

Company

{
    "id": int,
    "symbol": str,           # Símbolo bursátil (ej: AAPL)
    "name": str,             # Nombre de la empresa
    "sector": str,           # Sector industrial
    "industry": str,         # Industria específica
    "exchange": str,         # Bolsa (ej: NASDAQ)
    "currency": str          # Divisa (ej: USD)
}

StockPrice

{
    "id": int,
    "company_id": int,
    "open_price": float,
    "high_price": float,
    "low_price": float,
    "close_price": float,
    "volume": int,
    "date": date,
    "is_realtime": bool
}

Alert

{
    "id": int,
    "company_id": int,
    "alert_type": str,       # "price_up", "price_down", "volume_spike"
    "target_price": float,   # (opcional)
    "target_volume": int,    # (opcional)
    "is_active": bool,
    "notify_browser": bool,
    "notify_email": bool
}

News

{
    "id": int,
    "company_id": int,
    "title": str,
    "summary": str,
    "url": str,
    "source": str,
    "published_at": datetime,
    "sentiment": str,        # "positive", "negative", "neutral"
    "is_saved": bool
}

🎨 Temas

La aplicación soporta automáticamente temas light y dark:

• Detección automática: Se adapta a las preferencias del sistema
• Persistencia: Guarda la preferencia en localStorage
• Aplicación completa: Todos los componentes incluyen estilos para ambos temas
• Gráficos adaptativos: Plotly ajusta colores según el tema activo

🔐 Seguridad

• Variables de entorno para credenciales sensibles
• CORS habilitado para desarrollo (ajustar en producción)
• Validación básica en rutas
• Base de datos encriptada recomendada para producción

📈 Uso Típico

1. Agregar empresas: Dashboard → "Añadir Empresa" → Buscar símbolo (ej: AAPL)
2. Ver detalles: Haz clic en "Detalles" de cualquier empresa para ver gráfico + noticias
3. Crear alertas: Alertas → "Nueva Alerta" → Configurar tipo y precio objetivo
4. Seguimiento: El dashboard actualiza automáticamente cada 30 segundos

🐛 Troubleshooting

No se cargan datos de precios

• Verificar conexión a internet
• Comprobar FINNHUB_API_KEY (si está configurada)
• Revisar que yfinance esté disponible como fallback
• Ver logs en la consola del navegador

Gráficos no se renderizan

• Limpiar caché del navegador (F12 → Application → Clear)
• Verificar que Plotly.js se cargue correctamente
• Comprobar que existan datos históricos para la empresa
• Ver consola del navegador para errores de JavaScript

Base de datos corrupta

rm instance/tracker.db
python seed_prices.py  # Regenerar con datos de prueba

🚀 Despliegue en Producción

Para desplegar en producción:

1. Usar servidor WSGI (Gunicorn, uWSGI)
2. Configurar variables de entorno seguras
3. Habilitar HTTPS
4. Usar base de datos PostgreSQL/MySQL
5. Implementar caché (Redis)
6. Configurar CI/CD

Ejemplo con Gunicorn:

pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 app:app

📝 Contribuciones

Las contribuciones son bienvenidas. Por favor:

1. Fork el repositorio
2. Crear rama feature (git checkout -b feature/AmazingFeature)
3. Commit cambios (git commit -m 'Add AmazingFeature')
4. Push a rama (git push origin feature/AmazingFeature)
5. Abrir Pull Request

📄 Licencia

Este proyecto está bajo licencia MIT. Ver archivo LICENSE para más detalles.

👨‍💻 Autor

Joan Serra - Desarrollo inicial

🙋 Soporte

Para reportar bugs o solicitar features, abre un issue en GitHub.

📚 Recursos Útiles

• Documentación Flask
• Vue 3 Docs
• Tailwind CSS
• Plotly.js
• Finnhub API Docs
• yfinance GitHub

---

Última actualización: Febrero 20264. Push a la rama (git push origin feature/AmazingFeature) 5. Abre un Pull Request

📧 Soporte

Si tienes preguntas o problemas:

1. Revisa la sección de Solución de Problemas
2. Abre un issue en el repositorio
3. Consulta la documentación de Alpha Vantage

---

Desarrollado con ❤️ para la comunidad financiera

Versión: 1.0.0 Última actualización: 2024