feat: complete subscription billing system phases 6-10

Phase 6 - Database-driven tiers:
- Update subscription_service to query database first with legacy fallback
- Add get_tier_info() db parameter and _get_tier_from_legacy() method

Phase 7 - Platform health integration:
- Add get_subscription_capacity() for theoretical vs actual capacity
- Include subscription capacity in full health report

Phase 8 - Background subscription tasks:
- Add reset_period_counters() for billing period resets
- Add check_trial_expirations() for trial management
- Add sync_stripe_status() for Stripe synchronization
- Add cleanup_stale_subscriptions() for maintenance
- Add capture_capacity_snapshot() for daily metrics

Phase 10 - Capacity planning & forecasting:
- Add CapacitySnapshot model for historical tracking
- Create capacity_forecast_service with growth trends
- Add /subscription-capacity, /trends, /recommendations endpoints
- Add /snapshot endpoint for manual captures

Also includes billing API enhancements from phase 4:
- Add upcoming-invoice, change-tier, addon purchase/cancel endpoints
- Add UsageSummary schema for billing page
- Enhance billing.js with addon management functions

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

models/database/subscription.py

@@ -652,3 +652,61 @@ class VendorSubscription(Base, TimestampMixin):
         """Reset counters for new billing period."""
         self.orders_this_period = 0
         self.orders_limit_reached_at = None
+
+
+# ============================================================================
+# Capacity Planning
+# ============================================================================
+
+
+class CapacitySnapshot(Base, TimestampMixin):
+    """
+    Daily snapshot of platform capacity metrics.
+
+    Used for growth trending and capacity forecasting.
+    Captured daily by background job.
+    """
+
+    __tablename__ = "capacity_snapshots"
+
+    id = Column(Integer, primary_key=True, index=True)
+    snapshot_date = Column(DateTime(timezone=True), nullable=False, unique=True, index=True)
+
+    # Vendor metrics
+    total_vendors = Column(Integer, default=0, nullable=False)
+    active_vendors = Column(Integer, default=0, nullable=False)
+    trial_vendors = Column(Integer, default=0, nullable=False)
+
+    # Subscription metrics
+    total_subscriptions = Column(Integer, default=0, nullable=False)
+    active_subscriptions = Column(Integer, default=0, nullable=False)
+
+    # Resource metrics
+    total_products = Column(Integer, default=0, nullable=False)
+    total_orders_month = Column(Integer, default=0, nullable=False)
+    total_team_members = Column(Integer, default=0, nullable=False)
+
+    # Storage metrics
+    storage_used_gb = Column(Numeric(10, 2), default=0, nullable=False)
+    db_size_mb = Column(Numeric(10, 2), default=0, nullable=False)
+
+    # Capacity metrics (theoretical limits from subscriptions)
+    theoretical_products_limit = Column(Integer, nullable=True)
+    theoretical_orders_limit = Column(Integer, nullable=True)
+    theoretical_team_limit = Column(Integer, nullable=True)
+
+    # Tier distribution (JSON: {"essential": 10, "professional": 5, ...})
+    tier_distribution = Column(JSON, nullable=True)
+
+    # Performance metrics
+    avg_response_ms = Column(Integer, nullable=True)
+    peak_cpu_percent = Column(Numeric(5, 2), nullable=True)
+    peak_memory_percent = Column(Numeric(5, 2), nullable=True)
+
+    # Indexes
+    __table_args__ = (
+        Index("ix_capacity_snapshots_date", "snapshot_date"),
+    )
+
+    def __repr__(self) -> str:
+        return f"<CapacitySnapshot(date={self.snapshot_date}, vendors={self.total_vendors})>"

models/schema/billing.py

@@ -146,6 +146,10 @@ class VendorSubscriptionWithVendor(VendorSubscriptionResponse):
     vendor_name: str
     vendor_code: str
 
+    # Usage counts (for admin display)
+    products_count: int | None = None
+    team_count: int | None = None
+
 
 class VendorSubscriptionListResponse(BaseModel):
     """Response for listing vendor subscriptions."""
@@ -157,6 +161,15 @@ class VendorSubscriptionListResponse(BaseModel):
     pages: int
 
 
+class VendorSubscriptionCreate(BaseModel):
+    """Schema for admin creating a vendor subscription."""
+
+    tier: str = "essential"
+    status: str = "trial"
+    trial_days: int = 14
+    is_annual: bool = False
+
+
 class VendorSubscriptionUpdate(BaseModel):
     """Schema for admin updating a vendor subscription."""
 

models/schema/subscription.py

@@ -134,6 +134,22 @@ class SubscriptionUsage(BaseModel):
     team_members_percent_used: float | None
 
 
+class UsageSummary(BaseModel):
+    """Usage summary for billing page display."""
+
+    orders_this_period: int
+    orders_limit: int | None
+    orders_remaining: int | None
+
+    products_count: int
+    products_limit: int | None
+    products_remaining: int | None
+
+    team_count: int
+    team_limit: int | None
+    team_remaining: int | None
+
+
 class SubscriptionStatusResponse(BaseModel):
     """Subscription status with usage and limits."""