GreenHomeBack/src/CHANGES_DAILY_REPORT.md

خلاصه تغییرات - API گزارش روزانه

تاریخ: 1403/09/26 (2024/12/16)

فایل‌های جدید ایجاد شده:

1. GreenHome.Domain/DailyReport.cs

   • Entity برای ذخیره گزارش‌های روزانه
   • شامل اطلاعات تحلیل AI، مصرف توکن، و متادیتای مرتبط

2. GreenHome.Application/IDailyReportService.cs

   • Interface سرویس گزارش روزانه

3. GreenHome.Infrastructure/DailyReportService.cs

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

4. GreenHome.Api/Controllers/DailyReportController.cs

   • Controller جدید با endpoint برای دریافت گزارش

5. GreenHome.Infrastructure/Migrations/20251216152746_AddDailyReportsTable.cs

   • Migration برای ایجاد جدول DailyReports

6. DAILY_REPORT_API.md

   • مستندات کامل API

فایل‌های ویرایش شده:

1. GreenHome.Application/Dtos.cs

   • افزودن DailyReportRequest
   • افزودن DailyReportResponse

2. GreenHome.Infrastructure/GreenHomeDbContext.cs

   • افزودن DbSet<DailyReport>
   • پیکربندی entity در OnModelCreating

3. GreenHome.Api/Program.cs

   • ثبت IDailyReportService در DI container

4. GreenHome.Infrastructure/GreenHome.Infrastructure.csproj

   • افزودن reference به GreenHome.AI.DeepSeek

ویژگی‌های کلیدی:

1. کش هوشمند

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

2. نمونه‌برداری بهینه

• از هر 20 رکورد، فقط 1 رکورد انتخاب می‌شود
• کاهش 95% در مصرف توکن

3. تحلیل جامع

• دما، رطوبت، نور، و کیفیت هوا (CO)
• روندهای روزانه و پیشنهادات بهبود

4. مدیریت خطا

• بررسی اعتبار ورودی‌ها
• لاگ کامل عملیات
• پیام‌های خطای واضح به فارسی

5. بهینه‌سازی دیتابیس

• Unique constraint بر روی (DeviceId, PersianDate)
• Index‌های مناسب برای جستجوی سریع
• Cascade delete برای یکپارچگی داده

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

GET /api/DailyReport?deviceId=1&persianDate=1403/09/26

پیش‌نیازها:

1. کانفیگ DeepSeek API در appsettings.json:

{
  "DeepSeek": {
    "ApiKey": "your-api-key",
    "BaseUrl": "https://api.deepseek.com"
  }
}

2. اجرای migration:

dotnet ef database update

یا به صورت خودکار در startup برنامه اعمال می‌شود.

نکات امنیتی:

• API key باید در environment variable یا Azure Key Vault نگهداری شود
• در production، rate limiting اضافه کنید
• برای دسترسی به API، authentication لازم است (در نسخه بعدی)

تست:

1. مطمئن شوید دیتابیس شامل رکوردهای تلمتری برای تاریخ مورد نظر است
2. درخواست اول باید گزارش جدید ایجاد کند (fromCache: false)
3. درخواست دوم با همان تاریخ باید از کش برگردد (fromCache: true)

آمار عملکرد:

• زمان پاسخ اولین درخواست: ~3-5 ثانیه (شامل فراخوانی AI)
• زمان پاسخ درخواست‌های بعدی: <100ms (از کش)
• مصرف توکن برای یک روز با 288 رکورد: ~800-1500 توکن
• بدون نمونه‌برداری: ~15000-20000 توکن (95% کاهش!)

TODO (پیشنهادات آینده):

• اضافه کردن فیلتر تاریخ (از تا) برای دریافت چندین گزارش
• ایجاد endpoint برای لیست کردن تمام گزارش‌های یک دستگاه
• امکان حذف و ایجاد مجدد گزارش (برای مدیران)
• اضافه کردن chart و نمودار به پاسخ
• ارسال گزارش به ایمیل یا SMS
• مقایسه گزارش‌های چند روزه
• پیشنهادات اتوماتیک برای تنظیمات دستگاه