Upgrade your plan to access detailed analytics including import trends, product performance, and more.
- View Plans @@ -227,5 +227,5 @@ {% endblock %} {% block extra_scripts %} - + {% endblock %} diff --git a/app/modules/base.py b/app/modules/base.py index a330430b..0c45bbbc 100644 --- a/app/modules/base.py +++ b/app/modules/base.py @@ -45,6 +45,7 @@ if TYPE_CHECKING: from pydantic import BaseModel from app.modules.contracts.audit import AuditProviderProtocol + from app.modules.contracts.features import FeatureProviderProtocol from app.modules.contracts.metrics import MetricsProviderProtocol from app.modules.contracts.widgets import DashboardWidgetProviderProtocol @@ -65,7 +66,7 @@ class MenuItemDefinition: id: Unique identifier (e.g., "catalog.products", "orders.list") label_key: i18n key for the menu item label icon: Lucide icon name (e.g., "box", "shopping-cart") - route: URL path (can include placeholders like {vendor_code}) + route: URL path (can include placeholders like {store_code}) order: Sort order within section (lower = higher priority) is_mandatory: If True, cannot be hidden by user preferences requires_permission: Permission code required to see this item @@ -157,7 +158,7 @@ class PermissionDefinition: label_key: i18n key for the permission label description_key: i18n key for permission description category: Grouping category for UI organization (e.g., "products", "orders") - is_owner_only: If True, only vendor owners can have this permission + is_owner_only: If True, only store owners can have this permission Example: PermissionDefinition( @@ -251,7 +252,7 @@ class ModuleDefinition: # Routes admin_router: FastAPI router for admin routes - vendor_router: FastAPI router for vendor routes + store_router: FastAPI router for store routes # Lifecycle hooks on_enable: Called when module is enabled for a platform @@ -277,7 +278,7 @@ class ModuleDefinition: features=["subscription_management", "billing_history", "stripe_integration"], menu_items={ FrontendType.ADMIN: ["subscription-tiers", "subscriptions", "billing-history"], - FrontendType.VENDOR: ["billing"], + FrontendType.STORE: ["billing"], }, ) @@ -347,7 +348,7 @@ class ModuleDefinition: # Routes (registered dynamically) # ========================================================================= admin_router: "APIRouter | None" = None - vendor_router: "APIRouter | None" = None + store_router: "APIRouter | None" = None # ========================================================================= # Lifecycle Hooks @@ -455,6 +456,27 @@ class ModuleDefinition: # The provider will be discovered by core's AuditAggregator service. audit_provider: "Callable[[], AuditProviderProtocol] | None" = None + # ========================================================================= + # Feature Provider (Module-Driven Billable Features) + # ========================================================================= + # Callable that returns a FeatureProviderProtocol implementation. + # Use a callable (factory function) to enable lazy loading and avoid + # circular imports. Each module can declare its billable features + # and provide usage tracking for limit enforcement. + # + # Example: + # def _get_feature_provider(): + # from app.modules.catalog.services.catalog_features import catalog_feature_provider + # return catalog_feature_provider + # + # catalog_module = ModuleDefinition( + # code="catalog", + # feature_provider=_get_feature_provider, + # ) + # + # The provider will be discovered by billing's FeatureAggregator service. + feature_provider: "Callable[[], FeatureProviderProtocol] | None" = None + # ========================================================================= # Menu Item Methods (Legacy - uses menu_items dict of IDs) # ========================================================================= @@ -798,7 +820,7 @@ class ModuleDefinition: Get context contribution from this module for a frontend type. Args: - frontend_type: The frontend type (PLATFORM, ADMIN, VENDOR, STOREFRONT) + frontend_type: The frontend type (PLATFORM, ADMIN, STORE, STOREFRONT) request: FastAPI Request object db: Database session platform: Platform object (may be None for some contexts) @@ -885,6 +907,28 @@ class ModuleDefinition: return None return self.audit_provider() + # ========================================================================= + # Feature Provider Methods + # ========================================================================= + + def has_feature_provider(self) -> bool: + """Check if this module has a feature provider.""" + return self.feature_provider is not None + + def get_feature_provider_instance(self) -> "FeatureProviderProtocol | None": + """ + Get the feature provider instance for this module. + + Calls the feature_provider factory function to get the provider. + Returns None if no provider is configured. + + Returns: + FeatureProviderProtocol instance, or None + """ + if self.feature_provider is None: + return None + return self.feature_provider() + # ========================================================================= # Magic Methods # ========================================================================= diff --git a/app/modules/billing/__init__.py b/app/modules/billing/__init__.py index e67c49c0..db870f67 100644 --- a/app/modules/billing/__init__.py +++ b/app/modules/billing/__init__.py @@ -3,24 +3,25 @@ Billing Module - Subscription and payment management. This module provides: -- Subscription tier management -- Vendor subscription CRUD +- Merchant-level subscription management (per merchant per platform) +- Subscription tier management with TierFeatureLimit - Billing history and invoices - Stripe integration - Scheduled tasks for subscription lifecycle Routes: - Admin: /api/v1/admin/subscriptions/* -- Vendor: /api/v1/vendor/billing/* +- Store: /api/v1/store/billing/* +- Merchant: /api/v1/merchants/billing/* Menu Items: - Admin: subscription-tiers, subscriptions, billing-history -- Vendor: billing, invoices +- Store: billing, invoices Usage: from app.modules.billing import billing_module from app.modules.billing.services import subscription_service, stripe_service - from app.modules.billing.models import VendorSubscription, SubscriptionTier + from app.modules.billing.models import MerchantSubscription, SubscriptionTier from app.modules.billing.exceptions import TierLimitExceededException """ diff --git a/app/modules/billing/definition.py b/app/modules/billing/definition.py index 8ceb71b4..17d8c0a6 100644 --- a/app/modules/billing/definition.py +++ b/app/modules/billing/definition.py @@ -27,23 +27,34 @@ def _get_platform_context(request: Any, db: Any, platform: Any) -> dict[str, Any Returns pricing tier data for the marketing pricing page. """ from app.core.config import settings - from app.modules.billing.models import TIER_LIMITS, TierCode + from app.modules.billing.models import SubscriptionTier, TierCode + + tiers_db = ( + db.query(SubscriptionTier) + .filter( + SubscriptionTier.is_active == True, # noqa: E712 + SubscriptionTier.is_public == True, # noqa: E712 + ) + .order_by(SubscriptionTier.display_order) + .all() + ) tiers = [] - for tier_code, limits in TIER_LIMITS.items(): + for tier in tiers_db: + feature_codes = sorted(tier.get_feature_codes()) tiers.append({ - "code": tier_code.value, - "name": limits["name"], - "price_monthly": limits["price_monthly_cents"] / 100, - "price_annual": (limits["price_annual_cents"] / 100) - if limits.get("price_annual_cents") + "code": tier.code, + "name": tier.name, + "price_monthly": tier.price_monthly_cents / 100, + "price_annual": (tier.price_annual_cents / 100) + if tier.price_annual_cents else None, - "orders_per_month": limits.get("orders_per_month"), - "products_limit": limits.get("products_limit"), - "team_members": limits.get("team_members"), - "features": limits.get("features", []), - "is_popular": tier_code == TierCode.PROFESSIONAL, - "is_enterprise": tier_code == TierCode.ENTERPRISE, + "feature_codes": feature_codes, + "products_limit": tier.get_limit_for_feature("products_limit"), + "orders_per_month": tier.get_limit_for_feature("orders_per_month"), + "team_members": tier.get_limit_for_feature("team_members"), + "is_popular": tier.code == TierCode.PROFESSIONAL.value, + "is_enterprise": tier.code == TierCode.ENTERPRISE.value, }) return { @@ -65,11 +76,18 @@ def _get_admin_router(): return admin_router -def _get_vendor_router(): - """Lazy import of vendor router to avoid circular imports.""" - from app.modules.billing.routes.api.vendor import vendor_router +def _get_store_router(): + """Lazy import of store router to avoid circular imports.""" + from app.modules.billing.routes.api.store import store_router - return vendor_router + return store_router + + +def _get_feature_provider(): + """Lazy import of feature provider to avoid circular imports.""" + from app.modules.billing.services.billing_features import billing_feature_provider + + return billing_feature_provider # Billing module definition @@ -77,7 +95,7 @@ billing_module = ModuleDefinition( code="billing", name="Billing & Subscriptions", description=( - "Core subscription management, tier limits, vendor billing, and invoice history. " + "Core subscription management, tier limits, store billing, and invoice history. " "Provides tier-based feature gating used throughout the platform. " "Uses the payments module for actual payment processing." ), @@ -88,8 +106,8 @@ billing_module = ModuleDefinition( "billing_history", # View invoices and payment history "invoice_generation", # Generate and download invoices "subscription_analytics", # Subscription stats and metrics - "trial_management", # Manage vendor trial periods - "limit_overrides", # Override tier limits per vendor + "trial_management", # Manage store trial periods + "limit_overrides", # Override tier limits per store ], # Module-driven permissions permissions=[ @@ -127,12 +145,12 @@ billing_module = ModuleDefinition( menu_items={ FrontendType.ADMIN: [ "subscription-tiers", # Manage tier definitions - "subscriptions", # View/manage vendor subscriptions + "subscriptions", # View/manage store subscriptions "billing-history", # View all invoices ], - FrontendType.VENDOR: [ - "billing", # Vendor billing dashboard - "invoices", # Vendor invoice history + FrontendType.STORE: [ + "billing", # Store billing dashboard + "invoices", # Store invoice history ], }, # New module-driven menu definitions @@ -153,7 +171,7 @@ billing_module = ModuleDefinition( ), MenuItemDefinition( id="subscriptions", - label_key="billing.menu.vendor_subscriptions", + label_key="billing.menu.store_subscriptions", icon="credit-card", route="/admin/subscriptions", order=20, @@ -168,7 +186,7 @@ billing_module = ModuleDefinition( ], ), ], - FrontendType.VENDOR: [ + FrontendType.STORE: [ MenuSectionDefinition( id="sales", label_key="billing.menu.sales_orders", @@ -179,7 +197,7 @@ billing_module = ModuleDefinition( id="invoices", label_key="billing.menu.invoices", icon="currency-euro", - route="/vendor/{vendor_code}/invoices", + route="/store/{store_code}/invoices", order=30, ), ], @@ -194,7 +212,7 @@ billing_module = ModuleDefinition( id="billing", label_key="billing.menu.billing", icon="credit-card", - route="/vendor/{vendor_code}/billing", + route="/store/{store_code}/billing", order=30, ), ], @@ -244,6 +262,8 @@ billing_module = ModuleDefinition( options={"queue": "scheduled"}, ), ], + # Feature provider for feature flags + feature_provider=_get_feature_provider, ) @@ -255,7 +275,7 @@ def get_billing_module_with_routers() -> ModuleDefinition: during module initialization. """ billing_module.admin_router = _get_admin_router() - billing_module.vendor_router = _get_vendor_router() + billing_module.store_router = _get_store_router() return billing_module diff --git a/app/modules/billing/dependencies/feature_gate.py b/app/modules/billing/dependencies/feature_gate.py index 7f057bad..bcd7233d 100644 --- a/app/modules/billing/dependencies/feature_gate.py +++ b/app/modules/billing/dependencies/feature_gate.py @@ -1,44 +1,50 @@ -# app/core/feature_gate.py +# app/modules/billing/dependencies/feature_gate.py """ Feature gating decorator and dependencies for tier-based access control. +Resolves store → merchant → subscription → tier → TierFeatureLimit. + Provides: - @require_feature decorator for endpoints - RequireFeature dependency for flexible usage +- RequireWithinLimit dependency for quantitative checks - FeatureNotAvailableError exception with upgrade info Usage: # As decorator (simple) @router.get("/analytics") - @require_feature(FeatureCode.ANALYTICS_DASHBOARD) + @require_feature("analytics_dashboard") def get_analytics(...): ... # As dependency (more control) @router.get("/analytics") def get_analytics( - _: None = Depends(RequireFeature(FeatureCode.ANALYTICS_DASHBOARD)), + _: None = Depends(RequireFeature("analytics_dashboard")), ... ): ... - # Multiple features (any one required) - @require_feature(FeatureCode.ANALYTICS_DASHBOARD, FeatureCode.BASIC_REPORTS) - def get_reports(...): + # Quantitative limit check + @router.post("/products") + def create_product( + _: None = Depends(RequireWithinLimit("products_limit")), + ... + ): ... """ +import asyncio import functools import logging from typing import Callable -from fastapi import Depends, HTTPException, Request +from fastapi import Depends, HTTPException from sqlalchemy.orm import Session -from app.api.deps import get_current_vendor_api +from app.api.deps import get_current_store_api from app.core.database import get_db from app.modules.billing.services.feature_service import feature_service -from app.modules.billing.models import FeatureCode from app.modules.tenancy.models import User logger = logging.getLogger(__name__) @@ -46,7 +52,7 @@ logger = logging.getLogger(__name__) class FeatureNotAvailableError(HTTPException): """ - Exception raised when a feature is not available for the vendor's tier. + Exception raised when a feature is not available for the merchant's tier. Includes upgrade information for the frontend to display. """ @@ -61,7 +67,7 @@ class FeatureNotAvailableError(HTTPException): ): detail = { "error": "feature_not_available", - "message": f"This feature requires an upgrade to access.", + "message": "This feature requires an upgrade to access.", "feature_code": feature_code, "feature_name": feature_name, "upgrade": { @@ -77,16 +83,9 @@ class FeatureNotAvailableError(HTTPException): class RequireFeature: """ - Dependency class that checks if vendor has access to a feature. + Dependency class that checks if store's merchant has access to a feature. - Can be used as a FastAPI dependency: - @router.get("/analytics") - def get_analytics( - _: None = Depends(RequireFeature("analytics_dashboard")), - current_user: User = Depends(get_current_vendor_api), - db: Session = Depends(get_db), - ): - ... + Resolves store → merchant → subscription → tier → TierFeatureLimit. Args: *feature_codes: One or more feature codes. Access granted if ANY is available. @@ -99,58 +98,67 @@ class RequireFeature: def __call__( self, - current_user: User = Depends(get_current_vendor_api), + current_user: User = Depends(get_current_store_api), db: Session = Depends(get_db), ) -> None: - """Check if vendor has access to any of the required features.""" - vendor_id = current_user.token_vendor_id + """Check if store's merchant has access to any of the required features.""" + store_id = current_user.token_store_id - # Check if vendor has ANY of the required features for feature_code in self.feature_codes: - if feature_service.has_feature(db, vendor_id, feature_code): + if feature_service.has_feature_for_store(db, store_id, feature_code): return None - # None of the features are available - get upgrade info for first one + # None of the features are available feature_code = self.feature_codes[0] - upgrade_info = feature_service.get_feature_upgrade_info(db, feature_code) + raise FeatureNotAvailableError(feature_code=feature_code) - if upgrade_info: - raise FeatureNotAvailableError( - feature_code=feature_code, - feature_name=upgrade_info.feature_name, - required_tier_code=upgrade_info.required_tier_code, - required_tier_name=upgrade_info.required_tier_name, - required_tier_price_cents=upgrade_info.required_tier_price_monthly_cents, + +class RequireWithinLimit: + """ + Dependency that checks a quantitative resource limit. + + Resolves store → merchant → subscription → tier → TierFeatureLimit, + then checks current usage against the limit. + + Args: + feature_code: The quantitative feature to check (e.g., "products_limit") + """ + + def __init__(self, feature_code: str): + self.feature_code = feature_code + + def __call__( + self, + current_user: User = Depends(get_current_store_api), + db: Session = Depends(get_db), + ) -> None: + """Check if the resource limit allows adding more items.""" + store_id = current_user.token_store_id + + allowed, message = feature_service.check_resource_limit( + db, self.feature_code, store_id=store_id + ) + + if not allowed: + raise HTTPException( + status_code=403, + detail={ + "error": "limit_exceeded", + "message": message, + "feature_code": self.feature_code, + }, ) - else: - # Feature not found in registry - raise FeatureNotAvailableError(feature_code=feature_code) def require_feature(*feature_codes: str) -> Callable: """ Decorator to require one or more features for an endpoint. - The decorated endpoint will return 403 with upgrade info if the vendor + The decorated endpoint will return 403 if the store's merchant doesn't have access to ANY of the specified features. Args: *feature_codes: One or more feature codes. Access granted if ANY is available. - - Example: - @router.get("/analytics/dashboard") - @require_feature(FeatureCode.ANALYTICS_DASHBOARD) - async def get_analytics_dashboard( - current_user: User = Depends(get_current_vendor_api), - db: Session = Depends(get_db), - ): - ... - - # Multiple features (any one is sufficient) - @router.get("/reports") - @require_feature(FeatureCode.ANALYTICS_DASHBOARD, FeatureCode.BASIC_REPORTS) - async def get_reports(...): - ... """ if not feature_codes: raise ValueError("At least one feature code is required") @@ -158,48 +166,25 @@ def require_feature(*feature_codes: str) -> Callable: def decorator(func: Callable) -> Callable: @functools.wraps(func) async def async_wrapper(*args, **kwargs): - # Extract dependencies from kwargs db = kwargs.get("db") current_user = kwargs.get("current_user") - if not db or not current_user: - # Try to get from request if not in kwargs - request = kwargs.get("request") - if request and hasattr(request, "state"): - db = getattr(request.state, "db", None) - current_user = getattr(request.state, "user", None) - if not db or not current_user: raise HTTPException( status_code=500, detail="Feature check failed: missing db or current_user dependency", ) - vendor_id = current_user.token_vendor_id + store_id = current_user.token_store_id - # Check if vendor has ANY of the required features for feature_code in feature_codes: - if feature_service.has_feature(db, vendor_id, feature_code): + if feature_service.has_feature_for_store(db, store_id, feature_code): return await func(*args, **kwargs) - # None available - raise with upgrade info - feature_code = feature_codes[0] - upgrade_info = feature_service.get_feature_upgrade_info(db, feature_code) - - if upgrade_info: - raise FeatureNotAvailableError( - feature_code=feature_code, - feature_name=upgrade_info.feature_name, - required_tier_code=upgrade_info.required_tier_code, - required_tier_name=upgrade_info.required_tier_name, - required_tier_price_cents=upgrade_info.required_tier_price_monthly_cents, - ) - else: - raise FeatureNotAvailableError(feature_code=feature_code) + raise FeatureNotAvailableError(feature_code=feature_codes[0]) @functools.wraps(func) def sync_wrapper(*args, **kwargs): - # Extract dependencies from kwargs db = kwargs.get("db") current_user = kwargs.get("current_user") @@ -209,30 +194,13 @@ def require_feature(*feature_codes: str) -> Callable: detail="Feature check failed: missing db or current_user dependency", ) - vendor_id = current_user.token_vendor_id + store_id = current_user.token_store_id - # Check if vendor has ANY of the required features for feature_code in feature_codes: - if feature_service.has_feature(db, vendor_id, feature_code): + if feature_service.has_feature_for_store(db, store_id, feature_code): return func(*args, **kwargs) - # None available - raise with upgrade info - feature_code = feature_codes[0] - upgrade_info = feature_service.get_feature_upgrade_info(db, feature_code) - - if upgrade_info: - raise FeatureNotAvailableError( - feature_code=feature_code, - feature_name=upgrade_info.feature_name, - required_tier_code=upgrade_info.required_tier_code, - required_tier_name=upgrade_info.required_tier_name, - required_tier_price_cents=upgrade_info.required_tier_price_monthly_cents, - ) - else: - raise FeatureNotAvailableError(feature_code=feature_code) - - # Return appropriate wrapper based on whether func is async - import asyncio + raise FeatureNotAvailableError(feature_code=feature_codes[0]) if asyncio.iscoroutinefunction(func): return async_wrapper @@ -242,13 +210,9 @@ def require_feature(*feature_codes: str) -> Callable: return decorator -# ============================================================================ -# Convenience Exports -# ============================================================================ - __all__ = [ "require_feature", "RequireFeature", + "RequireWithinLimit", "FeatureNotAvailableError", - "FeatureCode", ] diff --git a/app/modules/billing/exceptions.py b/app/modules/billing/exceptions.py index e79293de..61f78bbd 100644 --- a/app/modules/billing/exceptions.py +++ b/app/modules/billing/exceptions.py @@ -74,10 +74,10 @@ BillingServiceError = BillingException class SubscriptionNotFoundException(ResourceNotFoundException): """Raised when a subscription is not found.""" - def __init__(self, vendor_id: int): + def __init__(self, store_id: int): super().__init__( resource_type="Subscription", - identifier=str(vendor_id), + identifier=str(store_id), error_code="SUBSCRIPTION_NOT_FOUND", ) diff --git a/app/modules/billing/locales/de.json b/app/modules/billing/locales/de.json index 0a2c39af..03056ad0 100644 --- a/app/modules/billing/locales/de.json +++ b/app/modules/billing/locales/de.json @@ -105,5 +105,23 @@ "orders_exceeded": "Monatliches Bestelllimit erreicht. Upgrade für mehr.", "products_exceeded": "Produktlimit erreicht. Upgrade für mehr.", "team_exceeded": "Teammitgliederlimit erreicht. Upgrade für mehr." + }, + "features": { + "subscription_management": { + "name": "Abonnementverwaltung", + "description": "Abonnementstufen und Abrechnung verwalten" + }, + "payment_processing": { + "name": "Zahlungsabwicklung", + "description": "Zahlungen über Stripe abwickeln" + }, + "invoicing": { + "name": "Rechnungsstellung", + "description": "Rechnungen erstellen und verwalten" + }, + "usage_tracking": { + "name": "Nutzungsverfolgung", + "description": "Funktionsnutzung gegen Stufenlimits verfolgen" + } } } diff --git a/app/modules/billing/locales/en.json b/app/modules/billing/locales/en.json index ffab8e16..ece47f56 100644 --- a/app/modules/billing/locales/en.json +++ b/app/modules/billing/locales/en.json @@ -105,5 +105,23 @@ "orders_exceeded": "Monthly order limit reached. Upgrade to continue.", "products_exceeded": "Product limit reached. Upgrade to add more.", "team_exceeded": "Team member limit reached. Upgrade to add more." + }, + "features": { + "subscription_management": { + "name": "Subscription Management", + "description": "Manage subscription tiers and billing" + }, + "payment_processing": { + "name": "Payment Processing", + "description": "Process payments via Stripe" + }, + "invoicing": { + "name": "Invoicing", + "description": "Generate and manage invoices" + }, + "usage_tracking": { + "name": "Usage Tracking", + "description": "Track feature usage against tier limits" + } } } diff --git a/app/modules/billing/locales/fr.json b/app/modules/billing/locales/fr.json index 1829825a..f9d4fd47 100644 --- a/app/modules/billing/locales/fr.json +++ b/app/modules/billing/locales/fr.json @@ -105,5 +105,23 @@ "orders_exceeded": "Limite mensuelle de commandes atteinte. Passez à un niveau supérieur.", "products_exceeded": "Limite de produits atteinte. Passez à un niveau supérieur.", "team_exceeded": "Limite de membres d'équipe atteinte. Passez à un niveau supérieur." + }, + "features": { + "subscription_management": { + "name": "Gestion des abonnements", + "description": "Gérer les niveaux d'abonnement et la facturation" + }, + "payment_processing": { + "name": "Traitement des paiements", + "description": "Traiter les paiements via Stripe" + }, + "invoicing": { + "name": "Facturation", + "description": "Générer et gérer les factures" + }, + "usage_tracking": { + "name": "Suivi d'utilisation", + "description": "Suivre l'utilisation des fonctionnalités par rapport aux limites du niveau" + } } } diff --git a/app/modules/billing/locales/lb.json b/app/modules/billing/locales/lb.json index 2622d438..44a75534 100644 --- a/app/modules/billing/locales/lb.json +++ b/app/modules/billing/locales/lb.json @@ -105,5 +105,23 @@ "orders_exceeded": "Monatlech Bestellungslimit erreecht. Upgrade fir méi.", "products_exceeded": "Produktlimit erreecht. Upgrade fir méi.", "team_exceeded": "Teammemberlimit erreecht. Upgrade fir méi." + }, + "features": { + "subscription_management": { + "name": "Abonnementverwaltung", + "description": "Abonnementstufen an Ofrechnung verwalten" + }, + "payment_processing": { + "name": "Zuelungsofwécklung", + "description": "Zuelungen iwwer Stripe ofwéckelen" + }, + "invoicing": { + "name": "Rechnungsstellung", + "description": "Rechnungen erstellen an verwalten" + }, + "usage_tracking": { + "name": "Notzungsverfolgung", + "description": "Funktiounsnotzung géint Stuflimiten verfolgen" + } } } diff --git a/app/modules/billing/migrations/versions/billing_001_merchant_subscriptions_and_feature_limits.py b/app/modules/billing/migrations/versions/billing_001_merchant_subscriptions_and_feature_limits.py new file mode 100644 index 00000000..2f7612ee --- /dev/null +++ b/app/modules/billing/migrations/versions/billing_001_merchant_subscriptions_and_feature_limits.py @@ -0,0 +1,179 @@ +# app/modules/billing/migrations/versions/billing_001_merchant_subscriptions_and_feature_limits.py +""" +Merchant subscriptions and feature limits migration. + +Creates: +- merchant_subscriptions table (replaces store_subscriptions) +- tier_feature_limits table (replaces hardcoded limit columns) +- merchant_feature_overrides table (replaces custom_*_limit columns) + +Drops: +- store_subscriptions table +- features table + +Alters: +- subscription_tiers: removes limit columns and features JSON + +Revision ID: billing_001 +""" + +from alembic import op +import sqlalchemy as sa + + +# Revision identifiers +revision = "billing_001" +down_revision = None +branch_labels = ("billing",) +depends_on = None + + +def upgrade() -> None: + # ======================================================================== + # Create merchant_subscriptions table + # ======================================================================== + op.create_table( + "merchant_subscriptions", + sa.Column("id", sa.Integer(), primary_key=True, index=True), + sa.Column("merchant_id", sa.Integer(), sa.ForeignKey("merchants.id", ondelete="CASCADE"), nullable=False, index=True), + sa.Column("platform_id", sa.Integer(), sa.ForeignKey("platforms.id", ondelete="CASCADE"), nullable=False, index=True), + sa.Column("tier_id", sa.Integer(), sa.ForeignKey("subscription_tiers.id", ondelete="SET NULL"), nullable=True, index=True), + sa.Column("status", sa.String(20), nullable=False, server_default="trial", index=True), + sa.Column("is_annual", sa.Boolean(), nullable=False, server_default="0"), + sa.Column("period_start", sa.DateTime(timezone=True), nullable=False), + sa.Column("period_end", sa.DateTime(timezone=True), nullable=False), + sa.Column("trial_ends_at", sa.DateTime(timezone=True), nullable=True), + sa.Column("stripe_customer_id", sa.String(100), nullable=True, index=True), + sa.Column("stripe_subscription_id", sa.String(100), nullable=True, index=True), + sa.Column("stripe_payment_method_id", sa.String(100), nullable=True), + sa.Column("payment_retry_count", sa.Integer(), nullable=False, server_default="0"), + sa.Column("last_payment_error", sa.Text(), nullable=True), + sa.Column("cancelled_at", sa.DateTime(timezone=True), nullable=True), + sa.Column("cancellation_reason", sa.Text(), nullable=True), + sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()), + sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()), + sa.UniqueConstraint("merchant_id", "platform_id", name="uq_merchant_platform_subscription"), + ) + op.create_index("idx_merchant_sub_status", "merchant_subscriptions", ["merchant_id", "status"]) + op.create_index("idx_merchant_sub_platform", "merchant_subscriptions", ["platform_id", "status"]) + + # ======================================================================== + # Create tier_feature_limits table + # ======================================================================== + op.create_table( + "tier_feature_limits", + sa.Column("id", sa.Integer(), primary_key=True, index=True), + sa.Column("tier_id", sa.Integer(), sa.ForeignKey("subscription_tiers.id", ondelete="CASCADE"), nullable=False, index=True), + sa.Column("feature_code", sa.String(80), nullable=False, index=True), + sa.Column("limit_value", sa.Integer(), nullable=True), + sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()), + sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()), + sa.UniqueConstraint("tier_id", "feature_code", name="uq_tier_feature_code"), + ) + op.create_index("idx_tier_feature_lookup", "tier_feature_limits", ["tier_id", "feature_code"]) + + # ======================================================================== + # Create merchant_feature_overrides table + # ======================================================================== + op.create_table( + "merchant_feature_overrides", + sa.Column("id", sa.Integer(), primary_key=True, index=True), + sa.Column("merchant_id", sa.Integer(), sa.ForeignKey("merchants.id", ondelete="CASCADE"), nullable=False, index=True), + sa.Column("platform_id", sa.Integer(), sa.ForeignKey("platforms.id", ondelete="CASCADE"), nullable=False, index=True), + sa.Column("feature_code", sa.String(80), nullable=False, index=True), + sa.Column("limit_value", sa.Integer(), nullable=True), + sa.Column("is_enabled", sa.Boolean(), nullable=False, server_default="1"), + sa.Column("reason", sa.String(255), nullable=True), + sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()), + sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()), + sa.UniqueConstraint("merchant_id", "platform_id", "feature_code", name="uq_merchant_platform_feature"), + ) + op.create_index("idx_merchant_override_lookup", "merchant_feature_overrides", ["merchant_id", "platform_id", "feature_code"]) + + # ======================================================================== + # Drop legacy tables + # ======================================================================== + op.drop_table("store_subscriptions") + op.drop_table("features") + + # ======================================================================== + # Remove legacy columns from subscription_tiers + # ======================================================================== + with op.batch_alter_table("subscription_tiers") as batch_op: + batch_op.drop_column("orders_per_month") + batch_op.drop_column("products_limit") + batch_op.drop_column("team_members") + batch_op.drop_column("order_history_months") + batch_op.drop_column("cms_pages_limit") + batch_op.drop_column("cms_custom_pages_limit") + batch_op.drop_column("features") + + # ======================================================================== + # Update stripe_webhook_events FK to merchant_subscriptions + # ======================================================================== + with op.batch_alter_table("stripe_webhook_events") as batch_op: + batch_op.drop_column("subscription_id") + batch_op.add_column( + sa.Column("merchant_subscription_id", sa.Integer(), + sa.ForeignKey("merchant_subscriptions.id"), nullable=True, index=True) + ) + + # ======================================================================== + # Add merchant_id to billing_history + # ======================================================================== + with op.batch_alter_table("billing_history") as batch_op: + batch_op.add_column( + sa.Column("merchant_id", sa.Integer(), + sa.ForeignKey("merchants.id"), nullable=True, index=True) + ) + + +def downgrade() -> None: + # Remove merchant_id from billing_history + with op.batch_alter_table("billing_history") as batch_op: + batch_op.drop_column("merchant_id") + + # Restore subscription_id on stripe_webhook_events + with op.batch_alter_table("stripe_webhook_events") as batch_op: + batch_op.drop_column("merchant_subscription_id") + batch_op.add_column( + sa.Column("subscription_id", sa.Integer(), + sa.ForeignKey("store_subscriptions.id"), nullable=True, index=True) + ) + + # Restore columns on subscription_tiers + with op.batch_alter_table("subscription_tiers") as batch_op: + batch_op.add_column(sa.Column("orders_per_month", sa.Integer(), nullable=True)) + batch_op.add_column(sa.Column("products_limit", sa.Integer(), nullable=True)) + batch_op.add_column(sa.Column("team_members", sa.Integer(), nullable=True)) + batch_op.add_column(sa.Column("order_history_months", sa.Integer(), nullable=True)) + batch_op.add_column(sa.Column("cms_pages_limit", sa.Integer(), nullable=True)) + batch_op.add_column(sa.Column("cms_custom_pages_limit", sa.Integer(), nullable=True)) + batch_op.add_column(sa.Column("features", sa.JSON(), nullable=True)) + + # Recreate features table + op.create_table( + "features", + sa.Column("id", sa.Integer(), primary_key=True), + sa.Column("code", sa.String(50), unique=True, nullable=False), + sa.Column("name", sa.String(100), nullable=False), + sa.Column("description", sa.Text(), nullable=True), + sa.Column("category", sa.String(50), nullable=False), + sa.Column("is_active", sa.Boolean(), server_default="1"), + ) + + # Recreate store_subscriptions table + op.create_table( + "store_subscriptions", + sa.Column("id", sa.Integer(), primary_key=True), + sa.Column("store_id", sa.Integer(), sa.ForeignKey("stores.id"), unique=True, nullable=False), + sa.Column("tier", sa.String(20), nullable=False, server_default="essential"), + sa.Column("status", sa.String(20), nullable=False, server_default="trial"), + sa.Column("period_start", sa.DateTime(timezone=True), nullable=False), + sa.Column("period_end", sa.DateTime(timezone=True), nullable=False), + ) + + # Drop new tables + op.drop_table("merchant_feature_overrides") + op.drop_table("tier_feature_limits") + op.drop_table("merchant_subscriptions") diff --git a/app/modules/billing/models/feature.py b/app/modules/billing/models/feature.py deleted file mode 100644 index 07162bfc..00000000 --- a/app/modules/billing/models/feature.py +++ /dev/null @@ -1,200 +0,0 @@ -# app/modules/billing/models/feature.py -""" -Feature registry for tier-based access control. - -Provides a database-driven feature registry that allows: -- Dynamic feature-to-tier assignment (no code changes needed) -- UI metadata for frontend rendering -- Feature categorization for organization -- Upgrade prompts with tier info - -Features are assigned to tiers via the SubscriptionTier.features JSON array. -This model provides the metadata and acts as a registry of all available features. -""" - -import enum -from datetime import UTC, datetime - -from sqlalchemy import Boolean, Column, DateTime, ForeignKey, Index, Integer, String, Text -from sqlalchemy.orm import relationship - -from app.core.database import Base -from models.database.base import TimestampMixin - - -class FeatureCategory(str, enum.Enum): - """Feature categories for organization.""" - - ORDERS = "orders" - INVENTORY = "inventory" - ANALYTICS = "analytics" - INVOICING = "invoicing" - INTEGRATIONS = "integrations" - TEAM = "team" - BRANDING = "branding" - CUSTOMERS = "customers" - CMS = "cms" - - -class FeatureUILocation(str, enum.Enum): - """Where the feature appears in the UI.""" - - SIDEBAR = "sidebar" # Main navigation item - DASHBOARD = "dashboard" # Dashboard widget/section - SETTINGS = "settings" # Settings page option - API = "api" # API-only feature (no UI) - INLINE = "inline" # Inline feature within a page - - -class Feature(Base, TimestampMixin): - """ - Feature registry for tier-based access control. - - Each feature represents a capability that can be enabled/disabled per tier. - The actual tier assignment is stored in SubscriptionTier.features as a JSON - array of feature codes. This table provides metadata for: - - UI rendering (icons, labels, locations) - - Upgrade prompts (which tier unlocks this?) - - Admin management (description, categorization) - - Example features: - - analytics_dashboard: Full analytics with charts - - api_access: REST API access for integrations - - team_roles: Role-based permissions for team members - - automation_rules: Automatic order processing rules - """ - - __tablename__ = "features" - - id = Column(Integer, primary_key=True, index=True) - - # Unique identifier used in code and tier.features JSON - code = Column(String(50), unique=True, nullable=False, index=True) - - # Display info - name = Column(String(100), nullable=False) - description = Column(Text, nullable=True) - - # Categorization - category = Column(String(50), nullable=False, index=True) - - # UI metadata - tells frontend how to render - ui_location = Column(String(50), nullable=True) # sidebar, dashboard, settings, api - ui_icon = Column(String(50), nullable=True) # Icon name (e.g., "chart-bar") - ui_route = Column(String(100), nullable=True) # Route pattern (e.g., "/vendor/{code}/analytics") - ui_badge_text = Column(String(20), nullable=True) # Badge to show (e.g., "Pro", "New") - - # Minimum tier that includes this feature (for upgrade prompts) - # This is denormalized for performance - the actual assignment is in SubscriptionTier.features - minimum_tier_id = Column( - Integer, ForeignKey("subscription_tiers.id"), nullable=True, index=True - ) - minimum_tier = relationship("SubscriptionTier", foreign_keys=[minimum_tier_id]) - - # Status - is_active = Column(Boolean, default=True, nullable=False) # Feature available at all - is_visible = Column(Boolean, default=True, nullable=False) # Show in UI even if locked - display_order = Column(Integer, default=0, nullable=False) # Sort order within category - - # Indexes - __table_args__ = ( - Index("idx_feature_category_order", "category", "display_order"), - Index("idx_feature_active_visible", "is_active", "is_visible"), - ) - - def __repr__(self) -> str: - return f"View your invoices and payment history.
+| Date | +Invoice # | +Amount | +Status | +Actions | +
|---|---|---|---|---|
| + + Loading invoices... + | +||||
| + No invoices found. + | +||||
| + | + | + + | ++ + | +
+
+
+
+ View
+
+
+
+ PDF
+
+
+ |
+
Here is an overview of your account.
+Active Subscriptions
+--
+Total Stores
+--
+Current Plan
+--
++ · + Renews +
+No active subscriptions.
+Sign in to manage your account
++ © 2026 Wizamart. All rights reserved. +
+Manage your platform subscriptions and plans.
+| Platform | +Tier | +Status | +Period End | +Actions | +
|---|---|---|---|---|
| + + Loading subscriptions... + | +||||
| + No subscriptions found. + | +||||
| + + + | ++ + | ++ + | ++ | + + View Details + + | +