Logic/Modules/Backend/crop_zoning/CROP_ZONING_FRONTEND_API.md

Crop Zoning API Guide For Frontend

این فایل برای تیم فرانت نوشته شده و رفتار endpointهای ماژول crop-zoning را به صورت کاربردی توضیح می‌دهد.

Base Path

/api/crop-zoning/

Authentication

• همه endpointها با تنظیم فعلی پروژه نیاز به احراز هویت دارند.
• هدر پیشنهادی:

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

Flow پیشنهادی فرانت

1. ابتدا GET /area/ را با farm_uuid صدا بزنید.
2. اگر task.status برابر PENDING یا PROCESSING بود، polling انجام دهید.
3. وقتی task.status برابر SUCCESS شد:
   • area را برای polygon اصلی زمین استفاده کنید.
   • zones را برای grid map و کارت‌های overview استفاده کنید.
4. برای legend محصولات، GET /products/ را بزنید.

وضعیت‌های Task

• IDLE: هنوز area/taskی برای مزرعه وجود ندارد.
• PENDING: تسک ساخته شده ولی پردازش هنوز شروع نشده یا در صف است.
• PROCESSING: بخشی از زون‌ها در حال پردازش هستند یا برخی کامل شده‌اند.
• SUCCESS: همه زون‌ها کامل پردازش شده‌اند.
• FAILURE: یک یا چند زون با خطا مواجه شده‌اند.

Stageهای Task

• waiting_to_start
• queued
• processing_zones
• continuing_processing
• completed
• failed

فیلد stage_label متن فارسی آماده برای نمایش در UI است.

---

1) Get Area

GET /api/crop-zoning/area/?farm_uuid=<farm_uuid>&page=1&page_size=10

Query Params

• farm_uuid: اجباری، UUID مزرعه
• page: اختیاری، شماره صفحه زون‌ها. پیش‌فرض 1
• page_size: اختیاری، تعداد زون در هر صفحه. پیش‌فرض 10

کاربرد

• گرفتن آخرین area مربوط به مزرعه
• ساخت area و zoneها در صورت نبود داده
• دریافت وضعیت task
• دریافت لیست zones به صورت صفحه‌بندی‌شده برای نمایش روی نقشه
• دریافت اطلاعات pagination برای ساخت pager یا infinite loading در فرانت

نمونه پاسخ موفق

{
  "status": "success",
  "data": {
    "task": {
      "status": "SUCCESS",
      "stage": "completed",
      "stage_label": "پردازش همه زون‌ها کامل شده است",
      "area_uuid": "c0eaa4d7-92bf-4542-a60d-6010b45e7c96",
      "total_zones": 364,
      "completed_zones": 364,
      "processing_zones": 0,
      "pending_zones": 0,
      "failed_zones": 0,
      "remaining_zones": 0,
      "progress_percent": 100,
      "summary": {
        "done": 364,
        "in_progress": 0,
        "remaining": 0,
        "failed": 0
      },
      "message": "از مجموع 364 زون، 364 زون پردازش شده، 0 زون در حال پردازش و 0 زون باقی مانده است.",
      "failed_zone_errors": [],
      "cell_side_km": 0.1
    },
    "area": {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[51.418934, 35.706815], [51.423054, 35.691062], [51.384258, 35.689389], [51.418934, 35.706815]]]
      },
      "properties": {
        "center": {
          "latitude": 35.69575533,
          "longitude": 51.40874867
        },
        "area_sqm": 3109868.97,
        "cell_side_km": 0.1,
        "area_hectares": 310.9869
      }
    },
    "zones": [
      {
        "zoneId": "zone-0",
        "zoneUuid": "d7a9a19b-b3ec-4721-b514-9aae5c9ea940",
        "geometry": {
          "type": "Polygon",
          "coordinates": [[[51.384258, 35.689389], [51.38536404, 35.689389], [51.38536404, 35.69028731], [51.384258, 35.69028731], [51.384258, 35.689389]]]
        },
        "center": {
          "latitude": 35.68983816,
          "longitude": 51.38481102
        },
        "area_sqm": 9999.91,
        "area_hectares": 1,
        "sequence": 0,
        "processing_status": "completed",
        "processing_error": "",
        "crop": "wheat",
        "matchPercent": 89,
        "waterNeed": "4820-5820 m³/ha",
        "estimatedProfit": "۱۵-۲۵ میلیون/هکتار",
        "waterNeedLayer": {
          "level": "medium",
          "value": "4820-5820 m³/ha",
          "color": "#0ea5e9"
        },
        "soilQualityLayer": {
          "level": "high",
          "score": 89,
          "color": "#22c55e"
        },
        "cultivationRiskLayer": {
          "level": "low",
          "color": "#22c55e"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 10,
      "total_pages": 37,
      "total_zones": 364,
      "returned_zones": 10,
      "has_next": true,
      "has_previous": false
    }
  }
}

رفتار pagination

• zones فقط شامل زون‌های همان صفحه‌ای است که در query param فرستاده شده
• task.total_zones تعداد کل زون‌های area را نشان می‌دهد، نه فقط زون‌های همان صفحه
• pagination.total_pages تعداد کل صفحه‌ها را برای فرانت مشخص می‌کند
• pagination.returned_zones تعداد آیتم‌های برگشتی در همان response را نشان می‌دهد
• اگر page بزرگ‌تر از total_pages باشد، response خطا نمی‌دهد و فقط zones خالی برمی‌گردد

مثال‌ها

صفحه اول با 10 زون در هر صفحه

GET /api/crop-zoning/area/?farm_uuid=<farm_uuid>&page=1&page_size=10

صفحه سوم با 25 زون در هر صفحه

GET /api/crop-zoning/area/?farm_uuid=<farm_uuid>&page=3&page_size=25

فیلدهای مهم zones

• zoneId: شناسه نمایشی زون، مثل zone-0
• zoneUuid: UUID داخلی زون
• geometry: polygon زون
• center: مرکز زون
• area_sqm: مساحت به متر مربع
• area_hectares: مساحت به هکتار
• sequence: ترتیب زون
• processing_status: یکی از pending, processing, completed, failed
• processing_error: متن خطا در صورت failure
• crop: محصول پیشنهادی
• matchPercent: درصد تطابق
• waterNeed: نیاز آبی پیشنهادی
• estimatedProfit: سود تخمینی
• waterNeedLayer: داده layer نیاز آبی
• soilQualityLayer: داده layer کیفیت خاک
• cultivationRiskLayer: داده layer ریسک کشت

فیلدهای مهم pagination

• page: شماره صفحه فعلی
• page_size: تعداد زون در هر صفحه
• total_pages: تعداد کل صفحه‌ها
• total_zones: تعداد کل زون‌های area
• returned_zones: تعداد زون‌های برگشتی در response فعلی
• has_next: آیا صفحه بعدی وجود دارد یا نه
• has_previous: آیا صفحه قبلی وجود دارد یا نه

خطاها

وقتی farm_uuid ارسال نشود

{
  "status": "error",
  "message": "farm_uuid is required."
}

وقتی مزرعه پیدا نشود

{
  "status": "error",
  "message": "Farm not found."
}

وقتی page یا page_size نامعتبر باشد

{
  "status": "error",
  "message": "page must be a positive integer."
}

• همین رفتار برای page_size هم وجود دارد و پیام خطا به صورت page_size must be a positive integer. برمی‌گردد.

---

2) Get Products

GET /api/crop-zoning/products/

کاربرد

• گرفتن لیست محصولات برای legend و labelها

نمونه پاسخ

{
  "status": "success",
  "data": {
    "products": [
      {
        "id": "wheat",
        "label": "گندم",
        "color": "#6bcb77"
      },
      {
        "id": "canola",
        "label": "کلزا",
        "color": "#ffd93d"
      },
      {
        "id": "saffron",
        "label": "زعفران",
        "color": "#9b59b6"
      }
    ]
  }
}