telegram-premium-features

# Telegram Premium Features Implementation v2.0.0 Complete guide for implementing monetization features in Telegram-compatible backends. > 📚 **十次版本迭代优化** (v1.0.0 → v2.0.0) > > 本技能经过十次迭代完善，从基础会员系统到全球化支付解决方案的完整知识体系。 ## 版本迭代历程 | 版本 | 主题 | 文档 | |------|------|------| | v1.0.0 | 基础实现 | 本指南 | | v1.1.0 | 支付网关对比 | [查看](references/v1.1.0-payment-gateways.md) | | v1.2.0 | 订阅生命周期 | [查看](references/v1.2.0-lifecycle.md) | | v1.3.0 | 优惠券促销 | [查看](references/v1.3.0-coupons.md) | | v1.4.0 | 税务合规 | [查看](references/v1.4.0-tax.md) | | v1.5.0 | 退款争议 | [查看](references/v1.5.0-refunds.md) | | v1.6.0 | 推荐奖励 | [查看](references/v1.6.0-referral.md) | | v1.7.0 | 数据分析 | [查看](references/v1.7.0-analytics.md) | | v1.8.0 | A/B测试 | [查看](references/v1.8.0-ab-testing.md) | | v1.9.0 | 国际化 | [查看](references/v1.9.0-i18n.md) | | v2.0.0 | 完整总结 | [查看](references/v2.0.0-final.md) | ## 快速导航 **基础搭建**: 从 [Membership System](#implementation-membership-system) 开始 **支付集成**: 查看 [v1.1.0支付网关](references/v1.1.0-payment-gateways.md) **运营优化**: 参考 [v1.3.0优惠券](references/v1.3.0-coupons.md) 和 [v1.7.0数据分析](references/v1.7.0-analytics.md) **全球化**: 查看 [v1.9.0国际化](references/v1.9.0-i18n.md) ## Overview This guide covers common premium features for IM platforms: - Membership/subscription systems - Usage quotas and limits - Payment integration - Feature gating - Admin analytics ## Core Concepts ### Feature Gating Model ``` ┌─────────────────────────────────────────────────────────┐ │ Feature Check Flow │ ├─────────────────────────────────────────────────────────┤ │ 1. User requests feature (e.g., send large file) │ │ 2. System checks user tier (free/premium) │ │ 3. If premium → allow │ │ 4. If free → check quota │ │ 5. If quota exceeded → show upgrade prompt │ └─────────────────────────────────────────────────────────┘ ``` ### User Tiers | Tier | Features | Price | |------|----------|-------| | **Free** | Basic messaging, 100MB file limit, 1 month history | Free | | **Basic** | 500MB file limit, 6 months history, no ads | $4.99/mo | | **Premium** | 2GB file limit, unlimited history, priority support | $9.99/mo | | **Business** | 4GB file limit, unlimited history, custom domains | $19.99/mo | ## Implementation: Membership System ### Database Schema ```sql -- User subscription status CREATE TABLE user_subscriptions ( id BIGINT PRIMARY KEY AUTO_INCREMENT, user_id BIGINT NOT NULL, tier ENUM('free', 'basic', 'premium', 'business') DEFAULT 'free', status ENUM('active', 'expired', 'cancelled') DEFAULT 'active', started_at BIGINT DEFAULT 0, expires_at BIGINT DEFAULT 0, auto_renew BOOLEAN DEFAULT FALSE, payment_method VARCHAR(50), created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, UNIQUE KEY uk_user_id (user_id), INDEX idx_expires (expires_at), INDEX idx_status (status) ) ENGINE=InnoDB; -- Subscription plans CREATE TABLE subscription_plans ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(50) NOT NULL, tier ENUM('basic', 'premium', 'business') NOT NULL, price_monthly DECIMAL(10,2) NOT NULL, price_yearly DECIMAL(10,2) NOT NULL, features JSON, is_active BOOLEAN DEFAULT TRUE, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ) ENGINE=InnoDB; -- Insert default plans INSERT INTO subscription_plans (name, tier, price_monthly, price_yearly, features) VALUES ('Basic', 'basic', 4.99, 49.99, '{"file_limit": 536870912, "history_months": 6, "ads": false}'), ('Premium', 'premium', 9.99, 99.99, '{"file_limit": 2147483648, "history_months": -1, "priority_support": true}'), ('Business', 'business', 19.99, 199.99, '{"file_limit": 4294967296, "history_months": -1, "custom_domain": true}'); ``` ### Quota Tracking ```sql -- User quotas (daily/monthly limits) CREATE TABLE user_quotas ( id BIGINT PRIMARY KEY AUTO_INCREMENT, user_id BIGINT NOT NULL, quota_type VARCHAR(50) NOT NULL, limit_value BIGINT DEFAULT 0, used_value BIGINT DEFAULT 0, reset_at BIGINT DEFAULT 0, UNIQUE KEY uk_user_type (user_id, quota_type) ) ENGINE=InnoDB; -- Quota types: messages_daily, files_daily, storage_used ``` ### Core Implementation ```go // subscription_manager.go type SubscriptionManager struct { db *sqlx.DB redis *redis.Client } // CheckUserTier 检查用户等级 func (m *SubscriptionManager) CheckUserTier(ctx context.Context, userID int64) (Tier, error) { // Try cache cacheKey := fmt.Sprintf("user:tier:%d", userID) cached, err := m.redis.Get(ctx, cacheKey).Result() if err == nil { return Tier(cached), nil } // Query database var sub UserSubscription err = m.db.GetContext(ctx, &sub, "SELECT * FROM user_subscriptions WHERE user_id = ?", userID) if err == sql.ErrNoRows { return TierFree, nil } if err != nil { return TierFree, err } // Check expiration if sub.Status == "expired" || (sub.ExpiresAt > 0 && sub.ExpiresAt < time.Now().Unix()) { m.ExpireSubscription(ctx, userID) return TierFree, nil } // Cache result m.redis.Set(ctx, cacheKey, string(sub.Tier), 5*time.Minute) return Tier(sub.Tier), nil } // CheckFeatureAccess 检查功能访问权限 func (m *SubscriptionManager) CheckFeatureAccess(ctx context.Context, userID int64, feature string) (bool, error) { tier, err := m.CheckUserTier(ctx, userID) if err != nil { return false, err } // Feature requirement mapping requirements := map[string]Tier{ "large_files": TierBasic, "unlimited_history": TierPremium, "custom_domain": TierBusiness, "priority_support": TierPremium, } requiredTier, exists := requirements[feature] if !exists { return true, nil // Feature doesn't require tier } return tier >= requiredTier, nil } // CheckQuota 检查配额 func (m *SubscriptionManager) CheckQuota(ctx context.Context, userID int64, quotaType string) (bool, int64, error) { tier, _ := m.CheckUserTier(ctx, userID) // Get tier limits limits := m.getTierLimits(tier) limit := limits[quotaType] if limit < 0 { return true, -1, nil // Unlimited } // Get current usage var quota UserQuota err := m.db.GetContext(ctx, &quota, "SELECT * FROM user_quotas WHERE user_id = ? AND quota_type = ?", userID, quotaType) if err == sql.ErrNoRows { // No record yet return true, limit, nil } if err != nil { return false, 0, err } // Check if need reset if quota.ResetAt < time.Now().Unix() { m.resetQuota(ctx, userID, quotaType) return true, limit, nil } remaining := limit - quota.UsedValue return remaining > 0, remaining, nil } // UseQuota 使用配额 func (m *SubscriptionManager) UseQuota(ctx context.Context, userID int64, quotaType string, amount int64) error { _, err := m.db.ExecContext(ctx, `INSERT INTO user_quotas (user_id, quota_type, used_value, reset_at) VALUES (?, ?, ?, ?) ON DUPLICATE KEY UPDATE used_value = used_value + VALUES(used_value)`, userID, quotaType, amount, getNextResetTime()) return err } func (m *SubscriptionManager) getTierLimits(tier Tier) map[string]int64 { limits := map[Tier]map[string]int64{ TierFree: { "messages_daily": 1000, "files_daily": 50, "file_size": 100 * 1024 * 1024, // 100MB "storage": 1024 * 1024 * 1024, // 1GB }, TierBasic: { "messages_daily": 10000, "files_daily": 500, "file_size": 500 * 1024 * 1024, // 500MB "storage": 10 * 1024 * 1024 * 1024, // 10GB }, TierPremium: { "messages_daily": -1, // Unlimited "files_daily": -1, "file_size": 2 * 1024 * 1024 * 1024, // 2GB "storage": 100 * 1024 * 1024 * 1024, // 100GB }, } return limits[tier] } ``` ## Implementation: Payment Integration ### Stripe Integration ```go // stripe_payment.go import "github.com/stripe/stripe-go/v74" type StripePayment struct { client *stripe.Client } func (p *StripePayment) CreateCheckoutSession(ctx context.Context, userID int64, planID int) (string, error) { // Get plan details plan, err := p.getPlan(ctx, planID) if err != nil { return "", err } params := &stripe.CheckoutSessionParams{ CustomerEmail: stripe.String(getUserEmail(userID)), LineItems: []*stripe.CheckoutSessionLineItemParams{ { PriceData: &stripe.CheckoutSessionLineItemPriceDataParams{ Currency: stripe.String("usd"), ProductData: &stripe.CheckoutSessionLineItemPriceDataProductDataParams{ Name: stripe.String(plan.Name), }, UnitAmount: stripe.Int64(int64(plan.Price * 100)), // cents }, Quantity: stripe.Int64(1), }, }, Mode: stripe.String(string(stripe.CheckoutSessionModeSubscription)), SuccessURL: stripe.String(fmt.Sprintf("https://yourapp.com/success?user=%d", userID)), CancelURL: stripe.String("https://yourapp.com/cancel"), Metadata: map[string]string{ "user_id": fmt.Sprintf("%d", userID), "plan_id": fmt.Sprintf("%d", planID), }, } session, err := stripe.CheckoutSession(params) if err != nil { return "", err } return session.URL, nil } func (p *StripePayment) HandleWebhook(payload []byte, sig string) error { event, err := stripe.Webhook(payload, sig, webhookSecret) if err != nil { return err } switch event.Type { case "checkout.session.completed": var session stripe.CheckoutSession err := json.Unmarshal(event.Data.Raw, &session) if err != nil { return err } userID, _ := strconv.ParseInt(session.Metadata["user_id"], 10, 64) planID, _ := strconv.Atoi(session.Metadata["plan_id"]) // Activate subscription p.activateSubscription(userID, planID, session.Subscription.ID) case "invoice.payment_failed": // Handle failed payment p.handlePaymentFailure(event) } return nil } ``` ### Webhook Handler ```go // payment_webhook.go func (s *Server) PaymentWebhook(ctx context.Context, req *PaymentWebhookReq) (*Bool, error) { switch req.Provider { case "stripe": err := s.stripePayment.HandleWebhook(req.Payload, req.Signature) if err != nil { return BoolFalse, err } case "alipay": err := s.alipayPayment.HandleNotify(req.Payload) if err != nil { return BoolFalse, err } } return BoolTrue, nil } ``` ## Implementation: Feature Gating ### Middleware Pattern ```go // middleware/premium_middleware.go func PremiumMiddleware(next HandlerFunc) HandlerFunc { return func(ctx context.Context, req Request) (Response, error) { userID := getUserIDFromContext(ctx) feature := getFeatureFromRequest(req) // Check access hasAccess, err := subscriptionManager.CheckFeatureAccess(ctx, userID, feature) if err != nil { return nil, err } if !hasAccess { return nil, status.Error(codes.PermissionDenied, "This feature requires premium subscription") } // Check quota for usage-based features if isQuotaBased(feature) { allowed, remaining, err := subscriptionManager.CheckQuota(ctx, userID, feature) if err != nil { return nil, err } if !allowed { return nil, status.Errorf(codes.ResourceExhausted, "Quota exceeded. Upgrade to get more.") } // Update context with remaining quota ctx = context.WithValue(ctx, "remaining_quota", remaining) } return next(ctx, req) } } ``` ### Usage in Handlers ```go func (s *Server) MessagesSendDocument(ctx context.Context, req *SendDocumentReq) (*Message, error) { userID := getUserIDFromContext(ctx) fileSize := req.File.Size // Check file size limit tier, _ := s.subManager.CheckUserTier(ctx, userID) limits := s.subManager.getTierLimits(tier) if fileSize > limits["file_size"] { return nil, status.Errorf(codes.FailedPrecondition, "File too large. Max size for your tier: %d MB", limits["file_size"]/(1024*1024)) } // Check and use quota allowed, _, err := s.subManager.CheckQuota(ctx, userID, "files_daily") if err != nil { return nil, err } if !allowed { return nil, status.Errorf(codes.ResourceExhausted, "Daily file upload limit reached. Upgrade for unlimited uploads.") } // Use quota s.subManager.UseQuota(ctx, userID, "files_daily", 1) // Process document... } ``` ## Implementation: Admin Dashboard ### Revenue Analytics ```go // admin/analytics.go type RevenueAnalytics struct { db *sqlx.DB } func (a *RevenueAnalytics) GetRevenueReport(ctx context.Context, start, end time.Time) (*RevenueReport, error) { query := ` SELECT DATE(created_at) as date, SUM(amount) as revenue, COUNT(*) as transactions, tier, payment_method FROM premium_transactions WHERE status = 1 AND created_at BETWEEN ? AND ? GROUP BY DATE(created_at), tier, payment_method ORDER BY date DESC ` var rows []RevenueRow err := a.db.SelectContext(ctx, &rows, query, start, end) if err != nil { return nil, err } return &RevenueReport{ Rows: rows, Total: sumRevenue(rows), StartDate: start, EndDate: end, }, nil } func (a *RevenueAnalytics) GetUserRetention(ctx context.Context) (*RetentionReport, error) { query := ` SELECT tier, COUNT(*) as total_users, SUM(CASE WHEN expires_at > NOW() THEN 1 ELSE 0 END) as active_users, SUM(CASE WHEN auto_renew = 1 THEN 1 ELSE 0 END) as auto_renew_users FROM user_subscriptions GROUP BY tier ` var rows []RetentionRow err := a.db.SelectContext(ctx, &rows, query) return &RetentionReport{Rows: rows}, err } ``` ## Client-Side Integration ### Upgrade Prompt UI ```go // Client receives error and shows upgrade dialog func handleSendFileError(err error) { if status.Code(err) == codes.FailedPrecondition { // Show upgrade dialog showUpgradeDialog( title: "File Too Large", message: "Upgrade to Premium to send files up to 2GB", plans: getAvailablePlans() ) } else if status.Code(err) == codes.ResourceExhausted { // Show quota exceeded dialog showUpgradeDialog( title: "Daily Limit Reached", message: "You've reached your daily upload limit. Upgrade for unlimited uploads.", plans: getAvailablePlans() ) } } ``` ## Testing ### Unit Tests ```go func TestSubscriptionManager(t *testing.T) { ctx := context.Background() manager := NewSubscriptionManager(testDB, testRedis) t.Run("CheckUserTier", func(t *testing.T) { // Free user tier, err := manager.CheckUserTier(ctx, 1) assert.NoError(t, err) assert.Equal(t, TierFree, tier) // Premium user tier, err = manager.CheckUserTier(ctx, 2) assert.NoError(t, err) assert.Equal(t, TierPremium, tier) }) t.Run("CheckFeatureAccess", func(t *testing.T) { // Free user can't access premium feature hasAccess, err := manager.CheckFeatureAccess(ctx, 1, "large_files") assert.NoError(t, err) assert.False(t, hasAccess) // Premium user can access hasAccess, err = manager.CheckFeatureAccess(ctx, 2, "large_files") assert.NoError(t, err) assert.True(t, hasAccess) }) t.Run("CheckQuota", func(t *testing.T) { // Free user has limited quota allowed, remaining, err := manager.CheckQuota(ctx, 1, "files_daily") assert.NoError(t, err) assert.True(t, allowed) assert.Equal(t, int64(50), remaining) // Premium user has unlimited allowed, remaining, err = manager.CheckQuota(ctx, 2, "files_daily") assert.NoError(t, err) assert.True(t, allowed) assert.Equal(t, int64(-1), remaining) // Unlimited }) } ``` ## Best Practices 1. **Graceful Degradation**: Free users should still have usable experience 2. **Clear Communication**: Always tell users why a feature is blocked 3. **Easy Upgrade**: One-click upgrade flow 4. **Fair Pricing**: Transparent pricing with clear value proposition 5. **Analytics**: Track conversion rates and user behavior ## References - [Stripe Documentation](https://stripe.com/docs) - [PayPal Developer](https://developer.paypal.com/) - [RevenueCat (mobile subscriptions)](https://www.revenuecat.com/)