sajad-dev/Backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
72588fe12c96efd84bed6ba9f877916d452d4534
Backend/LANDING_PAGE_FARM_AI_ASSISTANT_API.md
T
sajad-dev 72588fe12c UPDATE
2026-04-23 15:53:59 +03:30

15 KiB
Raw Blame History

راهنمای اتصال Landing Page به Farm AI Assistant و Auth API

این فایل برای تیم فرانت/لندینگ نوشته شده تا بتوانند از داخل Docker Network به بک‌اند وصل شوند و APIهای احراز هویت و Farm AI Assistant را مصرف کنند.

1) اتصال از طریق Docker Network

بک‌اند در docker-compose.yaml روی network خارجی crop_network اجرا می‌شود و سرویس وب آن:

  • service name: web
  • container name: backend-web
  • internal port: 8000

نکته مهم

اگر فرانت هم داخل Docker اجرا می‌شود، از داخل کانتینر نباید از localhost:8000 استفاده کنید، چون localhost به همان کانتینر فرانت اشاره می‌کند، نه به بک‌اند.

آدرس پیشنهادی برای اتصال داخل Docker Network

http://backend-web:8000

در بسیاری از موارد http://web:8000 هم کار می‌کند، اما چون container_name به‌صورت صریح backend-web تعریف شده، برای اتصال بین دو سرویس روی crop_network بهتر است از همین آدرس استفاده شود.

اگر network هنوز ساخته نشده است

docker network create crop_network

نمونه اتصال سرویس فرانت به همان network

services:
  landing:
    build: .
    container_name: landing-web
    environment:
      BACKEND_BASE_URL: http://backend-web:8000
    networks:
      - crop_network

networks:
  crop_network:
    external: true

پیشنهاد برای env فرانت

BACKEND_BASE_URL=http://backend-web:8000

اگر درخواست از خود مرورگر کاربر ارسال می‌شود

اگر فرانت در مرورگر API را مستقیم صدا می‌زند، معمولاً باید از آدرس host-mapped استفاده کنید:

http://localhost:8000

اما اگر درخواست از سمت سرور فرانت/SSR/Nuxt/Next داخل کانتینر ارسال می‌شود، از این آدرس استفاده کنید:

http://backend-web:8000

2) Base URL

برای ارتباط container-to-container

http://backend-web:8000

Prefixهای موردنیاز

  • Auth: /api/auth/
  • Farm AI Assistant: /api/farm-ai-assistant/

3) جریان کلی برای Landing Page

برای چت landing page، ارسال farm_uuid الزامی نیست.

یعنی اگر کاربر داخل landing page پیام بدهد:

  • فقط کافی است کاربر لاگین باشد
  • farm_uuid را ارسال نکنید
  • سیستم conversation را به‌صورت landing conversation با farm = null ذخیره می‌کند
  • در responseها معمولاً farm_uuid برابر null خواهد بود

فلو پیشنهادی

  1. کاربر با register یا login توکن بگیرد.
  2. توکن را در هدر Authorization: Bearer <token> بفرستید.
  3. برای شروع چت landing از POST /api/farm-ai-assistant/chat/task/ بدون farm_uuid استفاده کنید.
  4. task_id و conversation_id را از پاسخ نگه دارید.
  5. با GET /api/farm-ai-assistant/chat/task/{task_id}/status/ وضعیت را poll کنید.
  6. برای history از GET /api/farm-ai-assistant/chats/{conversation_id}/messages/ استفاده کنید.
  7. برای لیست چت‌های landing از GET /api/farm-ai-assistant/chats/ بدون farm_uuid استفاده کنید.

4) Authentication APIs

4.1) Register

  • Method: POST
  • URL: /api/auth/register/
  • Auth: نیاز ندارد

Request

{
  "username": "landing_user",
  "email": "landing@example.com",
  "phone_number": "09120000000",
  "password": "secret123",
  "first_name": "Landing",
  "last_name": "User"
}

Response 201

{
  "code": 201,
  "msg": "success",
  "data": {
    "id": 1,
    "username": "landing_user",
    "email": "landing@example.com",
    "first_name": "Landing",
    "last_name": "User",
    "phone_number": "09120000000"
  },
  "token": "<access_token>"
}

خطاهای رایج

  • 400: username تکراری
  • 400: email تکراری
  • 400: phone_number تکراری

4.2) Login

  • Method: POST
  • URL: /api/auth/login/
  • Auth: نیاز ندارد

Request

identifier می‌تواند username یا email یا phone_number باشد.

{
  "identifier": "landing_user",
  "password": "secret123"
}

Response 200

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "username": "landing_user",
    "email": "landing@example.com",
    "first_name": "Landing",
    "last_name": "User",
    "phone_number": "09120000000"
  },
  "token": "<access_token>"
}

خطای رایج

{
  "code": 401,
  "msg": "Invalid credentials."
}

5) هدر احراز هویت برای Farm AI Assistant

تمام endpointهای Farm AI Assistant نیاز به لاگین دارند:

Authorization: Bearer <access_token>
Content-Type: application/json

6) Farm AI Assistant APIs

6.1) ارسال پیام و ساخت task

  • Method: POST
  • URL: /api/farm-ai-assistant/chat/task/
  • Auth: لازم است
  • برای landing page: farm_uuid را ارسال نکنید

Request نمونه برای landing

{
  "content": "برای شروع کشاورزی چه محصولی مناسب‌تر است؟",
  "images": [],
  "title": "Landing chat",
  "farm_context": {
    "source": "landing",
    "page": "home"
  }
}

Request با ادامه conversation قبلی

{
  "conversation_id": "4b9f4d2f-2e5f-4f7a-ae24-6e7fd9c3e0f1",
  "content": "برای منطقه کم‌آب چه پیشنهادی داری؟",
  "images": []
}

فیلدها

فیلد نوع اجباری توضیح
farm_uuid uuid خیر برای landing ارسال نشود
content string اختیاری* متن پیام
images string[] اختیاری لیست URL/base64/path
conversation_id uuid اختیاری ادامه چت قبلی
title string اختیاری عنوان چت جدید
farm_context object اختیاری context اضافی UI

* حداقل یکی از content یا images باید ارسال شود.

Response 202

{
  "status": "success",
  "data": {
    "task_id": "farm-ai-chat-task-123",
    "status": "PENDING",
    "status_url": "/api/tasks/farm-ai-chat-task-123/status/",
    "conversation_id": "4b9f4d2f-2e5f-4f7a-ae24-6e7fd9c3e0f1",
    "message_id": "5d3f7a8c-9f2e-4d0a-b56f-1f2c2f9c1a22",
    "farm_uuid": null
  }
}

خطاهای رایج

  • 400: اگر نه content باشد نه images
  • 404: اگر conversation_id متعلق به کاربر نباشد
  • 503: اگر سرویس خارجی AI در دسترس نباشد

6.2) بررسی وضعیت task

  • Method: GET
  • URL: /api/farm-ai-assistant/chat/task/{task_id}/status/
  • Auth: لازم است
  • برای landing page: بدون farm_uuid

Request

GET /api/farm-ai-assistant/chat/task/farm-ai-chat-task-123/status/
Authorization: Bearer <access_token>

Response در حالت pending

{
  "status": "success",
  "data": {
    "task_id": "farm-ai-chat-task-123",
    "status": "PENDING",
    "conversation_id": "4b9f4d2f-2e5f-4f7a-ae24-6e7fd9c3e0f1",
    "farm_uuid": null,
    "progress": {
      "message": "Processing request"
    }
  }
}

Response در حالت success

{
  "status": "success",
  "data": {
    "task_id": "farm-ai-chat-task-123",
    "status": "SUCCESS",
    "conversation_id": "4b9f4d2f-2e5f-4f7a-ae24-6e7fd9c3e0f1",
    "farm_uuid": null,
    "result": {
      "message_id": "9f3f8f61-cc71-4f70-a650-2f4dc6f4e5c2",
      "conversation_id": "4b9f4d2f-2e5f-4f7a-ae24-6e7fd9c3e0f1",
      "farm_uuid": null,
      "task_id": "farm-ai-chat-task-123",
      "content": "Here is the recommended plan.",
      "sections": [
        {
          "type": "recommendation",
          "title": "Irrigation Plan",
          "icon": "droplet",
          "frequency": "3 times per week",
          "amount": "15 liters per plant",
          "timing": "Early morning",
          "expandableExplanation": "Loamy soil holds moisture well, so moderate frequency is enough."
        }
      ]
    }
  }
}

Response در حالت failure

{
  "status": "success",
  "data": {
    "task_id": "farm-ai-chat-task-123",
    "status": "FAILURE",
    "conversation_id": "4b9f4d2f-2e5f-4f7a-ae24-6e7fd9c3e0f1",
    "farm_uuid": null,
    "error": "something went wrong"
  }
}

پیشنهاد برای polling

  • هر 2 تا 3 ثانیه یک بار status را چک کنید
  • وقتی status برابر SUCCESS یا FAILURE شد polling را متوقف کنید

6.3) دریافت لیست chatها

  • Method: GET
  • URL: /api/farm-ai-assistant/chats/
  • Auth: لازم است
  • برای landing page: بدون farm_uuid

رفتار

اگر farm_uuid ارسال نشود:

  • فقط conversationهای landing همان کاربر برمی‌گردند
  • یعنی فقط رکوردهایی که مزرعه ندارند

Request

GET /api/farm-ai-assistant/chats/
Authorization: Bearer <access_token>

Response 200

{
  "status": "success",
  "data": [
    {
      "id": "4b9f4d2f-2e5f-4f7a-ae24-6e7fd9c3e0f1",
      "farm_uuid": null,
      "message_count": 4
    }
  ]
}

6.4) ساخت conversation خالی

  • Method: POST
  • URL: /api/farm-ai-assistant/chats/
  • Auth: لازم است
  • برای landing page: بدون farm_uuid

Request

{
  "title": "مشاوره اولیه",
  "farm_context": {
    "source": "landing"
  }
}

Response 201

{
  "status": "success",
  "data": {
    "id": "4b9f4d2f-2e5f-4f7a-ae24-6e7fd9c3e0f1",
    "farm_uuid": null,
    "message_count": 0
  }
}

6.5) حذف conversation

  • Method: DELETE
  • URL: /api/farm-ai-assistant/chats/{conversation_id}/
  • Auth: لازم است
  • برای landing page: بدون farm_uuid

رفتار

اگر farm_uuid نفرستید، فقط conversationهای landing همان کاربر قابل حذف هستند.

Request

DELETE /api/farm-ai-assistant/chats/4b9f4d2f-2e5f-4f7a-ae24-6e7fd9c3e0f1/
Authorization: Bearer <access_token>

Response 200

{
  "status": "success",
  "data": {
    "conversation_id": "4b9f4d2f-2e5f-4f7a-ae24-6e7fd9c3e0f1",
    "farm_uuid": null
  }
}

6.6) دریافت پیام‌های یک conversation

  • Method: GET
  • URL: /api/farm-ai-assistant/chats/{conversation_id}/messages/
  • Auth: لازم است
  • برای landing page: بدون farm_uuid

رفتار

اگر farm_uuid ارسال نشود، فقط conversationهای landing همان کاربر لود می‌شوند.

Request

GET /api/farm-ai-assistant/chats/4b9f4d2f-2e5f-4f7a-ae24-6e7fd9c3e0f1/messages/
Authorization: Bearer <access_token>

Response 200

{
  "status": "success",
  "data": {
    "conversation_id": "4b9f4d2f-2e5f-4f7a-ae24-6e7fd9c3e0f1",
    "farm_uuid": null,
    "messages": [
      {
        "message_id": "11111111-1111-1111-1111-111111111111",
        "conversation_id": "4b9f4d2f-2e5f-4f7a-ae24-6e7fd9c3e0f1",
        "farm_uuid": null,
        "role": "user",
        "content": "برای شروع کشاورزی چه چیزی پیشنهاد می‌کنی؟",
        "sections": [],
        "images": [],
        "created_at": "2025-03-27T12:00:00Z"
      },
      {
        "message_id": "22222222-2222-2222-2222-222222222222",
        "conversation_id": "4b9f4d2f-2e5f-4f7a-ae24-6e7fd9c3e0f1",
        "farm_uuid": null,
        "role": "assistant",
        "content": "Here is the recommended plan.",
        "sections": [
          {
            "type": "list",
            "title": "Important Notes",
            "items": [
              "Avoid watering at noon",
              "Check leaf stress every two days"
            ]
          }
        ],
        "images": [],
        "created_at": "2025-03-27T12:00:05Z"
      }
    ]
  }
}

7) مثال کامل فرانت برای Landing Chat

7.1) Register

curl -X POST 'http://backend-web:8000/api/auth/register/' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "landing_user",
    "email": "landing@example.com",
    "phone_number": "09120000000",
    "password": "secret123",
    "first_name": "Landing",
    "last_name": "User"
  }'

7.2) Login

curl -X POST 'http://backend-web:8000/api/auth/login/' \
  -H 'Content-Type: application/json' \
  -d '{
    "identifier": "landing_user",
    "password": "secret123"
  }'

7.3) Create task

curl -X POST 'http://backend-web:8000/api/farm-ai-assistant/chat/task/' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "برای شروع کشاورزی چه محصولی مناسب است؟",
    "farm_context": {
      "source": "landing",
      "page": "home"
    }
  }'

7.4) Poll task status

curl -X GET 'http://backend-web:8000/api/farm-ai-assistant/chat/task/farm-ai-chat-task-123/status/' \
  -H 'Authorization: Bearer <token>'

7.5) Get chat list

curl -X GET 'http://backend-web:8000/api/farm-ai-assistant/chats/' \
  -H 'Authorization: Bearer <token>'

7.6) Get messages

curl -X GET 'http://backend-web:8000/api/farm-ai-assistant/chats/4b9f4d2f-2e5f-4f7a-ae24-6e7fd9c3e0f1/messages/' \
  -H 'Authorization: Bearer <token>'

7.7) Delete conversation

curl -X DELETE 'http://backend-web:8000/api/farm-ai-assistant/chats/4b9f4d2f-2e5f-4f7a-ae24-6e7fd9c3e0f1/' \
  -H 'Authorization: Bearer <token>'

8) رفتار farm_uuid در Landing Page

برای endpointهای زیر در landing page لازم نیست farm_uuid ارسال شود:

  • POST /api/farm-ai-assistant/chat/task/
  • GET /api/farm-ai-assistant/chat/task/{task_id}/status/
  • GET /api/farm-ai-assistant/chats/
  • POST /api/farm-ai-assistant/chats/
  • DELETE /api/farm-ai-assistant/chats/{conversation_id}/
  • GET /api/farm-ai-assistant/chats/{conversation_id}/messages/

نتیجه این رفتار

  • چت به کاربر وابسته است
  • چت به مزرعه خاصی وابسته نیست
  • در response مقدار farm_uuid معمولاً null است

9) چیزی که فرانت باید نگه دارد

بعد از login این موارد را در state یا storage نگه دارید:

  • token
  • user

بعد از POST /chat/task/ این موارد را نگه دارید:

  • conversation_id
  • task_id
  • message_id

برای ادامه chat:

  • conversation_id را در درخواست بعدی دوباره بفرستید

10) نکات نهایی

  • تمام APIهای Farm AI Assistant به توکن نیاز دارند.
  • برای landing page، farm_uuid را نفرستید.
  • اگر فرانت داخل Docker است، آدرس بک‌اند را http://backend-web:8000 بگذارید.
  • اگر فرانت از داخل browser مستقیم درخواست می‌زند، معمولاً http://localhost:8000 لازم است.
  • localhost داخل کانتینر فرانت، آدرس بک‌اند نیست.
Reference in New Issue View Git Blame Copy Permalink