TaskFlow

A modern, full-stack task management application built with .NET 9 and React.

🌐 Live Application: https://taskflow-app.azurewebsites.net

scripts\use-env.ps1 <profile>

TaskFlow (Español)

Plataforma profesional de gestión de tareas con un backend robusto en .NET 9 (Entity Framework Core, Dapper, Stored Procedures) y un frontend moderno en React, TypeScript, Vite y Material UI.

🌐 Acceder a la aplicación: https://taskflow-app.azurewebsites.net

Características principales

• Autenticación y Autorización: Registro, login, confirmación por email con tokens JWT
• Gestión de Tareas: Operaciones CRUD completas con interfaz intuitiva y responsiva
• Soporte de Ubicación: Geolocalización opcional con integración de Google Maps para ubicaciones físicas de tareas
• Asistente de IA: Compañero inteligente impulsado por el router de Hugging Face, con fallback opcional en Ollama para operar sin conexión
• Gestión de Categorías: Crear, editar y organizar tareas por categorías
• Dashboard y Analíticas: Métricas visuales y gráficos para seguimiento de progreso
• Drag & Drop: Reordenar tareas con hello-pangea/dnd
• Soporte Multilenguaje: Español/Inglés con react-i18next
• Modo Claro/Oscuro: Cambio de tema con Material UI
• Manejo de Fechas: Edición y visualización local robusta con almacenamiento UTC
• Indicadores Visuales: Colores para urgencia y estado de tareas
• Acciones Contextuales: Opciones rápidas de editar, eliminar e info
• Notificaciones: Alertas no intrusivas posicionadas abajo a la izquierda

Requisitos previos

• Frontend: Node.js 18+ y npm
• Backend: .NET 9 SDK, SQL Server (local o remoto)
• Worker de emails: Azure Functions Core Tools v4 y Azurite (o una cuenta de Azure Storage) para la cola de correos
• Asistente de IA: Credenciales del router de Hugging Face (token con permiso Write); Ollama opcional como fallback offline
• Opcional: SQL Server Management Studio (SSMS)

Instalación y configuración

Configuración del Frontend

1. Navegar al directorio del frontend:

   cd taskflow-frontend
   

2. Instalar dependencias:

   npm install
   

3. Configurar variables de entorno:

   cp .env.example .env
   

   Editá .env y configurá:

   VITE_ROOT_URL=http://localhost:5149
   VITE_GOOGLE_MAPS_API_KEY=tu_clave_api_google_maps_aqui
   

   Obtener API Key de Google Maps:

   1. Andá a Google Cloud Console
   2. Creá o seleccioná un proyecto
   3. Habilitá estas APIs:
      • Maps JavaScript API
      • Places API (New)
   4. Creá una API Key y copiala

4. Iniciar servidor de desarrollo:

   npm run dev
   

   Accede en http://localhost:5173

Configuración del Backend

1. Navegar al directorio de la API:

   cd TaskFlow.Api
   

2. Configurar variables de entorno:

   cp .env.example .env
   

   Editá .env y configurá tu base de datos, SMTP y JWT.

3. Aplicar migraciones de base de datos:

   dotnet ef database update
   

4. Iniciar la API:

   dotnet run
   

   API disponible en el puerto mostrado en consola (típicamente https://localhost:5149)

Configuración del worker de emails (Azure Functions)

El worker de segundo plano consume la cola email-queue y envía los correos transaccionales.

1. Instalá las herramientas (una sola vez):
   • Azure Functions Core Tools v4
   • Azurite (npm install -g azurite) o conectate a una cuenta de Azure Storage
2. Levantá Azurite para desarrollo local:

   npx azurite --silent --location ./azurite --debug ./azurite/azurite.log
   

3. Configurá el worker:

   cd TaskFlow.Functions
   cp local.settings.json.example local.settings.json
   

   Completá local.settings.json con tu cadena de conexión de SQL Server y credenciales SMTP. Activá Email__UseSmtp=true y Email__AllowSmtpInDevelopment=true solo cuando quieras enviar correos reales desde tu entorno local.
4. Ejecutá el worker:

   func start
   

   El worker escuchará la cola email-queue y despachará los correos usando tu configuración SMTP.

Configuración del Asistente de IA

1. Configurar Hugging Face (proveedor predeterminado):

   • Creá o reutilizá una cuenta de Hugging Face y generá un token con permiso Write en huggingface.co/settings/tokens.
   • Actualizá TaskFlow.Api/appsettings.Local.json (o las variables de entorno) con:

     "AI": {
       "Provider": "huggingface",
       "ApiKey": "hf_tu_token",
       "Model": "HuggingFaceTB/SmolLM3-3B",
       "BaseUrl": "https://router.huggingface.co"
     }
     

   • Opcional: probá el token con

     curl -H "Authorization: Bearer <token>" https://router.huggingface.co/v1/models
     

2. Opcional: habilitar fallback en Ollama (modo sin conexión):

   • Instalá Ollama solo si necesitás operar totalmente offline (instalador para Windows o curl -fsSL https://ollama.com/install.sh | sh).
   • Descargá un modelo compatible:

     ollama pull llama3.2
     

   • Ejecutá Ollama (por defecto en http://localhost:11434) y cambiá el proveedor con AI__PROVIDER=ollama únicamente cuando Hugging Face no sea viable.

💡 Nota: Sin un token válido de Hugging Face el asistente se mostrará "Sin conexión". Ollama queda disponible solo para despliegues offline o aislados.

Variables de entorno

Frontend (.env)

• VITE_ROOT_URL — URL de la API del backend (ej., http://localhost:5149)
• VITE_GOOGLE_MAPS_API_KEY — API Key de Google Maps para funcionalidades de geolocalización (opcional pero recomendado)

Backend (.env)

• ConnectionStrings__DefaultConnection — Cadena de conexión de SQL Server
• Smtp__Host — Host del servidor SMTP (ej., smtp.gmail.com)
• Smtp__Port — Puerto SMTP (ej., 587)
• Smtp__User — Usuario SMTP
• Smtp__Pass — Contraseña SMTP/contraseña de aplicación (usar App Password de Gmail, no contraseña normal)
• Smtp__From — Dirección de email remitente
• Jwt__Key — Clave secreta JWT (mínimo 32 caracteres)
• FRONTEND_URL — URL del frontend para links de confirmación de email (ej., http://localhost:5173 en desarrollo)

Worker de emails (TaskFlow.Functions/local.settings.json)

• AzureWebJobsStorage — Cadena de conexión de Azure Storage para las colas (usá UseDevelopmentStorage=true con Azurite)
• Email__UseSmtp — Ponelo en true para enviar correos reales en lugar de guardarlos localmente
• Email__ForceSmtpFallback — Ponelo en true para saltar la cola y enviar por SMTP directo (útil si Azure Functions está caído)
• Email__AllowSmtpInDevelopment — Permite SMTP mientras el worker corre en modo Development
• Las mismas claves Smtp__* que la API — reutilizadas por el worker para enviar correos
• ConnectionStrings__DefaultConnection — reutilizada si el worker necesita acceder a la base de datos

Scripts disponibles

Frontend

• npm run dev — Servidor de desarrollo
• npm run build — Build de producción
• npm run preview — Previsualización del build
• npm run lint — ESLint
• npm run test — Ejecutar tests
• npm run test:coverage — Cobertura de tests

Backend

• dotnet run — Servidor de desarrollo (modo Development)
• dotnet run --launch-profile production — Servidor con configuración de producción
• dotnet build — Compilar proyecto
• dotnet test — Ejecutar tests
• dotnet publish -c Release — Build de producción

Deployment Scripts (desde raíz del proyecto)

• .\copy-frontend-to-wwwroot.ps1 — Build del frontend y copia a wwwroot para servir desde backend
• .\verify-deployment.ps1 — Verificar configuración de deployment (DB, SMTP, JWT, variables de entorno)

Despliegue en producción

Opción 1: Deployment Integrado (Recomendado para localhost)

Esta opción sirve el frontend directamente desde el backend, ideal para testing local o deployment simple.

1. Ejecutar el script de deployment:

   .\copy-frontend-to-wwwroot.ps1
   

   Este script automáticamente:

   • Instala dependencias si es necesario (npm install)
   • Compila el frontend para producción (npm run build)
   • Copia los archivos compilados a TaskFlow.Api/wwwroot/

2. Verificar la configuración:

   .\verify-deployment.ps1
   

   Esto verificará:

   • Build del frontend existe
   • Archivos copiados a wwwroot
   • Variables de entorno configuradas (ConnectionString, SMTP, JWT, FRONTEND_URL)
   • Migraciones de base de datos

3. Configurar variables de entorno en TaskFlow.Api/.env:

   ConnectionStrings__DefaultConnection=Server=localhost\SQLEXPRESS;Database=TaskFlowDb;Trusted_Connection=True;TrustServerCertificate=True;
   Smtp__Host=smtp.gmail.com
   Smtp__Port=587
   Smtp__User=tu-email@gmail.com
   Smtp__Pass=tu-app-password  # Usar App Password de Gmail, no contraseña regular
   Smtp__From=tu-email@gmail.com
   Jwt__Key=tu-clave-secreta-de-minimo-32-caracteres
   FRONTEND_URL=http://localhost:5149
   

   Importante sobre SMTP:

   • Para Gmail, necesitás un App Password, no tu contraseña regular
   • Generalo en: Google Account → Security → 2-Step Verification → App passwords
   • La verificación en 2 pasos debe estar activada primero

4. Aplicar migraciones:

   cd TaskFlow.Api
   dotnet ef database update
   

5. Iniciar el backend:

   dotnet run --project TaskFlow.Api/TaskFlow.Api.csproj
   

6. Acceder a la aplicación: http://localhost:5149

El backend servirá tanto la API como el frontend desde el mismo puerto.

💡 Nota: Para deployment en producción con dominio real, seguir las instrucciones en docs/DEPLOYMENT.md.

Opción 2: Deployment Separado (Desarrollo)

Opción 2: Deployment Separado (Desarrollo)

Para desarrollo activo con hot-reload:

Frontend

1. Build para producción:

   npm run build
   

2. Desplegar la carpeta dist/ en tu servidor de archivos estáticos (Nginx, Apache, IIS, etc.)

3. Configurar tu servidor web para servir index.html en todas las rutas (routing SPA)

Backend

1. Publicar la aplicación:

   dotnet publish -c Release -o ./publish
   

2. Desplegar en tu servidor (IIS, Linux con reverse proxy, etc.)

3. Configurar variables de entorno en tu entorno de producción

4. Configurar HTTPS y CORS para tu dominio del frontend

Estructura del proyecto

Frontend

• src/components/app/ — Componentes principales de la app y navegación
• src/components/auth-dialog/ — Formularios y diálogos de autenticación
• src/components/task-item/ — Visualización y gestión de ítems de tarea
• src/components/task-list/ — Listado y filtrado de tareas
• src/components/category-manager/ — Operaciones CRUD de categorías
• src/components/dashboard/ — Analíticas y métricas
• src/components/location/ — Selector de ubicación y visualización de mapas para tareas
• src/components/ai-assistant/ — Interfaz de chat de IA y funciones del asistente
• src/contexts/ — Contextos de React (Auth, Notificaciones)
• src/services/ — Servicios de comunicación con API
• src/config/ — Configuración centralizada de API y endpoints
• src/locales/ — Archivos de traducción (es/en)
• src/types/ — Definiciones de tipos TypeScript

Backend

• Controllers/ — Endpoints de la API
• Services/ — Lógica de negocio
• Models/ — Modelos de entidad
• DTOs/ — Objetos de transferencia de datos
• Migrations/ — Migraciones de Entity Framework

Dependencias clave

• React, ReactDOM
• TypeScript
• Vite
• Material UI v5
• @hello-pangea/dnd
• react-i18next, i18next
• react-country-flag

Backend (.NET 9 API)

Endpoints de la API

Autenticación

• POST /api/auth/register — Registro de usuario
• POST /api/auth/login — Login de usuario
• POST /api/auth/forgot-password — Recuperación de contraseña
• POST /api/auth/resend-confirmation — Reenviar confirmación de email
• GET /api/auth/me — Obtener información del usuario actual

Tareas

• GET /api/tasks — Listar tareas del usuario
• POST /api/tasks — Crear nueva tarea
• PUT /api/tasks/{id} — Actualizar tarea
• DELETE /api/tasks/{id} — Eliminar tarea

Categorías

• GET /api/categories — Listar categorías del usuario
• POST /api/categories — Crear nueva categoría
• PUT /api/categories/{id} — Actualizar categoría
• DELETE /api/categories/{id} — Eliminar categoría

Asistente de IA

• POST /api/ai-assistant/chat — Enviar mensaje al asistente de IA (requiere autenticación)
• GET /api/ai-assistant/status — Verificar disponibilidad de Ollama

Uso

1. Registrá una nueva cuenta o iniciá sesión con credenciales existentes
2. Creá categorías para organizar tus tareas
3. Agregá tareas con títulos, descripciones, fechas de vencimiento, categorías y ubicaciones
4. Buscá y seleccioná ubicaciones usando el autocompletado de Google Places o ubicación GPS
5. Visualizá ubicaciones de tareas en mapas interactivos en los detalles de la tarea
6. Usá el dashboard para ver analíticas y progreso
7. Cambiá temas e idiomas desde la navegación de la app
8. Arrastrá y soltá tareas para reordenarlas
9. Usá menús contextuales para acciones rápidas en las tareas
10. Chateá con el Asistente de IA para sugerencias de tareas, tips de organización y análisis de productividad

Asistente de IA

TaskFlow incluye un asistente de IA inteligente impulsado por Ollama que te ayuda a gestionar tus tareas de manera más efectiva. El asistente puede:

• Sugerir nuevas tareas basándose en tu carga de trabajo actual y objetivos
• Organizar tareas existentes por prioridad, categoría o fecha límite
• Crear planes de completitud con desgloses paso a paso
• Sugerir nuevas categorías para organizar mejor tu trabajo

El asistente de IA es consciente del contexto, lo que significa que conoce tus tareas, categorías y progreso. También está restringido por tema para discutir solo gestión de tareas y temas de productividad relacionados con TaskFlow.

Inicio Rápido

1. Instalá Ollama (ver sección Configuración de Ollama arriba)
2. Hacé clic en el ícono de chat en la esquina inferior derecha de la app
3. Comenzá a chatear - probá preguntar:
   • "Ayudame a organizar mis tareas para esta semana"
   • "¿En qué debería trabajar ahora?"
   • "Sugerí algunas categorías para mis tareas"
   • "Creá un plan para completar mis tareas urgentes"

Para documentación detallada, ver Documentación del Asistente de IA.