Backend/api_changes_last_6_commits_combined.md

گزارش تغییرات 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 گسترش یافته است