feat: фильтры и кэш списка задач

- добавлены фильтры, сортировка и пагинация для GET /tasks
- реализовано персональное кэширование списка задач в Redis (TTL из настроек)
- добавлен отказоустойчивый режим: ошибки Redis не роняют API
- инвалидация кэша переведена на удаление по префиксу пользователя
- устранён конфликт enum-поля sort_by=title для Pylance

Author: RomanVetrov

app/cache/__init__.py

@@ -0,0 +1,17 @@
+from app.cache.tasks_list import (
+    build_tasks_list_cache_prefix,
+    build_tasks_list_cache_key,
+    delete_cached_tasks_list,
+    delete_cached_tasks_list_for_user,
+    get_cached_tasks_list,
+    set_cached_tasks_list,
+)
+
+__all__ = [
+    "build_tasks_list_cache_prefix",
+    "build_tasks_list_cache_key",
+    "get_cached_tasks_list",
+    "set_cached_tasks_list",
+    "delete_cached_tasks_list",
+    "delete_cached_tasks_list_for_user",
+]

app/cache/tasks_list.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from logging import getLogger
+from uuid import UUID
+
+from pydantic import TypeAdapter, ValidationError
+from redis.asyncio import Redis
+from redis.exceptions import RedisError
+
+from app.schemas.task import TaskRead
+
+logger = getLogger(__name__)
+_CACHE_KEY_VERSION = "v1"
+_TASKS_LIST_ADAPTER = TypeAdapter(list[TaskRead])
+
+
+def build_tasks_list_cache_prefix(*, user_id: UUID) -> str:
+    """Формирует базовый префикс ключей кэша списка задач пользователя."""
+    return f"{_CACHE_KEY_VERSION}:tasks:list:user:{user_id}"
+
+
+def build_tasks_list_cache_key(
+    *,
+    user_id: UUID,
+    filters: Mapping[str, object | None] | None = None,
+) -> str:
+    """Формирует ключ кэша списка задач пользователя.
+
+    Параметр filters заложен заранее, чтобы позже безопасно добавить фильтрацию.
+    """
+    key = build_tasks_list_cache_prefix(user_id=user_id)
+    if not filters:
+        return key
+
+    normalized = [
+        f"{name}={value}"
+        for name, value in sorted(filters.items())
+        if value is not None
+    ]
+    if not normalized:
+        return key
+    return f"{key}:{'&'.join(normalized)}"
+
+
+async def get_cached_tasks_list(redis: Redis, cache_key: str) -> list[TaskRead] | None:
+    """Читает список задач из Redis.
+
+    Любые ошибки Redis не ломают API, а просто отключают кэш на текущем запросе.
+    """
+    try:
+        raw_payload = await redis.get(cache_key)
+    except RedisError:
+        logger.warning(
+            "Не удалось прочитать кэш списка задач",
+            extra={"cache_key": cache_key},
+        )
+        return None
+
+    if raw_payload is None:
+        return None
+
+    try:
+        return _TASKS_LIST_ADAPTER.validate_json(raw_payload)
+    except ValidationError:
+        await delete_cached_tasks_list(redis, cache_key)
+        return None
+
+
+async def set_cached_tasks_list(
+    redis: Redis,
+    cache_key: str,
+    tasks: list[TaskRead],
+    *,
+    ttl_seconds: int,
+) -> None:
+    """Сохраняет список задач в Redis."""
+    try:
+        payload = _TASKS_LIST_ADAPTER.dump_json(tasks).decode("utf-8")
+        await redis.set(cache_key, payload, ex=ttl_seconds)
+    except RedisError:
+        logger.warning(
+            "Не удалось записать кэш списка задач",
+            extra={"cache_key": cache_key},
+        )
+
+
+async def delete_cached_tasks_list(redis: Redis, cache_key: str) -> None:
+    """Удаляет кэш списка задач по ключу."""
+    try:
+        await redis.delete(cache_key)
+    except RedisError:
+        logger.warning(
+            "Не удалось удалить кэш списка задач",
+            extra={"cache_key": cache_key},
+        )
+
+
+async def delete_cached_tasks_list_for_user(redis: Redis, user_id: UUID) -> None:
+    """Удаляет все кэш-ключи списка задач для пользователя (включая фильтры)."""
+    prefix = build_tasks_list_cache_prefix(user_id=user_id)
+    pattern = f"{prefix}*"
+    try:
+        keys = [key async for key in redis.scan_iter(match=pattern)]
+        if keys:
+            await redis.delete(*keys)
+        else:
+            await redis.delete(prefix)
+    except RedisError:
+        logger.warning(
+            "Не удалось удалить кэш списка задач по префиксу",
+            extra={"cache_key_pattern": pattern},
+        )

app/config.py

@@ -8,6 +8,7 @@ class Settings(BaseSettings):
     ACCESS_TOKEN_EXPIRE_MINUTES: int = 10
     REFRESH_TOKEN_EXPIRE_DAYS: int = 7
     REDIS_URL: str = "redis://localhost:6379/0"
+    TASKS_LIST_CACHE_TTL_SECONDS: int = 60
     # Argon2 tuning (can be overridden via .env)
     ARGON_TIME_COST: int = 3
     ARGON_MEMORY_COST: int = 65536  # KiB (≈64 MiB)

app/repositories/task_repo.py

@@ -3,21 +3,67 @@
 from collections.abc import Sequence
 from uuid import UUID
 
-from sqlalchemy import select
+from sqlalchemy import asc, desc, or_, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.models.task import Task
 from app.models.user import User
+from app.schemas.task import SortOrder, TaskListFilters, TaskSortBy
 
 
 async def get_task_by_id(session: AsyncSession, task_id: UUID) -> Task | None:
     """Возвращает задачу по id или None."""
     return await session.get(Task, task_id)
 
 
-async def get_tasks_by_user(session: AsyncSession, user: User) -> Sequence[Task]:
-    """Возвращает все задачи пользователя."""
-    result = await session.execute(select(Task).where(Task.user_id == user.id))
+def _apply_ordering(stmt, filters: TaskListFilters):
+    """Добавляет сортировку к запросу списка задач по параметрам фильтра."""
+    sort_columns = {
+        TaskSortBy.created_at: Task.created_at,
+        TaskSortBy.due_date: Task.due_date,
+        TaskSortBy.task_title: Task.title,
+    }
+    sort_column = sort_columns[filters.sort_by]
+    order_expression = (
+        asc(sort_column) if filters.sort_order == SortOrder.asc else desc(sort_column)
+    )
+    return stmt.order_by(order_expression)
+
+
+async def get_tasks_by_user(
+    session: AsyncSession,
+    user: User,
+    filters: TaskListFilters | None = None,
+) -> Sequence[Task]:
+    """Возвращает список задач пользователя с фильтрами, сортировкой и пагинацией."""
+    effective_filters = filters or TaskListFilters()
+
+    stmt = select(Task).where(Task.user_id == user.id)
+
+    if effective_filters.status is not None:
+        stmt = stmt.where(Task.status == effective_filters.status)
+    if effective_filters.priority is not None:
+        stmt = stmt.where(Task.priority == effective_filters.priority)
+    if effective_filters.due_after is not None:
+        stmt = stmt.where(Task.due_date >= effective_filters.due_after)
+    if effective_filters.due_before is not None:
+        stmt = stmt.where(Task.due_date <= effective_filters.due_before)
+
+    if effective_filters.q is not None:
+        query = effective_filters.q.strip()
+        if query:
+            pattern = f"%{query}%"
+            stmt = stmt.where(
+                or_(
+                    Task.title.ilike(pattern),
+                    Task.description.ilike(pattern),
+                )
+            )
+
+    stmt = _apply_ordering(stmt, effective_filters)
+    stmt = stmt.limit(effective_filters.limit).offset(effective_filters.offset)
+
+    result = await session.execute(stmt)
     return result.scalars().all()
 
 

app/routes/tasks.py

@@ -1,27 +1,43 @@
 from __future__ import annotations
 
+from uuid import UUID
 from typing import Annotated
 
 from fastapi import APIRouter, Depends, HTTPException, status
+from redis.asyncio import Redis
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from app.cache import (
+    build_tasks_list_cache_key,
+    delete_cached_tasks_list_for_user,
+    get_cached_tasks_list,
+    set_cached_tasks_list,
+)
+from app.config import settings
 from app.database import get_db
 from app.get_or_404 import CurrentUser, TagDep, TaskDep
+from app.redis import get_redis
 from app.schemas.tag import TaskTagLink
 from app.services import tag as tag_service
-from app.schemas.task import TaskCreate, TaskDeleted, TaskRead, TaskUpdate
+from app.schemas.task import TaskCreate, TaskDeleted, TaskListFilters, TaskRead, TaskUpdate
 from app.services import task as task_service
 from app.services.task import InvalidDueDate
 
 router = APIRouter(prefix="/tasks", tags=["tasks"])
 DbSession = Annotated[AsyncSession, Depends(get_db)]
+RedisClient = Annotated[Redis, Depends(get_redis)]
+TaskFilters = Annotated[TaskListFilters, Depends()]
 
 _DUE_DATE_ERROR = HTTPException(
     status_code=status.HTTP_400_BAD_REQUEST,
     detail="Дедлайн не может быть в прошлом",
 )
 
 
+async def _invalidate_user_tasks_cache(redis: Redis, user_id: UUID) -> None:
+    await delete_cached_tasks_list_for_user(redis, user_id)
+
+
 @router.post(
     "",
     status_code=status.HTTP_201_CREATED,
@@ -31,11 +47,13 @@ async def create_task(
     payload: TaskCreate,
     current_user: CurrentUser,
     session: DbSession,
+    redis: RedisClient,
 ) -> TaskRead:
     try:
         task = await task_service.create_task(session, current_user, payload)
     except InvalidDueDate:
         raise _DUE_DATE_ERROR
+    await _invalidate_user_tasks_cache(redis, current_user.id)
     return TaskRead.model_validate(task)
 
 
@@ -45,10 +63,37 @@ async def create_task(
 )
 async def list_tasks(
     current_user: CurrentUser,
+    filters: TaskFilters,
     session: DbSession,
+    redis: RedisClient,
 ) -> list[TaskRead]:
-    tasks = await task_service.get_user_tasks(session, current_user)
-    return [TaskRead.model_validate(t) for t in tasks]
+    if (
+        filters.due_after is not None
+        and filters.due_before is not None
+        and filters.due_after > filters.due_before
+    ):
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
+            detail="due_after не может быть позже due_before",
+        )
+
+    cache_key = build_tasks_list_cache_key(
+        user_id=current_user.id,
+        filters=filters.model_dump(mode="json", exclude_none=True),
+    )
+    cached_tasks = await get_cached_tasks_list(redis, cache_key)
+    if cached_tasks is not None:
+        return cached_tasks
+
+    tasks = await task_service.get_user_tasks(session, current_user, filters)
+    response = [TaskRead.model_validate(t) for t in tasks]
+    await set_cached_tasks_list(
+        redis,
+        cache_key,
+        response,
+        ttl_seconds=settings.TASKS_LIST_CACHE_TTL_SECONDS,
+    )
+    return response
 
 
 @router.get(
@@ -67,11 +112,13 @@ async def update_task(
     payload: TaskUpdate,
     task: TaskDep,
     session: DbSession,
+    redis: RedisClient,
 ) -> TaskRead:
     try:
         updated = await task_service.update_task(session, task, payload)
     except InvalidDueDate:
         raise _DUE_DATE_ERROR
+    await _invalidate_user_tasks_cache(redis, task.user_id)
     return TaskRead.model_validate(updated)
 
 
@@ -82,8 +129,10 @@ async def update_task(
 async def delete_task(
     task: TaskDep,
     session: DbSession,
+    redis: RedisClient,
 ) -> TaskDeleted:
     task_id = await task_service.delete_task(session, task)
+    await _invalidate_user_tasks_cache(redis, task.user_id)
     return TaskDeleted(id=task_id)
 
 
@@ -96,8 +145,10 @@ async def attach_tag_to_task(
     task: TaskDep,
     tag: TagDep,
     session: DbSession,
+    redis: RedisClient,
 ) -> TaskTagLink:
     await tag_service.attach_tag_to_task(session, task, tag)
+    await _invalidate_user_tasks_cache(redis, task.user_id)
     return TaskTagLink(task_id=task.id, tag_id=tag.id)
 
 
@@ -109,6 +160,8 @@ async def detach_tag_from_task(
     task: TaskDep,
     tag: TagDep,
     session: DbSession,
+    redis: RedisClient,
 ) -> TaskTagLink:
     await tag_service.detach_tag_from_task(session, task, tag)
+    await _invalidate_user_tasks_cache(redis, task.user_id)
     return TaskTagLink(task_id=task.id, tag_id=tag.id)

app/schemas/task.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from datetime import date, datetime
+from enum import Enum
 from uuid import UUID
 
 from pydantic import BaseModel, ConfigDict, Field
@@ -41,3 +42,28 @@ class TaskRead(BaseModel):
 
 class TaskDeleted(BaseModel):
     id: UUID
+
+
+class TaskSortBy(str, Enum):
+    created_at = "created_at"
+    due_date = "due_date"
+    task_title = "title"
+
+
+class SortOrder(str, Enum):
+    asc = "asc"
+    desc = "desc"
+
+
+class TaskListFilters(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    status: StatusEnum | None = None
+    priority: PriorityEnum | None = None
+    q: str | None = Field(default=None, min_length=1, max_length=255)
+    due_before: date | None = None
+    due_after: date | None = None
+    sort_by: TaskSortBy = TaskSortBy.created_at
+    sort_order: SortOrder = SortOrder.desc
+    limit: int = Field(default=20, ge=1, le=100)
+    offset: int = Field(default=0, ge=0)