gendesign/tradein-mvp/backend/app/services/account_quota.py

"""Сервис квоты оценок trade-in — N успешных оценок в месяц на аккаунт.

Правила:
- Лимит = settings.estimate_quota_limit успешных оценок за календарный месяц
  (UTC, период 'YYYY-MM'); конфигурируется через env ESTIMATE_QUOTA_LIMIT, default 15.
- Без лимита (unlimited): роль admin ИЛИ username == 'kopylov'.
- Учитываются ТОЛЬКО успешные оценки (инкремент ПОСЛЕ estimate_quality).
- Если заголовок X-Authenticated-User отсутствует (dev без Caddy) → unlimited,
  лимит не применяется (fail-open).
- При исчерпании лимита поднимается HTTPException(429).
"""

from __future__ import annotations

import logging
from datetime import UTC, datetime

from fastapi import HTTPException
from sqlalchemy import text
from sqlalchemy.orm import Session

from app.core.auth import get_role
from app.core.config import settings

logger = logging.getLogger(__name__)

# Лимит успешных оценок за календарный месяц — конфигурируется через
# env ESTIMATE_QUOTA_LIMIT (core.config.Settings), default 15 (#658).
MONTHLY_LIMIT = settings.estimate_quota_limit
LIMIT_EXHAUSTED_MESSAGE = (
    f"Лимит из {MONTHLY_LIMIT} оценок в этом месяце исчерпан. "
    "За полной версией обращайтесь к Копылову."
)


def current_period() -> str:
    """Возвращает текущий период в формате 'YYYY-MM' (UTC)."""
    return datetime.now(UTC).strftime("%Y-%m")


def is_unlimited(username: str) -> bool:
    """True если пользователь не ограничен квотой.

    Unlimited: роль admin ИЛИ username == 'kopylov'.
    KeyError (неизвестный пользователь) → трактуется как limited (False).
    """
    if username == "kopylov":
        return True
    try:
        role = get_role(username)
        return role == "admin"
    except KeyError:
        return False


def get_status(db: Session, username: str | None) -> dict:
    """Возвращает статус квоты для пользователя.

    Если username is None → unlimited True, used 0, remaining 15.
    Если unlimited → used = фактический или 0, remaining = limit.
    """
    if username is None:
        return {
            "limit": MONTHLY_LIMIT,
            "used": 0,
            "remaining": MONTHLY_LIMIT,
            "unlimited": True,
        }

    unlimited = is_unlimited(username)
    period = current_period()

    row = db.execute(
        text(
            """
            SELECT used FROM account_estimate_usage
            WHERE username = :u AND period_month = :p
            """
        ),
        {"u": username, "p": period},
    ).fetchone()

    used = row.used if row is not None else 0

    if unlimited:
        return {
            "limit": MONTHLY_LIMIT,
            "used": used,
            "remaining": MONTHLY_LIMIT,
            "unlimited": True,
        }

    remaining = max(0, MONTHLY_LIMIT - used)
    return {
        "limit": MONTHLY_LIMIT,
        "used": used,
        "remaining": remaining,
        "unlimited": False,
    }


def check_and_raise(db: Session, username: str | None) -> None:
    """Проверяет лимит квоты и поднимает 429 если исчерпан.

    Если username is None или пользователь unlimited → no-op.
    """
    if username is None:
        return

    if is_unlimited(username):
        return

    period = current_period()
    row = db.execute(
        text(
            """
            SELECT used FROM account_estimate_usage
            WHERE username = :u AND period_month = :p
            """
        ),
        {"u": username, "p": period},
    ).fetchone()

    used = row.used if row is not None else 0
    if used >= MONTHLY_LIMIT:
        logger.warning(
            "quota exhausted: username=%r period=%s used=%d limit=%d",
            username,
            period,
            used,
            MONTHLY_LIMIT,
        )
        raise HTTPException(status_code=429, detail=LIMIT_EXHAUSTED_MESSAGE)


def increment(db: Session, username: str | None) -> bool:
    """Атомарно-условный инкремент счётчика успешных оценок (#747).

    Возвращает True если инкремент успешен; False если лимит исчерпан.
    None / unlimited → True (no-op success).

    Защита от TOCTOU: предикат `WHERE used < :lim` применяется к ветке DO UPDATE —
    два параллельных запроса при used=MONTHLY_LIMIT-1 не могут оба инкрементировать
    (второй упрётся в WHERE → RETURNING пуст → False). Свежая вставка (used=1) НЕ
    задевается WHERE (он только для DO UPDATE), поэтому первая оценка месяца проходит.
    """
    if username is None or is_unlimited(username):
        return True

    period = current_period()
    row = db.execute(
        text(
            """
            INSERT INTO account_estimate_usage (username, period_month, used, updated_at)
            VALUES (:u, :p, 1, NOW())
            ON CONFLICT (username, period_month)
            DO UPDATE SET
                used = account_estimate_usage.used + 1,
                updated_at = NOW()
            WHERE account_estimate_usage.used < :lim
            RETURNING used
            """
        ),
        {"u": username, "p": period, "lim": MONTHLY_LIMIT},
    ).fetchone()
    db.commit()
    ok = row is not None
    if ok:
        logger.debug("quota incremented: username=%r period=%s used=%s", username, period, row[0])
    else:
        logger.warning(
            "quota increment refused (atomic, #747): username=%r period=%s limit=%d",
            username,
            period,
            MONTHLY_LIMIT,
        )
    return ok