GreenHomeBack/src/AI_QUERY_TRACKING.md

📊 سیستم ذخیره و ردیابی سوالات هوش مصنوعی

✅ قابلیت‌های اضافه شده

1. ذخیره خودکار سوالات و پاسخ‌ها

تمام سوالاتی که به AI ارسال می‌شود و پاسخ‌های دریافتی، به صورت خودکار در دیتابیس ذخیره می‌شوند.

2. ردیابی مصرف توکن

برای هر سوال، اطلاعات کامل توکن ذخیره می‌شود:

• PromptTokens: تعداد توکن‌های سوال
• CompletionTokens: تعداد توکن‌های پاسخ
• TotalTokens: مجموع توکن‌های استفاده شده

3. ارتباط با دستگاه

هر سوال می‌تواند به یک دستگاه خاص مرتبط شود (با ارسال deviceId)

4. ارتباط با کاربر

هر سوال می‌تواند به یک کاربر خاص مرتبط شود (با ارسال userId)

5. اندازه‌گیری زمان پاسخ

زمان پاسخ‌دهی به میلی‌ثانیه اندازه‌گیری و ذخیره می‌شود

📋 جدول دیتابیس: AIQueries

CREATE TABLE AIQueries (
    Id INT PRIMARY KEY IDENTITY,
    DeviceId INT NULL,                  -- شماره دستگاه (اختیاری)
    UserId INT NULL,                    -- شماره کاربر (اختیاری)
    Question NVARCHAR(MAX) NOT NULL,    -- سوال
    Answer NVARCHAR(MAX) NOT NULL,      -- پاسخ
    PromptTokens INT NOT NULL,          -- توکن‌های سوال
    CompletionTokens INT NOT NULL,      -- توکن‌های پاسخ
    TotalTokens INT NOT NULL,           -- مجموع توکن‌ها
    Model NVARCHAR(100) NULL,           -- مدل استفاده شده
    Temperature FLOAT NULL,             -- پارامتر Temperature
    ResponseTimeMs BIGINT NULL,         -- زمان پاسخ (میلی‌ثانیه)
    CreatedAt DATETIME2 NOT NULL,       -- زمان ایجاد
    
    -- Foreign Keys
    FOREIGN KEY (DeviceId) REFERENCES Devices(Id) ON DELETE SET NULL,
    FOREIGN KEY (UserId) REFERENCES Users(Id) ON DELETE SET NULL
);

-- Indexes برای کوئری سریع
CREATE INDEX IX_AIQueries_DeviceId ON AIQueries(DeviceId);
CREATE INDEX IX_AIQueries_UserId ON AIQueries(UserId);
CREATE INDEX IX_AIQueries_CreatedAt ON AIQueries(CreatedAt);

🚀 نحوه استفاده

1. پرسیدن سوال با ذخیره خودکار

درخواست:

POST /api/ai/ask
Content-Type: application/json

{
  "question": "دمای مناسب اتاق چقدر است؟",
  "systemPrompt": "شما یک مشاور خانه هوشمند هستید",
  "deviceId": 123,
  "userId": 456
}

پاسخ:

{
  "question": "دمای مناسب اتاق چقدر است؟",
  "answer": "دمای مناسب اتاق برای راحتی معمولاً بین 20 تا 24 درجه سانتیگراد است...",
  "deviceId": 123,
  "tokens": {
    "prompt": 25,
    "completion": 150,
    "total": 175
  },
  "responseTimeMs": 1234,
  "timestamp": "2025-12-16T12:00:00Z"
}

2. دریافت تاریخچه سوالات یک دستگاه

درخواست:

GET /api/ai/history/device/123?take=50

پاسخ:

{
  "queries": [
    {
      "id": 1,
      "question": "دمای مناسب اتاق چقدر است؟",
      "answer": "دمای مناسب اتاق...",
      "totalTokens": 175,
      "promptTokens": 25,
      "completionTokens": 150,
      "model": "deepseek-chat",
      "responseTimeMs": 1234,
      "createdAt": "2025-12-16T12:00:00Z"
    }
  ],
  "totalTokens": 5432
}

3. دریافت آمار کلی

درخواست:

GET /api/ai/stats

پاسخ:

{
  "totalQueries": 1523,
  "totalTokensUsed": 254789,
  "totalPromptTokens": 89234,
  "totalCompletionTokens": 165555,
  "averageResponseTimeMs": 1456.78,
  "todayQueries": 45,
  "todayTokens": 7890
}

📊 API Endpoints جدید

1. POST /api/ai/ask

پرسیدن سوال ساده با ذخیره خودکار

پارامترها:

• question (required): سوال
• systemPrompt (optional): زمینه برای AI
• deviceId (optional): شماره دستگاه
• userId (optional): شماره کاربر

2. POST /api/ai/chat

چت پیشرفته با ذخیره خودکار

پارامترها:

• messages (required): لیست پیام‌ها
• model (optional): مدل AI
• temperature (optional): پارامتر خلاقیت
• maxTokens (optional): حداکثر توکن پاسخ
• deviceId (optional): شماره دستگاه
• userId (optional): شماره کاربر

3. POST /api/ai/suggest

دریافت پیشنهاد برای خانه هوشمند

پارامترها:

• deviceContext (required): اطلاعات دستگاه
• deviceId (optional): شماره دستگاه
• userId (optional): شماره کاربر

4. GET /api/ai/history/device/{deviceId}

دریافت تاریخچه سوالات یک دستگاه

Query Parameters:

• take (optional, default: 50): تعداد رکورد

5. GET /api/ai/stats

دریافت آمار کلی استفاده از AI

💡 مثال‌های عملی

مثال 1: سوال درباره دستگاه خاص

curl -X POST http://localhost:5000/api/ai/ask \
  -H "Content-Type: application/json" \
  -d '{
    "question": "دمای فعلی بالاست، چه کنم؟",
    "deviceId": 123,
    "userId": 456
  }'

مثال 2: دریافت تاریخچه

curl http://localhost:5000/api/ai/history/device/123

مثال 3: دریافت آمار

curl http://localhost:5000/api/ai/stats

مثال 4: پیشنهاد برای دستگاه

curl -X POST http://localhost:5000/api/ai/suggest \
  -H "Content-Type: application/json" \
  -d '{
    "deviceContext": "دمای اتاق: 28 درجه، رطوبت: 65%, ساعت: 14:00",
    "deviceId": 123
  }'

🔍 کوئری‌های مفید SQL

1. پرتکرارترین سوالات

SELECT Question, COUNT(*) as Count
FROM AIQueries
GROUP BY Question
ORDER BY Count DESC
LIMIT 10;

2. مصرف توکن به تفکیک دستگاه

SELECT 
    d.DeviceName,
    COUNT(aq.Id) as QueryCount,
    SUM(aq.TotalTokens) as TotalTokens,
    AVG(aq.TotalTokens) as AvgTokens
FROM AIQueries aq
JOIN Devices d ON aq.DeviceId = d.Id
GROUP BY d.DeviceName
ORDER BY TotalTokens DESC;

3. سوالات امروز

SELECT *
FROM AIQueries
WHERE CAST(CreatedAt AS DATE) = CAST(GETDATE() AS DATE)
ORDER BY CreatedAt DESC;

4. میانگین زمان پاسخ

SELECT 
    Model,
    COUNT(*) as QueryCount,
    AVG(ResponseTimeMs) as AvgResponseTime,
    MIN(ResponseTimeMs) as MinResponseTime,
    MAX(ResponseTimeMs) as MaxResponseTime
FROM AIQueries
WHERE ResponseTimeMs IS NOT NULL
GROUP BY Model;

📈 گزارش‌های آماری

مصرف روزانه

public async Task<DailyUsageReport> GetDailyUsage(DateTime date)
{
    var queries = await dbContext.AIQueries
        .Where(q => q.CreatedAt.Date == date.Date)
        .ToListAsync();
    
    return new DailyUsageReport
    {
        Date = date,
        TotalQueries = queries.Count,
        TotalTokens = queries.Sum(q => q.TotalTokens),
        UniqueDevices = queries.Select(q => q.DeviceId).Distinct().Count()
    };
}

مصرف هر دستگاه

public async Task<DeviceUsageReport> GetDeviceUsage(int deviceId)
{
    var queries = await dbContext.AIQueries
        .Where(q => q.DeviceId == deviceId)
        .ToListAsync();
    
    return new DeviceUsageReport
    {
        DeviceId = deviceId,
        TotalQueries = queries.Count,
        TotalTokens = queries.Sum(q => q.TotalTokens),
        AverageResponseTime = queries.Average(q => q.ResponseTimeMs ?? 0)
    };
}

⚠️ نکات مهم

1. هزینه

• هر توکن هزینه دارد
• با استفاده از آمار، مصرف را کنترل کنید
• برای کاهش هزینه، سوالات مشابه را cache کنید

2. عملکرد

• Index ها برای کوئری سریع اضافه شده‌اند
• برای حجم بالا، از pagination استفاده کنید
• رکوردهای قدیمی را Archive کنید

3. حریم خصوصی

• سوالات کاربران ذخیره می‌شوند
• از این داده‌ها با احتیاط استفاده کنید
• در صورت نیاز، امکان حذف تاریخچه اضافه کنید

🔧 اعمال تغییرات در دیتابیس

Migration ایجاد شده و آماده اجرا است:

cd GreenHome.Infrastructure
dotnet ef database update --startup-project ../GreenHome.Api

یا اگر برنامه را اجرا کنید، Migration به صورت خودکار اعمال می‌شود (در Program.cs تنظیم شده).

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

• Entity: GreenHome.Domain/AIQuery.cs
• Service: GreenHome.Infrastructure/AIQueryService.cs
• Interface: GreenHome.Application/IAIQueryService.cs
• Controller: GreenHome.Api/Controllers/AIController.cs
• Migration: GreenHome.Infrastructure/Migrations/20251216113127_AddAIQueryTable.cs

🎯 استفاده‌های پیشرفته

1. تحلیل رفتار کاربر

var userQueries = await aiQueryService.GetUserQueriesAsync(userId, 100);
var topics = ExtractTopics(userQueries);
// تحلیل علایق کاربر

2. بهینه‌سازی پاسخ‌ها

// پیدا کردن سوالات با زمان پاسخ بالا
var slowQueries = await dbContext.AIQueries
    .Where(q => q.ResponseTimeMs > 3000)
    .ToListAsync();

3. گزارش هزینه

// محاسبه هزینه بر اساس توکن
var totalTokens = await aiQueryService.GetDeviceTotalTokensAsync(deviceId);
var estimatedCost = CalculateCost(totalTokens);

---

نکته: تمام سوالات و پاسخ‌ها اکنون به صورت خودکار ذخیره می‌شوند و نیازی به کار اضافی نیست! ✨