orion/app/modules/billing/services/admin_subscription_service.py

# app/modules/billing/services/admin_subscription_service.py
"""
Admin Subscription Service.

Handles subscription management operations for platform administrators:
- Subscription tier CRUD
- Merchant subscription management
- Billing history queries
- Subscription analytics
"""

import logging
from math import ceil

from sqlalchemy import func
from sqlalchemy.orm import Session

from app.exceptions import (
    BusinessLogicException,
    ConflictException,
    ResourceNotFoundException,
)
from app.modules.billing.exceptions import TierNotFoundException
from app.modules.billing.models import (
    BillingHistory,
    MerchantSubscription,
    SubscriptionStatus,
    SubscriptionTier,
)
from app.modules.tenancy.models import Merchant

logger = logging.getLogger(__name__)


class AdminSubscriptionService:
    """Service for admin subscription management operations."""

    # =========================================================================
    # Subscription Tiers
    # =========================================================================

    def get_tiers(
        self, db: Session, include_inactive: bool = False, platform_id: int | None = None
    ) -> list[SubscriptionTier]:
        """Get all subscription tiers, optionally filtered by platform."""
        query = db.query(SubscriptionTier)

        if not include_inactive:
            query = query.filter(SubscriptionTier.is_active == True)  # noqa: E712

        if platform_id is not None:
            query = query.filter(
                (SubscriptionTier.platform_id == platform_id)
                | (SubscriptionTier.platform_id.is_(None))
            )

        return query.order_by(SubscriptionTier.display_order).all()

    def get_tier_by_code(
        self, db: Session, tier_code: str, platform_id: int | None = None
    ) -> SubscriptionTier:
        """Get a subscription tier by code, optionally scoped to a platform."""
        query = db.query(SubscriptionTier).filter(SubscriptionTier.code == tier_code)
        if platform_id is not None:
            query = query.filter(SubscriptionTier.platform_id == platform_id)
        tier = query.first()

        if not tier:
            raise TierNotFoundException(tier_code)

        return tier

    def create_tier(self, db: Session, tier_data: dict) -> SubscriptionTier:
        """Create a new subscription tier."""
        # Check for duplicate code
        existing = (
            db.query(SubscriptionTier)
            .filter(SubscriptionTier.code == tier_data["code"])
            .first()
        )
        if existing:
            raise ConflictException(
                f"Tier with code '{tier_data['code']}' already exists"
            )

        tier = SubscriptionTier(**tier_data)
        db.add(tier)

        logger.info(f"Created subscription tier: {tier.code}")
        return tier

    def update_tier(
        self, db: Session, tier_code: str, update_data: dict
    ) -> SubscriptionTier:
        """Update a subscription tier."""
        tier = self.get_tier_by_code(db, tier_code)

        for field, value in update_data.items():
            setattr(tier, field, value)

        logger.info(f"Updated subscription tier: {tier.code}")
        return tier

    def deactivate_tier(self, db: Session, tier_code: str) -> None:
        """Soft-delete a subscription tier."""
        tier = self.get_tier_by_code(db, tier_code)

        # Check if any active subscriptions use this tier (by tier_id FK)
        active_subs = (
            db.query(MerchantSubscription)
            .filter(
                MerchantSubscription.tier_id == tier.id,
                MerchantSubscription.status.in_([
                    SubscriptionStatus.ACTIVE.value,
                    SubscriptionStatus.TRIAL.value,
                ]),
            )
            .count()
        )

        if active_subs > 0:
            raise BusinessLogicException(
                f"Cannot delete tier: {active_subs} active subscriptions are using it",
                "TIER_HAS_ACTIVE_SUBSCRIPTIONS",
            )

        tier.is_active = False

        logger.info(f"Soft-deleted subscription tier: {tier.code}")

    # =========================================================================
    # Merchant Subscriptions
    # =========================================================================

    def list_subscriptions(
        self,
        db: Session,
        page: int = 1,
        per_page: int = 20,
        status: str | None = None,
        tier: str | None = None,
        search: str | None = None,
    ) -> dict:
        """List merchant subscriptions with filtering and pagination."""
        query = (
            db.query(MerchantSubscription, Merchant)
            .join(Merchant, MerchantSubscription.merchant_id == Merchant.id)
        )

        # Apply filters
        if status:
            query = query.filter(MerchantSubscription.status == status)
        if tier:
            query = query.join(
                SubscriptionTier, MerchantSubscription.tier_id == SubscriptionTier.id
            ).filter(SubscriptionTier.code == tier)
        if search:
            query = query.filter(Merchant.name.ilike(f"%{search}%"))

        # Count total
        total = query.count()

        # Paginate
        offset = (page - 1) * per_page
        results = (
            query.order_by(MerchantSubscription.created_at.desc())
            .offset(offset)
            .limit(per_page)
            .all()
        )

        return {
            "results": results,
            "total": total,
            "page": page,
            "per_page": per_page,
            "pages": ceil(total / per_page) if total > 0 else 0,
        }

    def get_subscription(
        self, db: Session, merchant_id: int, platform_id: int
    ) -> tuple:
        """Get subscription for a specific merchant on a platform."""
        result = (
            db.query(MerchantSubscription, Merchant)
            .join(Merchant, MerchantSubscription.merchant_id == Merchant.id)
            .filter(
                MerchantSubscription.merchant_id == merchant_id,
                MerchantSubscription.platform_id == platform_id,
            )
            .first()
        )

        if not result:
            raise ResourceNotFoundException(
                "Subscription",
                f"merchant_id={merchant_id}, platform_id={platform_id}",
            )

        return result

    def update_subscription(
        self, db: Session, merchant_id: int, platform_id: int, update_data: dict
    ) -> tuple:
        """Update a merchant's subscription."""
        result = self.get_subscription(db, merchant_id, platform_id)
        sub, merchant = result

        # Handle tier_code separately: resolve to tier_id
        tier_code = update_data.pop("tier_code", None)
        if tier_code is not None:
            if sub.stripe_subscription_id:
                from app.modules.billing.services.billing_service import billing_service
                billing_service.change_tier(
                    db, merchant_id, platform_id, tier_code, sub.is_annual
                )
            else:
                tier = self.get_tier_by_code(db, tier_code, platform_id=platform_id)
                sub.tier_id = tier.id

        for field, value in update_data.items():
            setattr(sub, field, value)

        logger.info(
            f"Admin updated subscription for merchant {merchant_id} "
            f"on platform {platform_id}: {list(update_data.keys())}"
            + (f", tier_code={tier_code}" if tier_code else "")
        )

        return sub, merchant

    # =========================================================================
    # Billing History
    # =========================================================================

    def list_billing_history(
        self,
        db: Session,
        page: int = 1,
        per_page: int = 20,
        merchant_id: int | None = None,
        status: str | None = None,
    ) -> dict:
        """List billing history across all merchants."""
        query = (
            db.query(BillingHistory, Merchant)
            .join(Merchant, BillingHistory.merchant_id == Merchant.id)
        )

        if merchant_id:
            query = query.filter(BillingHistory.merchant_id == merchant_id)
        if status:
            query = query.filter(BillingHistory.status == status)

        total = query.count()

        offset = (page - 1) * per_page
        results = (
            query.order_by(BillingHistory.invoice_date.desc())
            .offset(offset)
            .limit(per_page)
            .all()
        )

        return {
            "results": results,
            "total": total,
            "page": page,
            "per_page": per_page,
            "pages": ceil(total / per_page) if total > 0 else 0,
        }

    # =========================================================================
    # Platform Helpers
    # =========================================================================

    def get_platform_names_map(self, db: Session) -> dict[int, str]:
        """Get mapping of platform_id -> platform_name."""
        from app.modules.tenancy.models import Platform

        return {p.id: p.name for p in db.query(Platform).all()}

    def get_platform_name(self, db: Session, platform_id: int) -> str | None:
        """Get platform name by ID."""
        from app.modules.tenancy.models import Platform

        p = db.query(Platform).filter(Platform.id == platform_id).first()
        return p.name if p else None

    # =========================================================================
    # Merchant Subscriptions with Usage
    # =========================================================================

    def get_merchant_subscriptions_with_usage(
        self, db: Session, merchant_id: int
    ) -> list[dict]:
        """Get all subscriptions for a merchant with tier info and feature usage.

        Returns a list of dicts, each containing:
        - subscription: serialized MerchantSubscription
        - tier: tier info dict (code, name, feature_codes)
        - features: list of quantitative usage metrics
        - platform_id: int
        - platform_name: str
        """
        from app.modules.billing.schemas import MerchantSubscriptionAdminResponse
        from app.modules.billing.services.feature_service import feature_service
        from app.modules.billing.services.subscription_service import (
            subscription_service,
        )

        subs = subscription_service.get_merchant_subscriptions(db, merchant_id)
        platforms_map = self.get_platform_names_map(db)

        results = []
        for sub in subs:
            features_summary = feature_service.get_merchant_features_summary(
                db, merchant_id, sub.platform_id
            )

            tier_info = None
            if sub.tier:
                tier_info = {
                    "code": sub.tier.code,
                    "name": sub.tier.name,
                    "feature_codes": [
                        fl.feature_code for fl in (sub.tier.feature_limits or [])
                    ],
                }

            usage_metrics = []
            for fs in features_summary:
                if fs.feature_type == "quantitative" and fs.enabled:
                    usage_metrics.append({
                        "name": fs.name_key.replace("_", " ").title(),
                        "current": fs.current or 0,
                        "limit": fs.limit,
                        "percentage": fs.percent_used or 0,
                        "is_unlimited": fs.limit is None,
                        "is_at_limit": fs.remaining == 0 if fs.remaining is not None else False,
                        "is_approaching_limit": (fs.percent_used or 0) >= 80,
                    })

            results.append({
                "subscription": MerchantSubscriptionAdminResponse.model_validate(sub).model_dump(),
                "tier": tier_info,
                "features": usage_metrics,
                "platform_id": sub.platform_id,
                "platform_name": platforms_map.get(sub.platform_id, ""),
            })

        return results

    def get_subscriptions_for_store(
        self, db: Session, store_id: int
    ) -> list[dict]:
        """Get subscriptions + feature usage for a store (resolves to merchant).

        Convenience method for admin store detail page. Resolves
        store -> merchant -> all platform subscriptions.
        """
        from app.modules.tenancy.models import Store

        store = db.query(Store).filter(Store.id == store_id).first()
        if not store or not store.merchant_id:
            raise ResourceNotFoundException("Store", str(store_id))

        return self.get_merchant_subscriptions_with_usage(db, store.merchant_id)

    # =========================================================================
    # Statistics
    # =========================================================================

    def get_stats(self, db: Session) -> dict:
        """Get subscription statistics for admin dashboard."""
        # Count by status
        status_counts = (
            db.query(
                MerchantSubscription.status,
                func.count(MerchantSubscription.id),
            )
            .group_by(MerchantSubscription.status)
            .all()
        )

        stats = {
            "total_subscriptions": 0,
            "active_count": 0,
            "trial_count": 0,
            "past_due_count": 0,
            "cancelled_count": 0,
            "expired_count": 0,
        }

        for sub_status, count in status_counts:
            stats["total_subscriptions"] += count
            if sub_status == SubscriptionStatus.ACTIVE.value:
                stats["active_count"] = count
            elif sub_status == SubscriptionStatus.TRIAL.value:
                stats["trial_count"] = count
            elif sub_status == SubscriptionStatus.PAST_DUE.value:
                stats["past_due_count"] = count
            elif sub_status == SubscriptionStatus.CANCELLED.value:
                stats["cancelled_count"] = count
            elif sub_status == SubscriptionStatus.EXPIRED.value:
                stats["expired_count"] = count

        # Count by tier (join with SubscriptionTier to get tier name)
        tier_counts = (
            db.query(SubscriptionTier.name, func.count(MerchantSubscription.id))
            .join(
                SubscriptionTier,
                MerchantSubscription.tier_id == SubscriptionTier.id,
            )
            .filter(
                MerchantSubscription.status.in_([
                    SubscriptionStatus.ACTIVE.value,
                    SubscriptionStatus.TRIAL.value,
                ])
            )
            .group_by(SubscriptionTier.name)
            .all()
        )

        tier_distribution = dict(tier_counts)

        # Calculate MRR (Monthly Recurring Revenue)
        mrr_cents = 0
        arr_cents = 0

        active_subs = (
            db.query(MerchantSubscription, SubscriptionTier)
            .join(
                SubscriptionTier,
                MerchantSubscription.tier_id == SubscriptionTier.id,
            )
            .filter(MerchantSubscription.status == SubscriptionStatus.ACTIVE.value)
            .all()
        )

        for sub, sub_tier in active_subs:
            if sub.is_annual and sub_tier.price_annual_cents:
                mrr_cents += sub_tier.price_annual_cents // 12
                arr_cents += sub_tier.price_annual_cents
            else:
                mrr_cents += sub_tier.price_monthly_cents
                arr_cents += sub_tier.price_monthly_cents * 12

        stats["tier_distribution"] = tier_distribution
        stats["mrr_cents"] = mrr_cents
        stats["arr_cents"] = arr_cents

        return stats


# Singleton instance
admin_subscription_service = AdminSubscriptionService()