"""Monthly per-user usage tracking model. One row per user per calendar month. Tracks granular counts for each billable metric so the usage endpoint and admin dashboard can report accurate numbers. """ from __future__ import annotations from datetime import datetime from sqlalchemy import DateTime, Float, Integer, String, UniqueConstraint, func from sqlalchemy.orm import Mapped, mapped_column from app.core.database import Base from app.utils.ids import prefixed_id class UserUsageMonthly(Base): __tablename__ = "user_usage_monthly" __table_args__ = ( UniqueConstraint("user_id", "month", name="uq_user_usage_monthly_user_month"), ) id: Mapped[str] = mapped_column( String(40), primary_key=True, default=lambda: prefixed_id("usg"), ) user_id: Mapped[str] = mapped_column( String(40), index=True, nullable=False, ) month: Mapped[str] = mapped_column( String(7), # YYYY-MM nullable=False, ) documents_uploaded_count: Mapped[int] = mapped_column(Integer, default=0, nullable=False) generations_count: Mapped[int] = mapped_column(Integer, default=0, nullable=False) quizzes_generated_count: Mapped[int] = mapped_column(Integer, default=0, nullable=False) flashcards_generated_count: Mapped[int] = mapped_column(Integer, default=0, nullable=False) videos_generated_count: Mapped[int] = mapped_column(Integer, default=0, nullable=False) audio_minutes_generated: Mapped[float] = mapped_column(Float, default=0.0, nullable=False) storage_bytes_used: Mapped[int] = mapped_column(Integer, default=0, nullable=False) created_at: Mapped[datetime] = mapped_column( DateTime(timezone=True), server_default=func.now(), nullable=False, ) updated_at: Mapped[datetime] = mapped_column( DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False, )