Backend/farmer_todos/FARMER_TODOS_API.md

Farmer Todos API

این فایل مستندات کامل APIهای اپ farmer_todos را توضیح می‌دهد.

Base Path

تمام endpointهای این اپ با این prefix در دسترس هستند:

/api/farmer-todos/

Authentication

همه endpointهای این اپ نیاز به احراز هویت دارند.

• Permission: IsAuthenticated
• Authentication: بر اساس تنظیمات DRF پروژه، معمولاً JWT

هدر معمول:

Authorization: Bearer <token>

Overview

در ساختار فعلی پروژه، farmer_todos و farmer_calendar روی یک مدل مشترک سوار هستند، اما این اپ APIهای مخصوص todo را با فرمت مناسب frontend برمی‌گرداند.

موجودیت اصلی:

• FarmerTodoTask

فیلدهای مهم response:

• id: شناسه عمومی task از نوع UUID
• title: عنوان کار
• zone: نام ناحیه یا بخش
• scheduledDate: تاریخ انجام
• time: ساعت انجام
• priority: اولویت
• note: توضیح task
• tags: لیست tagها
• status: وضعیت

Enums

Priority

اولویت‌ها enum-based هستند و از دیتابیس خوانده نمی‌شوند.

مقادیر نهایی ذخیره‌شده:

• زیاد
• متوسط
• کم

ورودی‌های قابل قبول:

• high
• medium
• low
• زیاد
• متوسط
• کم

Tags

tags هم enum-based هستند و از دیتابیس خوانده نمی‌شوند.

نمونه tagهای مجاز:

• آبیاری
• آفت
• فوری
• روزانه
• ثبت دستی
• بازدید
• کوددهی
• سمپاشی
• برداشت

اگر tag خارج از enum ارسال شود، request با validation error رد می‌شود.

Status

مقادیر مجاز:

• open
• done

Endpoints

1) List Tasks

GET /api/farmer-todos/

Query Params

• status: فیلتر بر اساس وضعیت
• priority: فیلتر بر اساس اولویت
• date: فیلتر دقیق روی تاریخ
• from: فیلتر از این تاریخ به بعد
• to: فیلتر تا این تاریخ
• zone: فیلتر بر اساس zone
• search: جستجو در title و note
• farm_uuid: محدود کردن نتایج به یک مزرعه

Behavior

• فقط taskهای متعلق به farmهای کاربر login شده را برمی‌گرداند
• priority ورودی مثل high به مقدار داخلی مثل زیاد normalize می‌شود
• search در title و description مدل جستجو می‌کند
• خروجی بر اساس scheduled_date و time و created_at مرتب می‌شود

Sample Request

GET /api/farmer-todos/?farm_uuid=<farm_uuid>&priority=high&status=open&search=رطوبت

Sample Response

{
  "tasks": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "title": "بررسی رطوبت ردیف شمالی",
      "zone": "قطعه گندم - شمال مزرعه",
      "scheduledDate": "2025-02-24",
      "time": "06:30",
      "priority": "زیاد",
      "note": "اگر رطوبت کمتر از 28٪ بود، آبیاری دوباره بررسی شود.",
      "tags": ["آبیاری"],
      "status": "open"
    }
  ],
  "meta": {
    "total": 1
  }
}

---

2) Create Task

POST /api/farmer-todos/

Request Body

• title: اجباری، string
• zone: اجباری، string
• scheduledDate: اجباری، date با فرمت YYYY-MM-DD
• time: اجباری، time با فرمت HH:MM
• priority: اجباری
• note: اختیاری، string
• tags: اختیاری، array از tagهای enum
• status: اختیاری، open یا done
• farm_uuid: اختیاری، اما اگر کاربر چند farm داشته باشد اجباری می‌شود

Validation Rules

• title نباید خالی باشد
• zone نباید خالی باشد
• priority باید از enum مجاز باشد
• tags باید فقط از enum مجاز باشند
• در create اگر fieldهای اصلی نباشند خطای validation برمی‌گردد

fieldهای اجباری:

• title
• zone
• scheduledDate
• time
• priority

Sample Request

{
  "farm_uuid": "6b7ce8a8-13ec-4a6e-9118-7c298fd2a111",
  "title": "بازدید پمپ جنوب",
  "zone": "انبار مرکزی",
  "scheduledDate": "2025-02-24",
  "time": "07:00",
  "priority": "medium",
  "note": "بعد از ثبت انجام، مورد غیرعادی را یادداشت کن.",
  "tags": ["روزانه", "ثبت دستی"],
  "status": "open"
}

Sample Success Response

{
  "task": {
    "id": "7aa97f9f-bc4c-49f1-858f-11f3f433a111",
    "title": "بازدید پمپ جنوب",
    "zone": "انبار مرکزی",
    "scheduledDate": "2025-02-24",
    "time": "07:00",
    "priority": "متوسط",
    "note": "بعد از ثبت انجام، مورد غیرعادی را یادداشت کن.",
    "tags": ["روزانه", "ثبت دستی"],
    "status": "open"
  }
}

Sample Validation Error

{
  "code": "TASK_VALIDATION_ERROR",
  "message": "priority must be one of زیاد, متوسط, کم, high, medium, low",
  "details": {
    "priority": [
      "priority must be one of زیاد, متوسط, کم, high, medium, low"
    ]
  }
}

---

3) Get Task Detail

GET /api/farmer-todos/<task_uuid>/

Path Param

• task_uuid: شناسه UUID تسک

Behavior

• فقط اگر task متعلق به کاربر باشد برگردانده می‌شود
• اگر وجود نداشته باشد یا متعلق به کاربر دیگری باشد، 404 می‌دهد

Sample Response

{
  "task": {
    "id": "11111111-1111-1111-1111-111111111111",
    "title": "بررسی رطوبت ردیف شمالی",
    "zone": "قطعه گندم - شمال مزرعه",
    "scheduledDate": "2025-02-24",
    "time": "06:30",
    "priority": "زیاد",
    "note": "اگر رطوبت کمتر از 28٪ بود، آبیاری دوباره بررسی شود.",
    "tags": ["آبیاری"],
    "status": "open"
  }
}

Sample Not Found Response

{
  "code": "TASK_NOT_FOUND",
  "message": "Task not found."
}

---

4) Update Task

PUT /api/farmer-todos/<task_uuid>/

Behavior

• این endpoint از partial=True استفاده می‌کند، پس می‌توانی فقط بخشی از فیلدها را بفرستی
• اگر farm_uuid ارسال شود، نباید farm فعلی task را تغییر دهد
• اگر tags ارسال شوند، لیست tagهای task با لیست جدید جایگزین می‌شود
• اگر zone ارسال شود، zone جدید resolve یا ساخته می‌شود

Sample Request

{
  "status": "done"
}

یا:

{
  "priority": "high",
  "tags": ["فوری", "بازدید"],
  "note": "این کار باید امروز نهایی شود."
}

Sample Response

{
  "task": {
    "id": "11111111-1111-1111-1111-111111111111",
    "title": "بررسی رطوبت ردیف شمالی",
    "zone": "قطعه گندم - شمال مزرعه",
    "scheduledDate": "2025-02-24",
    "time": "06:30",
    "priority": "زیاد",
    "note": "اگر رطوبت کمتر از 28٪ بود، آبیاری دوباره بررسی شود.",
    "tags": ["آبیاری"],
    "status": "done"
  }
}

---

5) Delete Task

DELETE /api/farmer-todos/<task_uuid>/

Sample Response

{
  "success": true
}

---

6) List Zones

GET /api/farmer-todos/zones/

Query Params

• farm_uuid: اختیاری

Behavior

• zoneها از دیتابیس خوانده می‌شوند
• اگر farm_uuid ارسال شود، zoneها به همان farm محدود می‌شوند
• اگر farm_uuid ارسال نشود، zoneهای تکراری بین farmهای کاربر deduplicate می‌شوند

Sample Response

{
  "zones": [
    {
      "id": "zone_gndm-shmal-mzrh",
      "label": "قطعه گندم - شمال مزرعه",
      "value": "قطعه گندم - شمال مزرعه"
    }
  ],
  "meta": {
    "total": 1
  }
}

---

7) List Tags

GET /api/farmer-todos/tags/

Query Params

• farm_uuid: اختیاری؛ در نسخه فعلی فقط validate می‌شود

Behavior

• tagها از enum داخلی کد برمی‌گردند
• این endpoint دیگر از جدول tag چیزی نمی‌خواند

Sample Response

{
  "tags": [
    {
      "id": "tag_irrigation",
      "label": "آبیاری",
      "value": "آبیاری"
    },
    {
      "id": "tag_pest",
      "label": "آفت",
      "value": "آفت"
    },
    {
      "id": "tag_urgent",
      "label": "فوری",
      "value": "فوری"
    }
  ],
  "meta": {
    "total": 9
  }
}

---

8) Summary

GET /api/farmer-todos/summary/

Query Params

• farm_uuid: اختیاری

Response Fields

• todayTasksCount: تعداد taskهای امروز
• completedCount: تعداد taskهای انجام‌شده
• urgentCount: تعداد taskهای باز با priority بالا
• progressValue: درصد پیشرفت
• nextTask: نزدیک‌ترین task باز

Behavior

• progressValue از نسبت completedCount / totalCount محاسبه می‌شود
• nextTask اولین task باز از امروز به بعد است

Sample Response

{
  "todayTasksCount": 2,
  "completedCount": 1,
  "urgentCount": 2,
  "progressValue": 50,
  "nextTask": {
    "id": "11111111-1111-1111-1111-111111111111",
    "title": "بررسی رطوبت ردیف شمالی",
    "zone": "قطعه گندم - شمال مزرعه",
    "scheduledDate": "2025-02-24",
    "time": "06:30",
    "priority": "زیاد",
    "note": "اگر رطوبت کمتر از 28٪ بود، آبیاری دوباره بررسی شود.",
    "tags": ["آبیاری"],
    "status": "open"
  }
}

Error Format

خطاهای validation:

{
  "code": "TASK_VALIDATION_ERROR",
  "message": "error message",
  "details": {}
}

خطای پیدا نشدن:

{
  "code": "TASK_NOT_FOUND",
  "message": "Task not found."
}

Farm Resolution Rules

رفتار farm_uuid:

• اگر کاربر فقط یک farm داشته باشد، در create می‌تواند farm_uuid نفرستد
• اگر کاربر چند farm داشته باشد، در create باید farm_uuid بفرستد
• اگر farm_uuid نامعتبر باشد، validation error برمی‌گردد
• در update، farm_uuid نباید farm task را تغییر دهد

Notes

• فایل routeها: farmer_todos/urls.py
• فایل viewها: farmer_todos/views.py
• فایل serializerها: farmer_todos/serializers.py
• enumهای مشترک: farmer_calendar/enums.py

Related Note

در ساختار فعلی پروژه، farmer_todos از مدل مشترک با farmer_calendar استفاده می‌کند، ولی response و endpointهای این فایل مخصوص todo هستند.