arc/docs/NOTIFICATION_AI_INTEGRATION.md

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

تاریخ: 1403/09/16

---

## 🎯 **تغییر رویکرد: از Ollama به AIService**

### ❌ رویکرد قبلی (اشتباه)
- استفاده از Ollama محلی
- نیاز به نصب و راه‌اندازی جداگانه
- عدم یکپارچگی با سیستم موجود
- مدیریت جداگانه configuration

### ✅ رویکرد جدید (صحیح)
- استفاده از `AIService` موجود در سیستم
- یکپارچه با تنظیمات OpenAI موجود
- مدیریت یکپارچه اعتبار و لاگ‌ها
- بدون نیاز به dependency اضافی

---

## 🏗️ **معماری یکپارچه**

```
┌─────────────────────────────────────────────┐
│         AIService (موجود)                   │
│   - OpenAI Integration                     │
│   - مدیریت اعتبار و سهمیه                  │
│   - ثبت لاگ استفاده                        │
│   - Function calling                       │
└───────────┬─────────────────────────────────┘
            │
            ├─────► Chat AI (موجود)
            ├─────► Support Tickets (موجود)
            ├─────► Document Analysis (موجود)
            └─────► Content Moderation ✨ (جدید)
                    │
                    └─► Notification Templates
                        Review & Approval
```

---

## 🔑 **نکات کلیدی**

### 1. استفاده از Context سیستمی

```python
class AIContentModerationService:
    def __init__(self, db: Session):
        self.db = db
        # بدون نیاز به Ollama client
    
    def _create_system_context(self) -> AuthContext:
        """ایجاد context سیستمی (superadmin)"""
        system_user = self.db.query(User).filter(
            User.is_superadmin == True,
            User.is_active == True
        ).first()
        
        return AuthContext(user=system_user, db=self.db)
```

**چرا superadmin?**
- خط 87-99 در `ai_service.py`: superadmin ها بدون محدودیت از AI استفاده می‌کنند
- بدون نیاز به subscription یا wallet
- هزینه‌ای به کاربر تحمیل نمی‌شود

### 2. فراخوانی AI برای Moderation

```python
async def _ai_review(self, content: str, subject: str, event_type: str):
    # ایجاد AI Service با context سیستمی
    system_ctx = self._create_system_context()
    ai_service = AIService(self.db, system_ctx, business_id=None)
    
    # ساخت prompt
    messages = [
        {"role": "user", "content": f"""بررسی محتوا: {content}..."""}
    ]
    
    # ارسال (بدون function calling، فقط text)
    response = await ai_service.chat_completion(
        messages=messages,
        use_function_calling=False,
        max_tokens_override=500
    )
    
    # ثبت لاگ (بدون شارژ)
    ai_service.log_usage(
        ...
        cost=0,  # رایگان برای سیستم
        payment_method="system",
        context={"type": "content_moderation"}
    )
```

### 3. مدیریت هزینه

| نوع استفاده | کاربر | هزینه | Payment Method |
|-------------|-------|-------|----------------|
| Chat AI | User | 💰 از wallet | "wallet" یا "subscription" |
| Support AI | Operator | 🆓 رایگان | "system" |
| **Moderation** | **System** | **🆓 رایگان** | **"system"** |

---

## 📊 **جریان کامل Moderation**

```
[کسب‌وکار] ایجاد قالب "تخفیف 50% فقط امروز!"
    ↓
[Worker] دریافت از صف
    ↓
┌─────────────────────────────────────┐
│  AIContentModerationService         │
├─────────────────────────────────────┤
│  1. Rule-based checks               │
│     ✓ طول محتوا                     │
│     ✓ Syntax قالب                   │
│  2. Spam Detector                   │
│     ⚠️ کلمه "تخفیف" → +15 score    │
│     ⚠️ "فقط امروز" → +15 score     │
│     ⚠️ "50%" → +20 score            │
│     Score: 50/100                   │
│  3. AI Review (via AIService)       │
│     → ایجاد system context          │
│     → فراخوانی chat_completion      │
│     → دریافت: is_promotional=true  │
│     → confidence: 85                │
│  4. تصمیم‌گیری نهایی                │
│     spam_score=50 + AI=85          │
│     → Decision: REJECT             │
│     → Confidence: 85%              │
└─────────────────────────────────────┘
    ↓
[Template] status = rejected
[Queue] completed
```

---

## 🔄 **مقایسه قبل و بعد**

| ویژگی | قبل (Ollama) | بعد (AIService) |
|-------|-------------|-----------------|
| نصب | نیاز به Ollama | ✅ بدون نیاز |
| Configuration | جداگانه | ✅ یکپارچه |
| Model | llama3.2 local | OpenAI (از تنظیمات) |
| Cost Management | ندارد | ✅ مدیریت می‌شود |
| Logging | ندارد | ✅ در ai_usage_logs |
| Consistency | متفاوت | ✅ یکسان با بقیه |
| Maintenance | دوگانه | ✅ یک سیستم |

---

## 💡 **مزایای این رویکرد**

### 1. یکپارچگی کامل
```python
# همه از AIService استفاده می‌کنند:
- Chat AI
- Support AI Reply
- Document AI
- Content Moderation ✨
```

### 2. مدیریت متمرکز
- یک Configuration
- یک System برای اعتبار
- یک Logging System
- یک Monitoring

### 3. کاهش Complexity
- بدون Ollama deployment
- بدون مدیریت دو سیستم AI
- کد تمیزتر و maintainable

### 4. امنیت بالاتر
- استفاده از مکانیزم احراز هویت موجود
- مدیریت دسترسی‌ها
- Audit trail یکپارچه

---

## 🔍 **کد نهایی (Core Parts)**

### AIContentModerationService

```python
class AIContentModerationService:
    def __init__(self, db: Session):
        self.db = db
        # بدون Ollama - فقط rule-based detectors
        self.spam_detector = SpamDetector()
        self.profanity_detector = ProfanityDetector()
    
    async def review_template(self, content, subject, event_type):
        # 1. Rule-based checks
        spam_result = self.spam_detector.analyze(content)
        profanity_result = self.profanity_detector.check(content)
        
        # 2. AI review (از AIService)
        ai_result = await self._ai_review(content, subject, event_type)
        
        # 3. تصمیم‌گیری
        decision, confidence = self._make_decision(
            spam_result, profanity_result, ai_result
        )
        
        return ModerationResult(...)
    
    async def _ai_review(self, content, subject, event_type):
        """استفاده از AIService موجود"""
        # ایجاد context سیستمی
        system_ctx = self._create_system_context()
        
        # ایجاد AI Service
        ai_service = AIService(self.db, system_ctx, business_id=None)
        
        # فراخوانی
        response = await ai_service.chat_completion(
            messages=[{"role": "user", "content": prompt}],
            use_function_calling=False,
            max_tokens_override=500
        )
        
        # ثبت لاگ بدون شارژ
        ai_service.log_usage(..., cost=0, payment_method="system")
        
        return parsed_json
    
    def _create_system_context(self):
        """پیدا کردن superadmin برای context"""
        system_user = self.db.query(User).filter(
            User.is_superadmin == True
        ).first()
        
        return AuthContext(user=system_user, db=self.db)
```

---

## 📈 **نتیجه**

### قبل از تغییر
```
سیستم نوتیفیکیشن
    ↓
Ollama (جداگانه)
    ↓
❌ دوگانگی در سیستم
```

### بعد از تغییر
```
سیستم نوتیفیکیشن
    ↓
AIService (موجود)
    ↓
✅ یکپارچگی کامل
```

---

## ✅ **Checklist نهایی**

- [x] حذف SimpleLLMClient
- [x] حذف Ollama dependencies
- [x] استفاده از AIService
- [x] استفاده از system context
- [x] ثبت لاگ با payment_method="system"
- [x] به‌روزرسانی Worker
- [x] به‌روزرسانی Documentation
- [x] بدون lint errors

---

## 🎉 **خلاصه**

یک سیستم نوتیفیکیشن **کاملاً یکپارچه** پیاده‌سازی شد که:

1. ✅ از `AIService` موجود استفاده می‌کند
2. ✅ بدون نیاز به Ollama یا نصب جداگانه
3. ✅ هزینه AI بر عهده سیستم (رایگان برای کسب‌وکارها)
4. ✅ لاگ‌گیری یکپارچه با سایر بخش‌ها
5. ✅ کد تمیز و maintainable
6. ✅ آماده برای production

**نتیجه نهایی**: یک سیستم حرفه‌ای، یکپارچه و بدون dependency اضافی! 🚀