Seyyed_arc/docs/AI_CREDIT_CHECK_IMPLEMENTATION.md

پیاده‌سازی چک اعتبار و پکیج فعال برای هوش مصنوعی

📋 خلاصه

این سند توضیح می‌دهد که چگونه سیستم چک اعتبار پیشگیرانه و نمایش پیام‌های خطای تفصیلی برای استفاده از هوش مصنوعی پیاده‌سازی شده است.

---

✅ تغییرات انجام شده

۱. بکند (Backend)

الف) افزودن متد check_availability به AIService

فایل: hesabixAPI/app/services/ai/ai_service.py

متدی که قبل از ارسال پیام امکان استفاده از AI را چک می‌کند:

def check_availability(self, estimated_tokens: int = 1000) -> Dict[str, Any]:
    """
    بررسی اینکه آیا کاربر می‌تواند از AI استفاده کند
    (بدون ارسال واقعی پیام - برای چک پیشگیرانه)
    
    Returns:
        {
            "can_use": bool,
            "reason": str | None,  # NO_ACTIVE_SUBSCRIPTION, QUOTA_EXCEEDED, INSUFFICIENT_FUNDS
            "details": {
                "subscription": {...},
                "wallet": {...},
                "suggestions": [...]
            }
        }
    """

ویژگی‌ها:

• ✅ چک اشتراک فعال
• ✅ چک سهمیه رایگان/اشتراک
• ✅ چک موجودی کیف پول (برای پلن‌های pay_as_go و hybrid)
• ✅ محاسبه درصد استفاده و هشدار در 80%
• ✅ تخمین هزینه بر اساس تعداد توکن
• ✅ پیشنهادات عملی برای حل مشکل

ب) افزودن endpoint جدید

فایل: hesabixAPI/adapters/api/v1/ai/chat.py

POST /api/v1/ai/chat/check-availability

Request Body:

{
  "business_id": 123,
  "estimated_tokens": 1000
}

Response:

{
  "success": true,
  "data": {
    "can_use": true/false,
    "reason": "NO_ACTIVE_SUBSCRIPTION" | "QUOTA_EXCEEDED" | "INSUFFICIENT_FUNDS" | null,
    "details": {
      "subscription": {
        "plan_name": "پلن رایگان",
        "plan_type": "free",
        "tokens_used": 2500,
        "tokens_limit": 5000,
        "tokens_remaining": 2500,
        "usage_percentage": 50.0
      },
      "wallet": {
        "balance": 50000,
        "estimated_cost": 1500,
        "sufficient": true
      },
      "suggestions": [
        "⚠️ تنها ۲٬۵۰۰ توکن رایگان باقی مانده است",
        "پیشنهاد می‌کنیم به پلن بالاتر ارتقا دهید"
      ]
    }
  }
}

ج) بهبود پیام‌های خطا در check_quota_and_charge

خطاها حالا شامل اطلاعات تفصیلی هستند:

قبل:

raise ApiError("QUOTA_EXCEEDED", "سهمیه تمام شده است", http_status=400)

بعد:

raise ApiError(
    "QUOTA_EXCEEDED",
    f"سهمیه رایگان تمام شده است. باقیمانده: {tokens_remaining:,} توکن",
    http_status=400,
    extra_data={
        "tokens_used": 2500,
        "tokens_limit": 5000,
        "tokens_remaining": 2500,
        "tokens_required": 1000,
        "suggestion": "برای استفاده بیشتر، به پلن پولی ارتقا دهید"
    }
)

د) پیاده‌سازی در تلگرام

فایل: hesabixAPI/app/services/telegram_ai_chat_service.py

• ✅ چک اعتبار قبل از ارسال پیام
• ✅ نمایش پیام‌های فارسی و زیبا در تلگرام
• ✅ مدیریت خطاها در catch block

نمونه پیام خطا در تلگرام:

⚠️ سهمیه شما تمام شده است

استفاده شده: 5,000
سقف: 5,000

💡 برای ادامه:
• ارتقا به پلن بالاتر از داخل برنامه
• منتظر تمدید ماهانه بمانید

ه) پیاده‌سازی در تیکت‌های پشتیبانی

فایل: hesabixAPI/adapters/api/v1/support/ai_tickets.py

• ✅ چک اعتبار قبل از پیشنهاد پاسخ AI
• ✅ پیام‌های خطای مناسب برای اپراتورها

---

۲. فرانت (Frontend)

الف) افزودن متد checkAvailability به AIService

فایل: hesabixUI/hesabix_ui/lib/services/ai_service.dart

Future<Map<String, dynamic>> checkAvailability({
  int? businessId,
  int estimatedTokens = 1000,
}) async {
  final res = await _api.post<Map<String, dynamic>>(
    '/api/v1/ai/chat/check-availability',
    data: {
      if (businessId != null) 'business_id': businessId,
      'estimated_tokens': estimatedTokens,
    },
  );
  final body = res.data as Map<String, dynamic>;
  return body['data'] as Map<String, dynamic>;
}

ب) پیاده‌سازی چک پیشگیرانه در AIChatDialog

فایل: hesabixUI/hesabix_ui/lib/widgets/ai/ai_chat_dialog.dart

ویژگی‌های اضافه شده:

1. چک اعتبار قبل از ارسال پیام:

Future<void> _sendMessage() async {
  // چک اعتبار قبل از ارسال
  try {
    final availability = await _aiService.checkAvailability(
      businessId: widget.businessId,
      estimatedTokens: content.length * 2,
    );
    
    if (!(availability['can_use'] as bool? ?? false)) {
      _showDetailedError(availability);
      return;
    }
  } catch (e) {
    // در صورت خطا، اجازه ادامه بده
  }
  
  // ادامه ارسال...
}

2. نمایش دیالوگ خطای تفصیلی:

void _showDetailedError(Map<String, dynamic> errorData) {
  // نمایش دیالوگ با جزئیات خطا و دکمه‌های عملیاتی:
  // - دکمه ارتقا پلن
  // - دکمه شارژ کیف پول
  // - پیام‌های راهنما
}

3. نمایش هشدار کم بودن اعتبار:

Widget _buildCreditWarning() {
  // نمایش warning banner در بالای چت
  // زمانی که usage >= 80%
}

نمونه نمایش:

⚠️ اعتبار شما رو به اتمام است
2,500 توکن باقی مانده
                    [ارتقا پلن]

4. چک خودکار بعد از انتخاب session:

Future<void> _selectSession(AIChatSession session) async {
  // ...
  _checkAvailability(); // چک خودکار
}

---

🎯 سناریوهای پوشش داده شده

سناریو ۱: کاربر بدون اشتراک

قبل:

• کاربر پیام می‌فرستد
• AI پاسخ تولید می‌کند
• خطای "اشتراک فعالی وجود ندارد" ❌

بعد:

• کاربر پیام می‌نویسد
• قبل از ارسال، چک می‌شود
• دیالوگ زیبا با دکمه "مشاهده پلن‌ها" نمایش داده می‌شود ✅

---

سناریو ۲: سهمیه تمام شده (پلن رایگان)

قبل:

• کاربر پیام می‌فرستد
• AI پاسخ تولید می‌کند
• خطای "سهمیه تمام شده است" ❌

بعد:

• کاربر پیام می‌نویسد
• چک می‌شود: "شما 5,000 از 5,000 توکن خود را استفاده کرده‌اید"
• دکمه "ارتقا پلن" نمایش داده می‌شود ✅

---

سناریو ۳: موجودی کیف پول ناکافی

قبل:

• کاربر پیام می‌فرستد
• AI پاسخ تولید می‌کند
• خطای "موجودی کافی نیست" ❌

بعد:

• چک می‌شود: موجودی 1,000 ریال، هزینه تخمینی 2,500 ریال
• دکمه "شارژ کیف پول" نمایش داده می‌شود ✅

---

سناریو ۴: هشدار کم بودن اعتبار

زمانی که 80% سهمیه استفاده شده:

• Banner هشدار در بالای چت نمایش داده می‌شود
• "⚠️ اعتبار شما رو به اتمام است"
• دکمه "ارتقا پلن" برای راحتی کاربر

---

سناریو ۵: تلگرام

قبل:

• کاربر در تلگرام پیام می‌فرستد
• خطای ساده: "خطا در پردازش پیام" ❌

بعد:

💰 موجودی کیف پول ناکافی

موجودی فعلی: 1,000 ریال
هزینه تخمینی: 2,500 ریال

لطفاً از داخل برنامه، کیف پول خود را شارژ کنید.

        [🔙 بازگشت]

---

📊 کدهای خطا

کد	معنی	نمایش به کاربر
NO_ACTIVE_SUBSCRIPTION	اشتراک فعال ندارد	"نیاز به اشتراک" + دکمه مشاهده پلن‌ها
SUBSCRIPTION_INACTIVE	اشتراک منقضی شده	"اشتراک منقضی شده" + تاریخ انقضا
QUOTA_EXCEEDED	سهمیه تمام شده	نمایش استفاده/سقف + دکمه ارتقا
INSUFFICIENT_FUNDS	موجودی کیف پول کم	نمایش موجودی/هزینه + دکمه شارژ
AI_NOT_CONFIGURED	تنظیمات AI فعال نیست	پیام تماس با مدیر سیستم

---

🧪 تست

چک لیست تست

بکند:

• تست endpoint /api/v1/ai/chat/check-availability
  • با business_id
  • بدون business_id (استفاده از current business)
  • با estimated_tokens مختلف
• تست با اشتراک رایگان (free)
• تست با اشتراک ماهانه (subscription)
• تست با پلن pay_as_go
• تست بدون اشتراک
• تست با سهمیه تمام شده
• تست با موجودی کیف پول ناکافی

فرانت:

• تست دیالوگ چت
  • چک اعتبار قبل از ارسال
  • نمایش دیالوگ خطای تفصیلی
  • نمایش warning banner
• تست با سناریوهای مختلف خطا
• تست دکمه‌های عملیاتی (ارتقا پلن، شارژ کیف پول)

تلگرام:

• تست ارسال پیام در تلگرام
  • با اشتراک فعال
  • بدون اشتراک
  • با سهمیه تمام شده
  • با موجودی ناکافی
• تست نمایش پیام‌های فارسی و زیبا

تیکت‌های پشتیبانی:

• تست پیشنهاد پاسخ AI
• تست پاسخ خودکار AI
• تست با خطاهای مختلف اعتبار

---

📝 نکات مهم

۱. چک دو مرحله‌ای

سیستم دارای دو مرحله چک است:

1. چک پیشگیرانه (قبل از ارسال): با متد check_availability
2. چک نهایی (بعد از دریافت پاسخ): با متد check_quota_and_charge

این دو مرحله تضمین می‌کند که:

• کاربر قبل از ارسال متوجه مشکل می‌شود (UX بهتر)
• اگر تخمین اشتباه بود، بعد از دریافت پاسخ هم چک می‌شود (امنیت)

۲. تخمین توکن

برای چک پیشگیرانه، تخمین زده می‌شود:

estimated_tokens = message_length * 2

این تخمین تقریبی است و ممکن است با مقدار واقعی متفاوت باشد.

۳. Graceful Degradation

اگر چک اعتبار با خطا مواجه شود، سیستم به کاربر اجازه ادامه می‌دهد تا تجربه کاربری مختل نشود.

۴. پیام‌های کاربرپسند

تمام پیام‌ها:

• ✅ به فارسی
• ✅ با اعداد فرمت‌شده (1,000 به جای 1000)
• ✅ با ایموجی برای بهتر دیده شدن
• ✅ با پیشنهادات عملی

---

🔮 پیشنهادات آینده

1. پیش‌بینی دقیق‌تر هزینه: استفاده از ML برای تخمین دقیق‌تر توکن‌ها
2. خرید خودکار اعتبار: دکمه خرید مستقیم در دیالوگ خطا
3. نمایش تاریخ تمدید: برای پلن‌های اشتراکی
4. آمار مصرف: نمودار استفاده از AI در پروفایل کاربر
5. پیشنهاد پلن مناسب: بر اساس الگوی مصرف کاربر

---

📚 مستندات مرتبط

• AI Chat Implementation
• Telegram AI Chat Scenario
• Wallet Service Documentation

---

تاریخ: ۴ دسامبر ۲۰۲۵
نسخه: 1.0