Backend/docs/location_data_frontend_api_reference_fa.md

راهنمای فرانت برای API های Location Data

این فایل برای تیم فرانت نوشته شده تا بتواند API های Location Data را سریع و دقیق مصرف کند.

مسیرهای اصلی:

• GET /api/location-data/
• POST /api/location-data/
• POST /api/location-data/ndvi-health/
• GET /api/location-data/remote-sensing/
• POST /api/location-data/remote-sensing/
• GET /api/location-data/remote-sensing/cluster-blocks/{cluster_uuid}/live/
• GET /api/location-data/remote-sensing/cluster-recommendations/
• GET /api/location-data/remote-sensing/results/{result_id}/k-options/
• POST /api/location-data/remote-sensing/results/{result_id}/k-options/activate/
• GET /api/location-data/remote-sensing/runs/{run_id}/status/

احراز هویت

همه این endpointها با JWT کار می‌کنند.

نمونه header:

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

ساختار عمومی response

تقریبا همه endpointها این فرم را دارند:

{
  "code": 200,
  "msg": "success",
  "data": {}
}

قاعده پیشنهادی در فرانت:

1. اول HTTP status را چک کنید.
2. بعد code را از body چک کنید.
3. در موفقیت، فقط data را به state یا UI بدهید.
4. در خطا، msg را به عنوان پیام اصلی نمایش دهید.
5. اگر data شامل خطای فیلدها بود، آن را برای فرم map کنید.

نمونه خطای validation:

{
  "code": 400,
  "msg": "داده نامعتبر.",
  "data": {
    "farm_uuid": ["This field is required."]
  }
}

نمونه خطای not found:

{
  "code": 404,
  "msg": "location پیدا نشد.",
  "data": null
}

---

1) دریافت location ذخیره شده

GET /api/location-data/

کاربرد:

• خواندن location ذخیره شده
• دریافت farm boundary
• دریافت block layout
• دریافت subdivisionها و snapshotهای ماهواره ای ذخیره شده

query params

• lat اختیاری
• lon اختیاری
• farm_uuid اختیاری

نمونه درخواست

GET /api/location-data/?farm_uuid=<farm_uuid>

نمونه response

{
  "code": 200,
  "msg": "success",
  "data": {
    "source": "database",
    "id": 12,
    "lon": "51.389000",
    "lat": "35.689200",
    "input_block_count": 2,
    "farm_boundary": {},
    "block_layout": {},
    "block_subdivisions": [],
    "satellite_snapshots": []
  }
}

استفاده در فرانت

• farm_boundary را برای رسم polygon کل مزرعه استفاده کنید.
• block_layout را برای رندر blockها استفاده کنید.
• block_subdivisions برای نمایش grid/subdivision مفید است.
• satellite_snapshots برای summaryهای تاریخی یا cache قابل استفاده است.

---

2) ثبت یا به روزرسانی location

POST /api/location-data/

کاربرد:

• ساخت location جدید
• update location قبلی
• ثبت farm boundary
• ثبت block layout

نمونه body

{
  "farm_uuid": "11111111-1111-1111-1111-111111111111",
  "lat": 35.6892,
  "lon": 51.389,
  "farm_boundary": {
    "type": "Polygon",
    "coordinates": []
  },
  "block_layout": {
    "blocks": []
  }
}

نکات فرانت

• اگر کاربر هنوز boundary را کامل نکرده، این endpoint را صدا نزنید.
• در صورت دریافت source = created می‌توانید UI را به عنوان location جدید mark کنید.
• در صورت دریافت source = database یعنی رکورد از قبل وجود داشته یا update شده است.

---

3) دریافت NDVI health

POST /api/location-data/ndvi-health/

کاربرد:

• گرفتن کارت سلامت پوشش گیاهی مزرعه
• نمایش شاخص NDVI در UI

body

{
  "farm_uuid": "11111111-1111-1111-1111-111111111111"
}

response مهم

{
  "code": 200,
  "msg": "success",
  "data": {
    "ndviIndex": 0.63,
    "mean_ndvi": 0.63,
    "ndvi_map": {},
    "vegetation_health_class": "healthy",
    "observation_date": "2026-05-12",
    "satellite_source": "sentinel-2",
    "healthData": [
      {
        "title": "میانگین NDVI",
        "value": 0.63,
        "color": "green",
        "icon": "leaf"
      }
    ]
  }
}

استفاده در فرانت

• ndviIndex را به عنوان KPI اصلی نمایش دهید.
• vegetation_health_class را برای badge یا رنگ وضعیت استفاده کنید.
• healthData را برای کارت های summary استفاده کنید.
• ndvi_map اگر لایه نقشه داشت، به map layer وصل شود.

---

4) خواندن cache سنجش از دور

GET /api/location-data/remote-sensing/

کاربرد:

• فقط داده cache شده یا ذخیره شده را می‌خواند
• پردازش جدید شروع نمی‌کند

query params

• farm_uuid اجباری
• page اختیاری
• page_size اختیاری
• start_date اختیاری
• end_date اختیاری

نمونه درخواست

GET /api/location-data/remote-sensing/?farm_uuid=<farm_uuid>&page=1&page_size=50

فیلدهای مهم response

• status
• source
• location
• summary
• cells
• run
• subdivision_result
• pagination
• metadata

رفتار پیشنهادی در فرانت بر اساس status

• success: داده آماده است و باید render شود.
• processing: هنوز نتیجه نهایی آماده نیست؛ loading یا polling state نشان دهید.
• not_found: هنوز تحلیل برای این مزرعه ساخته نشده؛ می‌توانید POST /remote-sensing/ را بزنید.

استفاده در فرانت

• cells برای نقشه سلولی و heatmap مناسب است.
• summary برای کارت آماری بالای صفحه مناسب است.
• subdivision_result.cluster_blocks برای نمایش cluster polygonها استفاده شود.
• assignments برای رنگ آمیزی سلول ها بر اساس label کلاستر مفید است.

---

5) شروع تحلیل سنجش از دور

POST /api/location-data/remote-sensing/

کاربرد:

• شروع async processing
• ساخت run و task_id
• شروع جریان polling برای UI

body

{
  "farm_uuid": "11111111-1111-1111-1111-111111111111"
}

response

{
  "code": 202,
  "msg": "تحلیل سنجش‌ازدور در صف قرار گرفت.",
  "data": {
    "status": "processing",
    "source": "processing",
    "location": {},
    "block_code": "",
    "chunk_size_sqm": 900,
    "temporal_extent": {
      "start_date": "2026-04-12",
      "end_date": "2026-05-12"
    },
    "summary": {
      "cell_count": 0,
      "ndvi_mean": null,
      "ndwi_mean": null,
      "soil_vv_db_mean": null
    },
    "cells": [],
    "run": {},
    "task_id": "11111111-1111-1111-1111-111111111111"
  }
}

قرارداد مهم برای فرانت

• همیشه task_id را ذخیره کنید.
• اگر run.id موجود بود، برای status endpoint از آن استفاده کنید.
• بعد از این endpoint بلافاصله polling را شروع کنید.

flow پیشنهادی

POST /remote-sensing/
-> دریافت task_id / run
-> هر چند ثانیه GET /runs/{run_id}/status/
-> وقتی status = completed شد، همان payload را مصرف کن

---

6) دریافت live metrics برای یک cluster

GET /api/location-data/remote-sensing/cluster-blocks/{cluster_uuid}/live/

کاربرد:

• گرفتن metricهای یک cluster
• استفاده برای panel جزئیات یا modal زنده

نمونه درخواست

GET /api/location-data/remote-sensing/cluster-blocks/<cluster_uuid>/live/

فیلدهای مهم

• source
• cluster_block
• summary
• metrics
• metadata

نکات فرانت

• اگر source = database بود، label بزنید که داده cache است.
• اگر source = openeo بود، می‌توانید label زنده یا live نمایش دهید.
• metrics برای KPIهای سریع مناسب است.
• cluster_block.geometry را برای هایلایت روی نقشه استفاده کنید.

---

7) پیشنهاد گیاه برای clusterها

GET /api/location-data/remote-sensing/cluster-recommendations/

کاربرد:

• دریافت پیشنهاد محصول برای هر cluster
• نمایش candidate plantها و suggested plant

query params

• farm_uuid اجباری

فیلدهای مهم response

• registered_plants
• clusters
• evaluated_plant_count
• cluster_count

استفاده در فرانت

برای هر cluster این بخش ها مهم هستند:

• satellite_metrics
• sensor_metrics
• resolved_metrics
• candidate_plants
• suggested_plant

UI پیشنهادی

• کارت cluster با عنوان sub_block_code یا cluster_label
• KPIهای resolved_metrics
• جدول candidateها با score
• highlight کردن suggested_plant

---

8) لیست K optionها

GET /api/location-data/remote-sensing/results/{result_id}/k-options/

کاربرد:

• گرفتن همه Kهای ذخیره شده برای یک subdivision result

response مهم

{
  "code": 200,
  "msg": "success",
  "data": {
    "result_id": 5,
    "active_requested_k": 3,
    "recommended_requested_k": 4,
    "options": []
  }
}

استفاده در فرانت

• active_requested_k را به عنوان گزینه فعال UI نشان دهید.
• recommended_requested_k را با badge پیشنهادی نمایش دهید.
• options را برای dropdown یا segmented control استفاده کنید.

---

9) فعال سازی یک K

POST /api/location-data/remote-sensing/results/{result_id}/k-options/activate/

body

{
  "requested_k": 4
}

استفاده در فرانت

• وقتی کاربر K جدید را انتخاب می‌کند این endpoint را صدا بزنید.
• بعد از موفقیت، subdivision_result برگشتی را جایگزین state قبلی کنید.
• لازم نیست دوباره GET /remote-sensing/ را صدا بزنید اگر payload کامل برگشت.

---

10) polling وضعیت run

GET /api/location-data/remote-sensing/runs/{run_id}/status/

کاربرد:

• فهمیدن این که pipeline در چه مرحله‌ای است
• دریافت نتیجه نهایی به محض completion

statusهای مهم

• pending
• running
• retrying
• completed
• failed

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

• pending: queue state
• running: progress state
• retrying: پیام retry موقت
• completed: داده نهایی را render کن
• failed: CTA برای retry بده

نکته مهم

اگر status = completed شد، همان response نهایی را مصرف کنید و polling را stop کنید.

---

فیلدهای مهم برای map

farm level

• farm_boundary
• block_layout.blocks
• block_subdivisions

remote sensing level

• cells[].geometry
• subdivision_result.cluster_blocks[].geometry
• subdivision_result.assignments[]
• cluster_block.geometry

پیشنهاد برای لایه های نقشه

1. لایه مرز مزرعه
2. لایه blockها
3. لایه cellها یا heatmap
4. لایه cluster blockها
5. لایه selected cluster highlight

---

خطاهایی که فرانت باید handle کند

400

• ورودی ناقص یا نامعتبر
• باید خطای فیلدی یا toast نشان داده شود

404

• مزرعه یا location یا result پیدا نشده
• برای UI بهتر است empty state نمایش داده شود

502

• خطا از backend upstream مثل openEO یا AI
• بهتر است retry action داشته باشید

---

flow پیشنهادی کامل برای صفحه تحلیل

سناریو اول: فقط نمایش داده موجود

GET /api/location-data/remote-sensing/?farm_uuid=<farm_uuid>
-> اگر status=success : render
-> اگر status=processing : برو به polling
-> اگر status=not_found : دکمه شروع تحلیل نمایش بده

سناریو دوم: کاربر تحلیل را شروع می‌کند

POST /api/location-data/remote-sensing/
-> 202
-> run/task_id را ذخیره کن
-> GET /api/location-data/remote-sensing/runs/{run_id}/status/
-> وقتی completed شد نتیجه را render کن

سناریو سوم: کاربر K را تغییر می‌دهد

GET /results/{result_id}/k-options/
-> انتخاب K
-> POST /results/{result_id}/k-options/activate/
-> subdivision_result جدید را render کن

---

پیشنهاد state management در فرانت

حداقل stateهایی که نیاز دارید:

{
  location: null,
  remoteSensing: null,
  runStatus: null,
  clusterRecommendations: [],
  selectedClusterUuid: null,
  kOptions: [],
  loading: false,
  polling: false,
  error: null
}

---

نکات نهایی برای تیم فرانت

• برای endpointهای async همیشه polling را در نظر بگیرید.
• code را از body نادیده نگیرید.
• روی status در remote sensing و run status منطق UI بنویسید.
• داده های هندسی را مستقیم برای map layerها مصرف کنید.
• cluster_uuid, result_id, run_id را بعد از اولین response در state نگه دارید.

---

فایل مکمل

اگر به جزئیات کامل همه responseها نیاز دارید، این فایل را هم ببینید:

• docs/location_data_api_responses_fa.md