version 2

src/DAILY_REPORT_API.md

@@ -0,0 +1,145 @@
+# API گزارش تحلیل روزانه گلخانه
+
+این API برای دریافت تحلیل هوشمصنوعی روزانه از داده‌های تلمتری گلخانه طراحی شده است.
+
+## اندپوینت
+
+```
+GET /api/DailyReport
+```
+
+## پارامترها
+
+| پارامتر | نوع | الزامی | توضیحات |
+|---------|-----|--------|----------|
+| `deviceId` | int | بله | شناسه دستگاه |
+| `persianDate` | string | بله | تاریخ شمسی به فرمت `yyyy/MM/dd` (مثال: `1403/09/26`) |
+
+## مثال درخواست
+
+```http
+GET /api/DailyReport?deviceId=1&persianDate=1403/09/26
+```
+
+## پاسخ موفق (200 OK)
+
+```json
+{
+  "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
+درخواست نامعتبر (شناسه دستگاه یا فرمت تاریخ اشتباه)
+
+```json
+{
+  "error": "تاریخ شمسی باید به فرمت yyyy/MM/dd باشد"
+}
+```
+
+### 404 Not Found
+دستگاه یا داده‌ای برای تاریخ مورد نظر یافت نشد
+
+```json
+{
+  "error": "هیچ رکوردی برای دستگاه 1 در تاریخ 1403/09/26 یافت نشد"
+}
+```
+
+### 500 Internal Server Error
+خطای سرور (مثلاً خطا در ارتباط با DeepSeek API)
+
+```json
+{
+  "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` ذخیره می‌شوند:
+
+```sql
+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 زیر را اجرا کنید:
+
+```bash
+dotnet ef database update --project GreenHome.Infrastructure --startup-project GreenHome.Api
+```
+
+یا به صورت خودکار در startup برنامه اعمال می‌شود.
+