TimeTracker/app/models/expense_category.py

from datetime import datetime
from decimal import Decimal
from app import db
from sqlalchemy import Index


class ExpenseCategory(db.Model):
    """Expense category model with budget tracking"""

    __tablename__ = "expense_categories"

    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(100), nullable=False, unique=True, index=True)
    description = db.Column(db.Text, nullable=True)
    code = db.Column(db.String(20), nullable=True, unique=True, index=True)  # Short code for quick reference
    color = db.Column(db.String(7), nullable=True)  # Hex color for UI (e.g., #FF5733)
    icon = db.Column(db.String(50), nullable=True)  # Icon name for UI

    # Budget settings
    monthly_budget = db.Column(db.Numeric(10, 2), nullable=True)
    quarterly_budget = db.Column(db.Numeric(10, 2), nullable=True)
    yearly_budget = db.Column(db.Numeric(10, 2), nullable=True)
    budget_threshold_percent = db.Column(db.Integer, nullable=False, default=80)  # Alert when exceeded

    # Settings
    requires_receipt = db.Column(db.Boolean, default=True, nullable=False)
    requires_approval = db.Column(db.Boolean, default=True, nullable=False)
    default_tax_rate = db.Column(db.Numeric(5, 2), nullable=True)
    is_active = db.Column(db.Boolean, default=True, nullable=False)

    # Metadata
    created_at = db.Column(db.DateTime, default=datetime.utcnow, nullable=False)
    updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)

    def __init__(self, name, **kwargs):
        self.name = name.strip()
        self.description = kwargs.get("description", "").strip() if kwargs.get("description") else None
        self.code = kwargs.get("code", "").strip() if kwargs.get("code") else None
        self.color = kwargs.get("color")
        self.icon = kwargs.get("icon")
        self.monthly_budget = Decimal(str(kwargs.get("monthly_budget"))) if kwargs.get("monthly_budget") else None
        self.quarterly_budget = Decimal(str(kwargs.get("quarterly_budget"))) if kwargs.get("quarterly_budget") else None
        self.yearly_budget = Decimal(str(kwargs.get("yearly_budget"))) if kwargs.get("yearly_budget") else None
        self.budget_threshold_percent = kwargs.get("budget_threshold_percent", 80)
        self.requires_receipt = kwargs.get("requires_receipt", True)
        self.requires_approval = kwargs.get("requires_approval", True)
        self.default_tax_rate = Decimal(str(kwargs.get("default_tax_rate"))) if kwargs.get("default_tax_rate") else None
        self.is_active = kwargs.get("is_active", True)

    def __repr__(self):
        return f"<ExpenseCategory {self.name}>"

    def get_spent_amount(self, start_date, end_date):
        """Get total amount spent in this category for date range"""
        from app.models.expense import Expense

        query = db.session.query(db.func.sum(Expense.amount + db.func.coalesce(Expense.tax_amount, 0))).filter(
            Expense.category == self.name,
            Expense.status.in_(["approved", "reimbursed"]),
            Expense.expense_date >= start_date,
            Expense.expense_date <= end_date,
        )

        total = query.scalar() or Decimal("0")
        return float(total)

    def get_budget_utilization(self, period="monthly"):
        """Get budget utilization percentage for the current period"""
        from datetime import date

        today = date.today()

        if period == "monthly":
            start_date = date(today.year, today.month, 1)
            budget = self.monthly_budget
        elif period == "quarterly":
            quarter = (today.month - 1) // 3 + 1
            start_month = (quarter - 1) * 3 + 1
            start_date = date(today.year, start_month, 1)
            budget = self.quarterly_budget
        elif period == "yearly":
            start_date = date(today.year, 1, 1)
            budget = self.yearly_budget
        else:
            return None

        if not budget or budget == 0:
            return None

        spent = self.get_spent_amount(start_date, today)
        utilization = (spent / float(budget)) * 100

        return {
            "spent": spent,
            "budget": float(budget),
            "utilization_percent": round(utilization, 2),
            "remaining": float(budget) - spent,
            "over_threshold": utilization >= self.budget_threshold_percent,
        }

    def to_dict(self):
        """Convert category to dictionary for API responses"""
        return {
            "id": self.id,
            "name": self.name,
            "description": self.description,
            "code": self.code,
            "color": self.color,
            "icon": self.icon,
            "monthly_budget": float(self.monthly_budget) if self.monthly_budget else None,
            "quarterly_budget": float(self.quarterly_budget) if self.quarterly_budget else None,
            "yearly_budget": float(self.yearly_budget) if self.yearly_budget else None,
            "budget_threshold_percent": self.budget_threshold_percent,
            "requires_receipt": self.requires_receipt,
            "requires_approval": self.requires_approval,
            "default_tax_rate": float(self.default_tax_rate) if self.default_tax_rate else None,
            "is_active": self.is_active,
            "created_at": self.created_at.isoformat() if self.created_at else None,
            "updated_at": self.updated_at.isoformat() if self.updated_at else None,
        }

    @classmethod
    def get_active_categories(cls):
        """Get all active categories"""
        return cls.query.filter_by(is_active=True).order_by(cls.name).all()

    @classmethod
    def get_categories_over_budget(cls, period="monthly"):
        """Get categories that are over their budget threshold"""
        categories = cls.get_active_categories()
        over_budget = []

        for category in categories:
            utilization = category.get_budget_utilization(period)
            if utilization and utilization["over_threshold"]:
                over_budget.append({"category": category, "utilization": utilization})

        return over_budget