Productivity Models: Tasks & Pomodoro

Task (app/Models/Task.php)

Modelo de tareas (to-do) vinculadas a usuarios.

Campos

Campo Tipo Descripción
uuid_cliente UUID Identificador único del cliente (dedup)
user_id FK Dueño de la tarea
title string (max 255) Título de la tarea
description text nullable Descripción
status enum pending, in_progress, completed, cancelled
priority enum low, medium, high
due_date date nullable Fecha límite
estimated_pomodoros integer nullable Pomodoros estimados
completed_at datetime nullable Timestamp de completado

Scopes

Task::pending()      // status = 'pending'
Task::inProgress()   // status = 'in_progress'
Task::completed()    // status = 'completed'
Task::orderByPriority()  // Ordena high → medium → low
Task::orderByDueDate()   // Ordena por fecha límite

Relaciones

$task->user()              // belongsTo User
$task->pomodoroSessions()  // hasMany PomodoroSession
$task->incrementPomodoros() // Incrementa contador de pomodoros completados

PomodoroSession (app/Models/PomodoroSession.php)

Sesiones de trabajo Pomodoro vinculadas a usuarios y opcionalmente a tareas.

Campos

Campo Tipo Descripción
uuid_cliente UUID Identificador único del cliente (dedup)
user_id FK Usuario
task_id FK nullable Tarea asociada (opcional)
started_at datetime Inicio de la sesión
ended_at datetime nullable Fin de la sesión
duration_seconds integer nullable Duración real en segundos
break_type enum nullable none, short, long
status enum running, completed, cancelled

Scopes

PomodoroSession::completed()   // status = 'completed'
PomodoroSession::today()       // started_at >= hoy
PomodoroSession::thisWeek()    // started_at >= inicio de semana
PomodoroSession::thisMonth()   // started_at >= inicio de mes

Relaciones

$session->user()  // belongsTo User
$session->task()  // belongsTo Task
$session->cancel() // Marca como cancelled + ended_at = now

Flujo de Vida de una Sesión

1. POST /api/pomodoro/start
   - Verifica uuid_cliente no duplicado
   - Verifica que no haya sesión running
   - Crea sesión con status='running'
   - Si task_id y task.status='pending' → cambia a 'in_progress'

2. POST /api/pomodoro/complete
   - Busca sesión running por uuid_cliente
   - Actualiza: ended_at, duration_seconds, break_type, status='completed'
   - task.incrementPomodoros()
   - Envía notificación push

3. POST /api/pomodoro/cancel
   - Busca sesión running por uuid_cliente
   - session.cancel()