Files
Django_TasksApp/main/planner/services/scheduling.py
T
2026-09-30 17:25:25 +02:00

194 lines
8.2 KiB
Python

"""Reusable scheduling and recommendation decisions for the task planner."""
from __future__ import annotations
from dataclasses import dataclass
from datetime import date, timedelta
from typing import TYPE_CHECKING, Iterable
from planner.models import Task, TaskWeatherShift
if TYPE_CHECKING:
from planner.models import SickDaySettings
ENERGY_BUDGETS = {1: 15, 2: 30, 3: 60, 4: 90, 5: 180}
DEFAULT_ENERGY_LEVEL = 3
@dataclass(frozen=True)
class RecommendedTaskGroup:
"""One independently recommended top-level task and its eligible subtasks."""
task: Task
subtasks: tuple[Task, ...]
def normalize_energy_level(value: object) -> int:
try:
level = int(value)
except (TypeError, ValueError):
return DEFAULT_ENERGY_LEVEL
return max(min(level, max(ENERGY_BUDGETS)), min(ENERGY_BUDGETS))
def duration_budget_for_energy(value: object) -> int:
return ENERGY_BUDGETS[normalize_energy_level(value)]
def is_task_scheduled_on_date(task: Task, selected_date: date) -> bool:
anchor = task.scheduled_for
if not isinstance(anchor, date) or not isinstance(selected_date, date):
return False
if not task.is_recurring:
return selected_date == anchor
interval = task.recurrence_interval
if not isinstance(interval, int) or isinstance(interval, bool) or interval <= 0 or selected_date < anchor:
return False
if task.recurrence_unit == Task.RecurrenceUnit.DAY:
return (selected_date - anchor).days % interval == 0
if task.recurrence_unit == Task.RecurrenceUnit.WEEK:
return (selected_date - anchor).days % (interval * 7) == 0
if task.recurrence_unit == Task.RecurrenceUnit.MONTH:
if selected_date.day != anchor.day:
return False
distance = (selected_date.year - anchor.year) * 12 + selected_date.month - anchor.month
return distance >= 0 and distance % interval == 0
return False
def is_task_eligible(task: Task, selected_date: date) -> bool:
if not isinstance(selected_date, date):
return False
if task.deferred_until is not None:
if selected_date < task.deferred_until:
return False
if selected_date == task.deferred_until:
return True
return is_task_scheduled_on_date(task, selected_date)
def task_recommendation_key(task: Task, energy_level: object) -> tuple:
budget = duration_budget_for_energy(energy_level)
duration = task.estimated_duration_minutes
has_duration = duration is not None
exceeds_budget = has_duration and duration > budget
if not has_duration:
preference = float('inf')
elif normalize_energy_level(energy_level) <= 2:
preference = duration
elif duration <= budget:
preference = budget - duration
else:
preference = duration - budget
return (not task.is_active, not task.is_recurring, not has_duration,
exceeds_budget if has_duration else True, preference, task.title.casefold())
def _weather_shift_for_date(task: Task, selected_date: date):
return task.weather_shifts.filter(shifted_to=selected_date).first()
def _find_weather_target(task: Task, owner, original_date: date):
"""Find the first forecast-supported vacancy for one weather-blocked occurrence."""
from planner.services.weather import (
FORECAST_SEARCH_HORIZON_DAYS, evaluate_weather_suitability, forecast_for_user_on_date,
)
for offset in range(1, FORECAST_SEARCH_HORIZON_DAYS + 1):
candidate = original_date + timedelta(days=offset)
# An occurrence may not be moved onto another natural or already moved occurrence.
if is_task_scheduled_on_date(task, candidate):
continue
if task.weather_shifts.filter(shifted_to=candidate).exclude(original_date=original_date).exists():
continue
outcome = evaluate_weather_suitability(task, forecast_for_user_on_date(owner, candidate))
if outcome.status == 'suitable':
return candidate, outcome.reason
return None, 'Waiting for a suitable weather forecast.'
def is_weather_eligible(task: Task, selected_date: date, owner) -> bool:
"""Apply weather-owned occurrence moves without changing recurrence anchors.
Manual, missed, and Sick Day deferrals are intentionally evaluated first and
are never replaced by weather state. Unknown weather remains visible.
"""
if owner is None or task.weather_profile == Task.WeatherProfile.ANY:
return is_task_eligible(task, selected_date)
moved = _weather_shift_for_date(task, selected_date)
if moved is not None:
task.weather_shift_reason = moved.reason
task.weather_shifted_from = moved.original_date
return True
if not is_task_eligible(task, selected_date):
return False
if task.deferred_until is not None and task.deferral_source != Task.DeferralSource.WEATHER:
return True
if not is_task_scheduled_on_date(task, selected_date):
return True
existing = task.weather_shifts.filter(original_date=selected_date).first()
if existing is not None:
# The source is weather-owned, so it can be recalculated without touching other deferrals.
target, reason = _find_weather_target(task, owner, selected_date)
if existing.shifted_to != target or existing.reason != reason:
existing.shifted_to, existing.reason = target, reason
existing.save(update_fields=['shifted_to', 'reason', 'updated_at'])
return False
from planner.services.weather import evaluate_weather_suitability, forecast_for_user_on_date
outcome = evaluate_weather_suitability(task, forecast_for_user_on_date(owner, selected_date))
if outcome.status != 'unsuitable':
if outcome.status == 'unknown':
task.weather_shift_reason = outcome.reason
return True
target, reason = _find_weather_target(task, owner, selected_date)
TaskWeatherShift.objects.create(
task=task, owner=owner, original_date=selected_date, shifted_to=target,
reason=f'{outcome.reason} {reason}',
)
return False
def recommend_tasks(top_level_tasks: Iterable[Task], selected_date: date, energy_level: object,
sick_day_settings: 'SickDaySettings | None' = None, *, user=None) -> list[RecommendedTaskGroup]:
"""Recommend parent tasks first; completed parents unlock their subtasks."""
from planner.services.deferrals import is_sick_day_suppressed
candidates = []
for parent in top_level_tasks:
if parent.is_completed:
candidates.extend(
subtask for subtask in parent.subtasks.all()
if is_weather_eligible(subtask, selected_date, user)
and not is_sick_day_suppressed(subtask, sick_day_settings, selected_date)
)
elif (
is_weather_eligible(parent, selected_date, user)
and not is_sick_day_suppressed(parent, sick_day_settings, selected_date)
):
candidates.append(parent)
candidates.sort(key=lambda task: task_recommendation_key(task, energy_level))
return [RecommendedTaskGroup(task, ()) for task in candidates]
def daily_recommendations(user, selected_date: date | object = None, energy_level: object = None,
sick_day_settings: 'SickDaySettings | None' = None) -> list[RecommendedTaskGroup]:
"""Load one user's tasks and apply deferral and weather policies.
The legacy three-argument shape remains temporarily supported for existing
service callers; normal application code always passes the authenticated user.
"""
if isinstance(user, date):
user, selected_date, energy_level, sick_day_settings = None, user, selected_date, energy_level
from planner.services.deferrals import apply_missed_task_deferrals, sync_sick_day_deferrals
queryset = Task.objects.filter(parent_task__isnull=True)
if user is not None:
queryset = queryset.filter(owner=user)
top_level_tasks = list(queryset.prefetch_related('subtasks', 'weather_shifts'))
all_tasks = [task for parent in top_level_tasks for task in (parent, *parent.subtasks.all())]
apply_missed_task_deferrals(all_tasks, selected_date)
sync_sick_day_deferrals(all_tasks, sick_day_settings, selected_date)
return recommend_tasks(top_level_tasks, selected_date, energy_level, sick_day_settings, user=user)