xiaoxia-saas/apps/api/app/schemas/subscription.py

"""Subscription schemas for API request/response models."""

from __future__ import annotations

from typing import Optional

from pydantic import BaseModel, Field

# ============ Enums / Types ============
# 会员体系（#1951/#1955 实装）：
#   free     — 免费用户
#   monthly  — 月卡
#   quarterly — 季卡
#   yearly   — 年卡
# 已废弃档位：standard / pro / enterprise（保留常量名便于识别旧字段，但不在 API 中暴露）


class MembershipType(str):
    """会员类型（与 packages.domain.points_rules.MEMBERSHIP_PRICES 一致）"""

    FREE = "free"
    MONTHLY = "monthly"
    QUARTERLY = "quarterly"
    YEARLY = "yearly"


class SubscriptionStatus(str):
    """订阅状态"""

    ACTIVE = "active"
    EXPIRED = "expired"
    CANCELLED = "cancelled"
    TRIAL = "trial"


class BillingStatus(str):
    """账单状态"""

    PAID = "paid"
    PENDING = "pending"
    FAILED = "failed"
    REFUNDED = "refunded"


class BillingCycle(str):
    """计费周期"""

    MONTHLY = "monthly"
    QUARTERLY = "quarterly"
    YEARLY = "yearly"


# ============ Response Schemas ============


class SubscriptionInfo(BaseModel):
    """当前订阅信息"""

    id: str
    plan_id: str
    plan_name: str
    status: str
    billing_cycle: str
    current_period_start: str
    current_period_end: str
    amount: float
    auto_renew: bool
    created_at: str


class BillingRecord(BaseModel):
    """账单记录"""

    id: str
    plan_name: str
    amount: float
    billing_cycle: str
    status: str
    payment_method: str
    created_at: str
    invoice_url: Optional[str] = None


class ChangePlanResponse(BaseModel):
    """升级/降级响应"""

    success: bool
    message: str
    new_subscription: Optional[SubscriptionInfo] = None


class SimpleResponse(BaseModel):
    """简单响应（用于取消订阅、切换自动续费等）"""

    success: bool
    message: str


# ============ Request Schemas ============


class ChangePlanRequest(BaseModel):
    """升级/降级请求"""

    target_plan_id: str = Field(..., description="目标会员类型: monthly/quarterly/yearly")
    billing_cycle: str = Field(..., description="计费周期: monthly/quarterly/yearly")


class ToggleAutoRenewRequest(BaseModel):
    """切换自动续费请求"""

    enabled: bool = Field(..., description="是否开启自动续费")