UPDATE

api_changes_last_6_commits_combined.md

@@ -0,0 +1,232 @@
+# گزارش تغییرات API در ۶ کامیت اخیر
+
+این فایل تغییرات مربوط به سه فایل زیر را نسبت به **۶ کامیت قبل** (`HEAD~6`) مستند می‌کند:
+
+- `irrigation_recommendation/urls.py`
+- `fertilization_recommendation/apps.py`
+- `farm_ai_assistant/views.py`
+
+## بازه مقایسه
+- مبدا: `HEAD~6`
+- مقصد: `HEAD`
+
+## نتیجه سریع
+- در `irrigation_recommendation/urls.py`، API آبیاری از مدل دارای endpoint بررسی وضعیت task فاصله گرفته و دو endpoint جدید برای لیست روش‌های آبیاری و water stress اضافه شده است.
+- در `fertilization_recommendation/apps.py`، در این بازه **هیچ تغییری** ثبت نشده است.
+- در `farm_ai_assistant/views.py`، API چت از flow مبتنی بر task/polling به flow مستقیم request/response تغییر کرده و پشتیبانی از `history`، `image_urls` و ورودی‌های multipart/JSON بهتر شده است.
+
+## 1) تغییرات `irrigation_recommendation/urls.py`
+
+### وضعیت قبلی
+مسیرهای زیر وجود داشتند:
+- `config/` -> `ConfigView`
+- `recommend/` -> `RecommendView`
+- `recommend/status/<str:task_id>/` -> `RecommendTaskStatusView`
+
+### وضعیت فعلی
+مسیرهای فعلی:
+- `` -> `IrrigationMethodListView`
+- `config/` -> `ConfigView`
+- `recommend/` -> `RecommendView`
+- `water-stress/` -> `WaterStressView`
+
+### تغییرات دقیق
+#### الف) اضافه شدن endpoint ریشه برای لیست روش‌های آبیاری
+مسیر جدید:
+- `GET irrigation_recommendation/`
+- view: `IrrigationMethodListView`
+- name: `irrigation-method-list`
+
+اثر:
+- حالا این app علاوه بر recommendation، یک endpoint مستقل برای دریافت لیست روش‌های آبیاری هم دارد.
+
+#### ب) حذف endpoint بررسی وضعیت task
+مسیر حذف‌شده:
+- `recommend/status/<str:task_id>/`
+- view: `RecommendTaskStatusView`
+- name: `irrigation-recommendation-task-status`
+
+اثر:
+- دیگر API رسمی‌ای در `urls.py` برای polling وضعیت task recommendation تعریف نشده است.
+- این تغییر از نظر معماری شبیه حذف flow تسک‌محور در بخش AI assistant است.
+
+#### ج) اضافه شدن endpoint جدید water stress
+مسیر جدید:
+- `POST irrigation_recommendation/water-stress/`
+- view: `WaterStressView`
+- name: `irrigation-water-stress`
+
+اثر:
+- یک قابلیت جدید در API آبیاری اضافه شده که به‌صورت جداگانه water stress را محاسبه/برمی‌گرداند.
+
+### چیزهایی که تغییر نکرده‌اند
+- `config/`
+- `recommend/`
+
+## 2) تغییرات `fertilization_recommendation/apps.py`
+
+در بازه `HEAD~6..HEAD` برای این فایل **هیچ diffای وجود ندارد**.
+
+### وضعیت فعلی و قبلی یکسان است
+مقدارهای مهم بدون تغییر مانده‌اند:
+- `default_auto_field = "django.db.models.BigAutoField"`
+- `name = "fertilization_recommendation"`
+- `verbose_name = "Fertilization Recommendation"`
+
+### نتیجه
+- از نظر ثبت app در Django، در این ۶ کامیت اخیر تغییری در `fertilization_recommendation/apps.py` اعمال نشده است.
+- اگر منظورت بررسی APIهای recommendation بوده، این فایل خودش route یا view API ندارد و فقط تنظیمات app را نگه می‌دارد.
+
+## 3) تغییرات `farm_ai_assistant/views.py`
+
+بزرگ‌ترین تغییرات این بازه در این فایل اتفاق افتاده است.
+
+### خلاصه معماری
+API چت از این مدل:
+1. ثبت درخواست چت
+2. ساخت task در سرویس AI
+3. دریافت `task_id`
+4. polling برای status
+
+به این مدل تغییر کرده:
+1. ارسال مستقیم درخواست چت
+2. دریافت مستقیم پاسخ assistant
+3. ذخیره هم‌زمان پیام کاربر و پیام assistant
+
+### تغییرات مهم
+#### الف) حذف flow مبتنی بر task
+کلاس‌های زیر حذف شده‌اند:
+- `ChatTaskCreateView`
+- `ChatTaskStatusView`
+
+رفتار قبلی:
+- `ChatTaskCreateView` درخواست را به endpoint زیر در سرویس بیرونی می‌فرستاد:
+  - `/rag/chat/generate`
+- سپس `ChatTaskStatusView` وضعیت task را از endpoint زیر می‌گرفت:
+  - `/tasks/{task_id}/status`
+
+رفتار جدید:
+- این دو کلاس حذف شده‌اند و flow task-based از این فایل کنار رفته است.
+
+اثر:
+- دیگر پاسخ چت در دو مرحله create/status مدیریت نمی‌شود.
+- polling مبتنی بر `task_id` از منطق این viewها حذف شده است.
+
+#### ب) مستقیم شدن درخواست چت در `ChatView`
+در `ChatView.post`، اکنون درخواست مستقیم به سرویس AI ارسال می‌شود:
+- endpoint جدید آداپتر: `/api/rag/chat/`
+
+این یعنی:
+- به‌جای submit task و پیگیری وضعیت آن، پاسخ assistant در همان request برگردانده می‌شود.
+
+#### ج) تغییر مدل ورودی از `content` به `query`
+در payload ارسالی به adapter، حالا فیلد اصلی متن کاربر این است:
+- `query`
+
+در نسخه قبلی، از `content` برای ساخت payload استفاده می‌شد.
+الان:
+- `content` در منطق اصلی جای خود را به `query` داده است.
+
+اثر:
+- کلاینتی که هنوز payload قدیمی مبتنی بر `content` می‌فرستد، باید با قرارداد جدید view/serializer هماهنگ شود.
+
+#### د) پشتیبانی از `history`
+قابلیت جدید:
+- history پیام‌ها به‌صورت ساختاریافته دریافت، نرمال‌سازی و به adapter ارسال می‌شود.
+
+تغییرات مرتبط:
+- اضافه شدن `_serialize_history_messages`
+- اضافه شدن `_merge_history`
+- اضافه شدن `history` به payload ارسالی به سرویس بیرونی
+
+اثر:
+- API حالا می‌تواند context مکالمه را شفاف‌تر و مستقل از صرفاً conversation id به سرویس AI بفرستد.
+- اگر history در ورودی باشد، استفاده می‌شود؛ در غیر این صورت از پیام‌های conversation برای ساخت history استفاده می‌شود.
+
+#### ه) پشتیبانی از `image_urls` و فایل آپلودی
+قابلیت‌های جدید:
+- `image_urls` به payload اضافه شده است.
+- فایل‌های آپلودشده نیز جمع‌آوری و به payload الصاق می‌شوند.
+
+تغییرات مرتبط:
+- اضافه شدن `_attach_uploaded_files`
+- تبدیل `history` و `image_urls` به JSON string هنگام multipart submission
+- ادغام `image_urls` و `images` در ذخیره پیام کاربر
+
+اثر:
+- API چت حالا هم لینک تصویر و هم فایل تصویر آپلودی را پشتیبانی می‌کند.
+- درخواست‌های multipart برای سناریوهای image-based chat بهتر پشتیبانی می‌شوند.
+
+#### و) مدیریت بهتر JSON و خطای Parse
+قابلیت‌های جدید:
+- import شدن `ParseError`
+- اضافه شدن `_parse_json_array`
+- اضافه شدن `_prepare_chat_input`
+- پاسخ ۴۰۰ اختصاصی برای JSON نامعتبر
+
+رفتار جدید:
+- اگر body نامعتبر باشد، API این پیام را برمی‌گرداند:
+  - invalid JSON / extra trailing characters
+- فیلدهایی مثل `history` و `image_urls` اگر به شکل string JSON بیایند، parse می‌شوند.
+
+اثر:
+- endpoint چت در برابر فرمت‌های مختلف درخواست مقاوم‌تر شده است.
+- احتمال خطا برای کلاینت‌هایی که multipart یا JSON string می‌فرستند کمتر شده است.
+
+#### ز) تغییر در ساخت conversation جدید
+رفتار جدید:
+- عنوان conversation با `_generate_conversation_title(query)` ساخته می‌شود.
+- اگر query خالی باشد، عنوان پیش‌فرض `Image` می‌شود.
+- برای conversation جدید، `farm_context` به‌صورت خالی `{}` ست می‌شود.
+
+رفتار حذف‌شده:
+- دیگر `farm_context` و `title` مستقیماً از payload برای update/create conversation استفاده نمی‌شوند.
+- منطق قبلی که conversation موجود را با `farm_context` یا `title` آپدیت می‌کرد حذف شده است.
+
+اثر:
+- کنترل عنوان مکالمه بیشتر به منطق داخلی view منتقل شده است.
+- payload کلاینت اختیار کمتری روی title/farm_context conversation دارد.
+
+#### ح) بهبود نرمال‌سازی پاسخ assistant
+در نرمال‌سازی sectionها، این کلیدها هم پشتیبانی می‌شوند:
+- `primaryAction`
+- `validityPeriod`
+
+اثر:
+- ساختار response assistant برای UIهای غنی‌تر آماده‌تر شده است.
+
+#### ط) حذف وابستگی به mock chat response
+حذف شده:
+- `CHAT_RESPONSE_DATA`
+- متد `_build_mock_assistant_payload`
+
+اثر:
+- منطق چت بیشتر به پاسخ واقعی adapter متکی شده و از mock response داخلی فاصله گرفته است.
+
+#### ی) logging بیشتر برای دیباگ integration
+موارد جدید:
+- import شدن `logging`
+- تعریف `logger`
+- ثبت log برای response adapter و برخی وضعیت‌های payload parsing/extraction
+
+اثر:
+- عیب‌یابی integration با سرویس AI ساده‌تر شده است.
+
+## جمع‌بندی نهایی
+در این ۶ کامیت اخیر:
+
+- `irrigation_recommendation/urls.py`
+  - endpoint بررسی وضعیت task حذف شده
+  - endpoint ریشه برای لیست روش‌های آبیاری اضافه شده
+  - endpoint جدید `water-stress/` اضافه شده
+
+- `fertilization_recommendation/apps.py`
+  - هیچ تغییری نداشته است
+
+- `farm_ai_assistant/views.py`
+  - flow چت task-based حذف شده
+  - درخواست مستقیم به `/api/rag/chat/` جایگزین شده
+  - پشتیبانی از `history`، `image_urls` و فایل آپلودی اضافه شده
+  - مدیریت JSON/multipart بهتر شده
+  - title conversation از `query` ساخته می‌شود
+  - نرمال‌سازی response assistant گسترش یافته است