GreenHomeBack/src/DAILY_REPORT_API.md

API گزارش تحلیل روزانه گلخانه

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

اندپوینت

GET /api/DailyReport

پارامترها

پارامتر	نوع	الزامی	توضیحات
deviceId	int	بله	شناسه دستگاه
persianDate	string	بله	تاریخ شمسی به فرمت yyyy/MM/dd (مثال: 1403/09/26)

مثال درخواست

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

پاسخ موفق (200 OK)

{
  "id": 15,
  "deviceId": 1,
  "deviceName": "گلخانه اول",
  "persianDate": "1403/09/26",
  "analysis": "**وضعیت کلی:**\n\nدر طول روز 1403/09/26، شرایط گلخانه به طور کلی مطلوب بوده است. دمای متوسط حدود 25 درجه سانتیگراد، رطوبت 65 درصد و نور کافی (حدود 5000 لوکس) ثبت شده است. کیفیت هوا نیز با مقادیر CO در محدوده ایمن (کمتر از 100 PPM) مناسب بوده است.\n\n**روندهای مشاهده شده:**\n\n- دما در طول روز از 18 درجه صبح به 32 درجه ظهر رسیده و سپس کاهش یافته است.\n- رطوبت هوا در ساعات ظهر کاهش یافته ولی شب مجدداً افزایش یافته.\n- نور در ساعات صبح تا عصر در حد مطلوب و شب صفر بوده است.\n- مقادیر CO در کل روز در سطح ایمن باقی مانده.\n\n**نکات و هشدارها:**\n\n- دمای ظهر (32 درجه) کمی بالاست. توصیه می‌شود سیستم تهویه را بهبود دهید.\n- رطوبت شب بیش از حد است (85 درصد) که ممکن است منجر به رشد قارچ شود.\n\n**پیشنهادات:**\n\n1. نصب سیستم سایه‌بان خودکار برای کنترل دمای ظهر\n2. استفاده از هواکش در شب برای کاهش رطوبت\n3. بررسی سیستم آبیاری برای جلوگیری از رطوبت اضافی",
  "recordCount": 288,
  "sampledRecordCount": 15,
  "totalTokens": 1250,
  "createdAt": "2024-12-16T14:30:00Z",
  "fromCache": false
}

پاسخ‌های خطا

400 Bad Request

درخواست نامعتبر (شناسه دستگاه یا فرمت تاریخ اشتباه)

{
  "error": "تاریخ شمسی باید به فرمت yyyy/MM/dd باشد"
}

404 Not Found

دستگاه یا داده‌ای برای تاریخ مورد نظر یافت نشد

{
  "error": "هیچ رکوردی برای دستگاه 1 در تاریخ 1403/09/26 یافت نشد"
}

500 Internal Server Error

خطای سرور (مثلاً خطا در ارتباط با DeepSeek API)

{
  "error": "خطای سرور در پردازش درخواست"
}

نحوه عملکرد

1. بررسی کش: ابتدا سیستم چک می‌کند آیا برای این دستگاه و تاریخ، گزارشی قبلاً ایجاد شده یا نه. اگر وجود داشته باشد، همان گزارش برگردانده می‌شود (fromCache: true) و توکن جدیدی مصرف نمی‌شود.

2. استخراج داده‌ها: اگر گزارش موجود نباشد، تمام رکوردهای تلمتری آن روز از دیتابیس استخراج می‌شوند.

3. نمونه‌برداری: داده‌ها بر اساس زمان سورت می‌شوند و سپس از هر 20 رکورد، فقط رکورد اول انتخاب می‌شود. این کار برای کاهش مصرف توکن و بهینه‌سازی هزینه انجام می‌شود.

4. ارسال به AI: داده‌های نمونه‌برداری شده در قالب یک جدول ساختاریافته به DeepSeek API ارسال می‌شوند با درخواست تحلیل خلاصه.

5. ذخیره‌سازی: پاسخ دریافتی به همراه اطلاعات مصرف توکن در دیتابیس ذخیره می‌شود.

6. بازگشت نتیجه: گزارش تحلیل به کاربر برگردانده می‌شود.

فیلدهای تحلیل شده

API داده‌های زیر را برای تحلیل در نظر می‌گیرد:

• زمان (TimestampUtc) - زمان ثبت داده
• دما (TemperatureC) - دمای محیط به درجه سانتیگراد
• رطوبت (HumidityPercent) - درصد رطوبت هوا
• نور (Lux) - شدت نور به لوکس
• CO (GasPPM) - مقدار گاز CO به PPM

مدیریت توکن

• هر درخواست جدید توکن مصرف می‌کند (معمولاً 800-1500 توکن)
• گزارش‌های cache شده هیچ توکن اضافی مصرف نمی‌کنند
• نمونه‌برداری 1 از 20 رکورد، مصرف توکن را تا 95% کاهش می‌دهد
• اطلاعات دقیق مصرف توکن در فیلد totalTokens برگردانده می‌شود

جدول دیتابیس

گزارش‌ها در جدول DailyReports ذخیره می‌شوند:

CREATE TABLE DailyReports (
    Id INT PRIMARY KEY IDENTITY(1,1),
    DeviceId INT NOT NULL,
    PersianDate NVARCHAR(10) NOT NULL,
    PersianYear INT NOT NULL,
    PersianMonth INT NOT NULL,
    PersianDay INT NOT NULL,
    Analysis NVARCHAR(MAX) NOT NULL,
    RecordCount INT NOT NULL,
    SampledRecordCount INT NOT NULL,
    PromptTokens INT NOT NULL,
    CompletionTokens INT NOT NULL,
    TotalTokens INT NOT NULL,
    Model NVARCHAR(100),
    CreatedAt DATETIME2 NOT NULL,
    ResponseTimeMs BIGINT,
    CONSTRAINT FK_DailyReports_Devices FOREIGN KEY (DeviceId) 
        REFERENCES Devices(Id) ON DELETE CASCADE,
    CONSTRAINT UQ_DailyReports_DeviceDate UNIQUE (DeviceId, PersianDate)
);

نکات مهم

1. یکتایی گزارش: برای هر دستگاه و تاریخ، فقط یک گزارش ذخیره می‌شود (UNIQUE constraint)
2. کش خودکار: سیستم به طور خودکار از گزارش‌های قبلی استفاده می‌کند
3. حذف cascade: با حذف دستگاه، تمام گزارش‌های آن نیز حذف می‌شوند
4. زمان ایران: زمان‌ها در API به timezone ایران (UTC+3:30) تبدیل می‌شوند
5. خطاهای لاگ: تمام خطاها و عملیات در لاگ سیستم ثبت می‌شوند

Migration

برای اعمال تغییرات دیتابیس، migration زیر را اجرا کنید:

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

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