arc/docs/AI_CREDIT_CHECK_IMPLEMENTATION.md

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

## 📋 خلاصه

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

---

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

### **۱. بکند (Backend)**

#### **الف) افزودن متد `check_availability` به `AIService`**
**فایل**: `hesabixAPI/app/services/ai/ai_service.py`

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

```python
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**:
```json
{
  "business_id": 123,
  "estimated_tokens": 1000
}
```

**Response**:
```json
{
  "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`**

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

**قبل**:
```python
raise ApiError("QUOTA_EXCEEDED", "سهمیه تمام شده است", http_status=400)
```

**بعد**:
```python
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`

```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. **چک اعتبار قبل از ارسال پیام**:
```dart
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. **نمایش دیالوگ خطای تفصیلی**:
```dart
void _showDetailedError(Map<String, dynamic> errorData) {
  // نمایش دیالوگ با جزئیات خطا و دکمه‌های عملیاتی:
  // - دکمه ارتقا پلن
  // - دکمه شارژ کیف پول
  // - پیام‌های راهنما
}
```

3. **نمایش هشدار کم بودن اعتبار**:
```dart
Widget _buildCreditWarning() {
  // نمایش warning banner در بالای چت
  // زمانی که usage >= 80%
}
```

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

4. **چک خودکار بعد از انتخاب session**:
```dart
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](./AI_CHAT_IMPLEMENTATION.md)
- [Telegram AI Chat Scenario](./TELEGRAM_AI_CHAT_SCENARIO.md)
- [Wallet Service Documentation](./WALLET_SERVICE.md)

---

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