Backend/farmer_calendar/FARMER_CALENDAR_API.md

Farmer Calendar API

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

Base Path

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

/api/events/

Authentication

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

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

هدر معمول:

Authorization: Bearer <token>

Data Model

موجودیت اصلی در این اپ FarmerCalendarEvent است.

فیلدهای مهم:

• id: شناسه عمومی event از نوع UUID
• title: عنوان event
• description: توضیحات
• deadline: مهلت به صورت timestamp عددی
• start: زمان شروع event
• end: زمان پایان event
• extendedProps: داده‌های اضافه به صورت object
• tags: لیست tagها

Tag Rules

در نسخه فعلی، tags از دیتابیس خوانده نمی‌شوند و فقط از enum داخلی پروژه مجاز هستند.

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

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

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

Priority

در مدل مشترک event/todo، اولویت به صورت enum تعریف شده است.

مقادیر مجاز:

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

یا در بعضی serializerهای مرتبط، ورودی انگلیسی:

• high
• medium
• low

Endpoints

1) List Events

GET /api/events/

Query Params

• start: فیلتر از این datetime به بعد
• end: فیلتر تا این datetime
• farm_uuid: اگر کاربر چند مزرعه داشته باشد، برای محدود کردن نتایج به یک مزرعه

Behavior

• فقط eventهای متعلق به farmهای کاربر login شده را برمی‌گرداند
• اگر start ارسال شود، eventهایی برمی‌گردند که end >= start
• اگر end ارسال شود، eventهایی برمی‌گردند که start <= end
• خروجی بر اساس start و بعد created_at مرتب می‌شود

Sample Request

GET /api/events/?farm_uuid=<farm_uuid>&start=2025-02-24T00:00:00Z&end=2025-02-25T00:00:00Z

Sample Response

{
  "events": [
    {
      "id": "4be7c204-6fd8-4aa4-a5f4-7f0e9ceaa111",
      "title": "آبیاری بلوک شمالی",
      "description": "کنترل فشار و مدت زمان آبیاری",
      "deadline": 1734942600,
      "tags": ["آبیاری", "فوری"],
      "start": "2025-02-24T06:30:00Z",
      "end": "2025-02-24T08:00:00Z",
      "extendedProps": {
        "source": "manual"
      }
    }
  ],
  "meta": {
    "total": 1
  }
}

---

2) Create Event

POST /api/events/

Request Body

• title: اجباری، string
• description: اختیاری، string
• deadline: اختیاری، integer
• tags: اختیاری، array از tagهای enum
• start: اجباری، datetime
• end: اجباری، datetime
• extendedProps: اختیاری، object
• farm_uuid: اختیاری، اما اگر کاربر چند farm داشته باشد اجباری می‌شود

Validation Rules

• title نباید خالی باشد
• extendedProps باید object باشد
• end نباید از start کوچک‌تر باشد
• tags فقط باید از enum مجاز باشند
• اگر کاربر چند farm داشته باشد و farm_uuid نفرستد، خطا برمی‌گردد

Sample Request

{
  "farm_uuid": "6b7ce8a8-13ec-4a6e-9118-7c298fd2a111",
  "title": "بازدید آفت در گلخانه",
  "description": "بررسی وضعیت برگ ها و ثبت گزارش",
  "deadline": 1734971400,
  "tags": ["آفت", "فوری"],
  "start": "2025-02-24T14:00:00Z",
  "end": "2025-02-24T15:00:00Z",
  "extendedProps": {
    "source": "manual"
  }
}

Sample Success Response

{
  "event": {
    "id": "7aa97f9f-bc4c-49f1-858f-11f3f433a111",
    "title": "بازدید آفت در گلخانه",
    "description": "بررسی وضعیت برگ ها و ثبت گزارش",
    "deadline": 1734971400,
    "tags": ["آفت", "فوری"],
    "start": "2025-02-24T14:00:00Z",
    "end": "2025-02-24T15:00:00Z",
    "extendedProps": {
      "source": "manual"
    }
  }
}

Sample Validation Error

{
  "code": "EVENT_VALIDATION_ERROR",
  "message": "title cannot be empty",
  "details": {
    "title": ["title cannot be empty"]
  }
}

---

3) Get Event Detail

GET /api/events/<event_uuid>/

Path Param

• event_uuid: شناسه UUID رویداد

Behavior

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

Sample Response

{
  "event": {
    "id": "4be7c204-6fd8-4aa4-a5f4-7f0e9ceaa111",
    "title": "آبیاری بلوک شمالی",
    "description": "کنترل فشار و مدت زمان آبیاری",
    "deadline": 1734942600,
    "tags": ["آبیاری"],
    "start": "2025-02-24T06:30:00Z",
    "end": "2025-02-24T08:00:00Z",
    "extendedProps": {}
  }
}

Sample Not Found Response

{
  "code": "EVENT_NOT_FOUND",
  "message": "Event not found."
}

---

4) Update Event

PUT /api/events/<event_uuid>/

Request Body

ساختار body مثل create است.

Important Notes

• این endpoint در حال حاضر update کامل انجام می‌دهد، نه partial
• اگر farm_uuid ارسال شود، نباید با farm فعلی event فرق داشته باشد
• اگر tags ارسال شوند، tagهای قبلی با همان لیست جدید جایگزین می‌شوند

Sample Request

{
  "title": "آبیاری بلوک شمالی",
  "description": "اولویت بالا",
  "deadline": 1734942600,
  "tags": ["آبیاری", "فوری"],
  "start": "2025-02-24T15:00:00Z",
  "end": "2025-02-24T16:00:00Z",
  "extendedProps": {}
}

Sample Response

{
  "event": {
    "id": "4be7c204-6fd8-4aa4-a5f4-7f0e9ceaa111",
    "title": "آبیاری بلوک شمالی",
    "description": "اولویت بالا",
    "deadline": 1734942600,
    "tags": ["آبیاری", "فوری"],
    "start": "2025-02-24T15:00:00Z",
    "end": "2025-02-24T16:00:00Z",
    "extendedProps": {}
  }
}

---

5) Delete Event

DELETE /api/events/<event_uuid>/

Sample Response

{
  "success": true
}

---

6) List Available Tags

GET /api/events/tags/

Query Params

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

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
  }
}

Error Format

فرمت خطاهای validation به این شکل است:

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

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

{
  "code": "EVENT_NOT_FOUND",
  "message": "Event not found."
}

Farm Resolution Rules

رفتار farm_uuid در این اپ:

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

Implementation Notes

• فایل routeها: farmer_calendar/urls.py
• فایل viewها: farmer_calendar/views.py
• فایل serializerها: farmer_calendar/serializers.py
• enumهای tag و priority: farmer_calendar/enums.py

Related Note

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