db/models.py - main - o.polulyakh/RunTracker_Bot

db/models.py
145 строк7 KB
Oksana Polulyakh
verse 0.1.2
02 янв 2026, 18:49
02 янв 2026, 18:494c52575
from datetime import date, datetime
from decimal import Decimal

from sqlalchemy import Column, DateTime, Float, Integer, String, BigInteger, ForeignKey, Date, ColumnElement
from sqlalchemy.orm import declarative_base, relationship

Base = declarative_base()


class User(Base):
    """
    Модель пользователя в системе.
    
    Хранит основную информацию о пользователе Telegram, включая
    его идентификатор, имя, фамилию и роль. Связана с моделью Workout
    отношением один-ко-многим.
    
    Attributes:
        id (int): Уникальный идентификатор пользователя в базе данных (первичный ключ)
        telegram_id (int): Уникальный идентификатор пользователя в Telegram (уникальное значение)
        first_name (str): Имя пользователя (обязательное поле)
        last_name (str | None): Фамилия пользователя (необязательное поле)
        created_at (datetime): Дата и время регистрации пользователя
        role (str): Роль пользователя (например, "runner")
        workouts (list[Workout]): Список связанных тренировок (relationship)
    
    Relationships:
        workouts: Обратная связь с моделью Workout. При удалении пользователя
                   автоматически удаляются все его тренировки (cascade="all, delete-orphan").
    """
    __tablename__ = "users"

    id = Column(Integer, primary_key=True)
    telegram_id = Column(BigInteger, nullable=False, unique=True)
    first_name = Column(String(100), nullable=False)
    last_name = Column(String(100), nullable=True)
    created_at = Column(DateTime, default=datetime.now)
    role = Column(String(100), nullable=False)

    workouts = relationship("Workout", back_populates="user", cascade="all, delete-orphan")

    def __repr__(self) -> str:
        """
        Возвращает строковое представление объекта User.
        
        Returns:
            str: Строка в формате <User telegram_id: first_name>
        """
        return f"<User {self.telegram_id}: {self.first_name}>"

    def to_dict(self) -> dict:
        """
        Конвертирует объект User в словарь для передачи вне сессии SQLAlchemy.
        
        Returns:
            dict: Словарь с основными данными пользователя
        
        Note:
            Метод используется для передачи данных пользователю после завершения
            сессии SQLAlchemy, так как объекты ORM нельзя использовать вне сессии.
        """
        return {
            "id": self.id,
            "telegram_id": self.telegram_id,
            "first_name": self.first_name,
            "last_name": self.last_name,
        }


class Workout(Base):
    """
    Модель тренировки пользователя.
    
    Хранит информацию о беговой тренировке: дистанцию, продолжительность,
    дату и рассчитанный темп. Связана с моделью User отношением
    многие-к-одному.
    
    Attributes:
        id (int): Уникальный идентификатор тренировки (первичный ключ)
        user_id (int): Идентификатор пользователя, которому принадлежит тренировка
        distance (float): Дистанция пробежки в километрах
        duration_min (int): Продолжительность тренировки в минутах
        date_time (date): Дата проведения тренировки
        user (User): Связанный пользователь (relationship)
        pace (float): Свойство, возвращающее темп в мин/км (вычисляется на лету)
    
    Relationships:
        user: Обратная связь с моделью User. Позволяет получить
              информацию о пользователе, которому принадлежит тренировка.
    """
    __tablename__ = "workouts"

    id = Column(Integer, primary_key=True)
    user_id = Column(Integer, ForeignKey("users.id"), nullable=False)
    distance = Column(Float, nullable=False)
    duration_min = Column(Integer, nullable=False)
    date_time = Column(Date, nullable=False)

    user = relationship("User", back_populates="workouts")

    @property
    def pace(self) -> float:
        """
        Рассчитывает и возвращает темп тренировки в минутах на километр.
        
        Темп рассчитывается как отношение продолжительности тренировки 
        к пройденной дистанции. Для тренировок с нулевой дистанцией 
        возвращается 0.0.
        
        Returns:
            float: Темп в мин/км, или 0.0 если дистанция равна 0

        """
        if self.distance > 0:
            return self.duration_min / self.distance
        return 0.0

    def __repr__(self) -> str:
        """
        Возвращает строковое представление объекта Workout.
        
        Returns:
            str: Строка в формате <Workout distance km in duration_min min>
        """
        return f"<Workout {self.distance}km in {self.duration_min}min>"

    def to_dict(self) -> dict:
        """
        Конвертирует объект Workout в словарь для передачи вне сессии SQLAlchemy.
        
        Returns:
            dict: Словарь с данными тренировки, включая вычисленный темп
        
        Note:
            Метод используется для передачи данных тренировки после завершения
            сессии SQLAlchemy, так как объекты ORM нельзя использовать вне сессии.
            Включает вычисленное свойство pace в результирующий словарь.
        """
        return {
            "id": self.id,
            "distance": self.distance,
            "duration_min": self.duration_min,
            "pace": self.pace,
            "date_time": self.date_time,
        }