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 سیستمی

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

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. یکپارچگی کامل

# همه از 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

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 نهایی

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

---

🎉 خلاصه

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

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

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