Ai/docs/location_data_remote_sensing_response_explained.md

توضیح response سنجش‌ازدور

این فایل response زیر را توضیح می‌دهد:

• کد HTTP داخلی: 200
• پیام: success
• وضعیت نهایی تحلیل: completed
• منبع response: database

این response نشان می‌دهد که pipeline سنجش‌ازدور برای یک مزرعه با موفقیت اجرا شده، داده‌های ماهواره‌ای برای 12 سلول grid ذخیره شده، و در نهایت subdivision داده‌محور با 2 خوشه ساخته شده است.

جمع‌بندی سریع همین response

• تحلیل مربوط به بازه 2026-04-09 تا 2026-05-09 است.
• درخواست در 2026-05-10T20:17:34Z شروع شده و در 2026-05-10T20:28:29Z کامل شده است.
• 12 سلول grid با اندازه 900 مترمربع پردازش شده‌اند.
• feature های استفاده‌شده برای clustering این‌ها هستند:
  • ndvi
  • ndwi
  • soil_vv_db
• هیچ metricی fail نشده است.
• همه 12 observation قابل استفاده بوده‌اند:
  • usable_observation_count = 12
  • fully_null_observation_count = 0
• نتیجه نهایی clustering برابر 2 خوشه است.

ساختار کلی response

ساختار سطح بالا این response به صورت زیر است:

{
  "code": 200,
  "msg": "success",
  "data": {
    "status": "completed",
    "source": "database",
    "run": {...},
    "task": {...},
    "location": {...},
    "summary": {...},
    "cells": [...],
    "subdivision_result": {...},
    "pagination": {...}
  }
}

هر بخش یک نقش جدا دارد:

• run: رکورد اصلی اجرای تحلیل
• task: وضعیت orchestration و stageهای Celery/pipeline
• location: اطلاعات مزرعه و layout بلوک‌ها
• summary: خلاصه آماری observationها
• cells: داده خام هر سلول grid
• subdivision_result: خروجی clustering و assignment هر سلول
• pagination: اطلاعات صفحه‌بندی برای لیست cellها و assignmentها

بخش code و msg

• code = 200
  • یعنی endpoint با موفقیت جواب داده است.
• msg = "success"
  • پیام عمومی موفقیت است.

این دو فیلد بیشتر برای client-side handling مفید هستند.

بخش data.status و data.source

• status = "completed"
  • یعنی فرآیند تحلیلی کامل شده و نتیجه نهایی آماده است.
• source = "database"
  • یعنی response از داده‌های ذخیره‌شده در دیتابیس ساخته شده، نه از اجرای زنده openEO در همان لحظه.

نکته:

• این به معنی آن نیست که openEO استفاده نشده؛ برعکس، openEO قبلاً استفاده شده و خروجی آن در DB persist شده است.
• فقط endpoint فعلی نتیجه را از cache دیتابیسی برگردانده است.

بخش run

بخش run رکورد اصلی اجرای remote sensing را توصیف می‌کند.

فیلدهای پایه

• id = 1
  • شناسه اجرای تحلیل
• block_code = ""
  • اجرای تحلیل روی block پیش‌فرض/کل محدوده انجام شده است
• chunk_size_sqm = 900
  • هر cell حدود 900 مترمربع است
• temporal_start = "2026-04-09"
• temporal_end = "2026-05-09"
  • بازه زمانی داده‌های ماهواره‌ای

وضعیت run

• status = "success"
  • وضعیت خام دیتابیس
• status_label = "completed"
  • نسخه نرمال‌شده برای client
• pipeline_status = "completed"
  • وضعیت نهایی قابل نمایش برای frontend
• stage = "completed"
  • آخرین stage ثبت‌شده

featureهای انتخاب‌شده

• selected_features = ["ndvi", "ndwi", "soil_vv_db"]

یعنی clustering فقط با این سه feature انجام شده است.

requested_cluster_count

• requested_cluster_count = null

یعنی کاربر تعداد cluster را مستقیماً مشخص نکرده و سیستم آن را خودش انتخاب کرده است.

بخش run.metadata

این بخش metadata کامل اجرای pipeline را نگه می‌دارد.

scope

• scope = "all_blocks"

یعنی اجرا در scope کل blockهای قابل تحلیل ثبت شده است.

service

این بخش مشخص می‌کند metricها از کدام backend آمده‌اند.

• backend = "openeo"
• backend_url = "https://openeofed.dataspace.copernicus.eu"
• collections_used = ["SENTINEL2_L2A", "SENTINEL1_GRD"]

یعنی:

• ndvi و ndwi از Sentinel-2
• soil_vv از Sentinel-1
• soil_vv_db به صورت مشتق‌شده از soil_vv

job_refs

این‌ها شناسه jobهای openEO هستند:

• ndvi
• ndwi
• soil_vv

این شناسه‌ها برای trace کردن jobهای backend خیلی مهم‌اند.

failed_metrics

• failed_metrics = []

یعنی هیچ metricی fail نشده است.

payload_diagnostics

برای هر metric یک summary از payload خام openEO ذخیره شده:

• returned_cell_count = 12
• payload_keys_sample = ["0", "1", "2", "3", "4"]
• available_features = []

تعبیر این بخش:

• backend برای هر metric 12 نتیجه برگردانده
• payload به صورت positional/list-based بوده، نه با cell_codeهای صریح
• available_features = [] طبیعی است، چون payload از نوع لیستی عددی بوده و structure دیکشنری feature-based نداشته است

بخش run.metadata.summary

این خلاصه اجرایی run است:

• source = "openeo"
• status = "completed"
• cell_count = 12
• processed_cell_count = 12
• created_observation_count = 12
• updated_observation_count = 0
• existing_observation_count = 0
• failed_metric_count = 0
• cluster_count = 2
• subdivision_result_id = 1

معنی عملی:

• همه 12 سلول تازه ساخته و پردازش شده‌اند
• چیزی از قبل reuse نشده
• pipeline بدون failure تا انتها رفته

بخش timestamps

این timestamps جریان کامل pipeline را نشان می‌دهند:

• queued_at: زمان queue شدن task
• started_at: زمان شروع واقعی task
• preparing_analysis_grid_at: زمان شروع ساخت grid
• analysis_grid_ready_at: زمان آماده شدن grid
• analysis_cells_selected_at: زمان انتخاب cellهای هدف
• fetching_remote_metrics_at: زمان شروع fetch از openEO
• remote_metrics_fetched_at: زمان تکمیل دریافت metricها
• observations_persisted_at: زمان ذخیره observationها در DB
• clustering_completed_at: زمان تکمیل clustering
• completed_at: زمان پایان کامل pipeline

برای این response:

• start: 2026-05-10T20:17:34.570353+00:00
• complete: 2026-05-10T20:28:29.469326+00:00

پس کل فرآیند حدود 10 دقیقه و 55 ثانیه طول کشیده است.

بخش stage_details

این بخش مهم‌ترین قسمت برای debugging و فهم pipeline است.

analysis_grid_ready

{
  "created": true,
  "total_count": 12,
  "created_count": 12,
  "existing_count": 0
}

یعنی:

• grid analysis تازه ساخته شده
• 12 سلول جدید ایجاد شده

analysis_cells_selected

{
  "force_refresh": false,
  "total_cell_count": 12,
  "existing_cell_count": 0,
  "cell_count_to_process": 12
}

یعنی:

• force refresh فعال نبوده
• هیچ cell cache‌شده‌ای برای reuse وجود نداشته
• هر 12 سلول باید از openEO پردازش می‌شدند

fetching_remote_metrics

این بخش دو چیز را نشان می‌دهد:

• target_cells
  • لیست سلول‌هایی که برایشان metric گرفته شده
• metric_progress
  • وضعیت پیشرفت metricها

در این response:

• total_metrics = 3
• metricهای کامل‌شده:
  • ndvi
  • ndwi
  • soil_vv_db

نکته:

• job_ref soil_vv_db در اصل به job مربوط به soil_vv map شده، چون soil_vv_db metric مشتق‌شده است.

remote_metrics_fetched

این بخش metadata سرویس را بعد از fetch نگه می‌دارد و تأیید می‌کند:

• metricها از openEO آمده‌اند
• هیچ metricی fail نشده
• برای هر metric 12 سلول نتیجه برگشته

observations_persisted

این بخش نشان می‌دهد داده‌ها با موفقیت در DB ذخیره شده‌اند:

• created_count = 12
• updated_count = 0
• matched_cell_count = 12
• usable_observation_count = 12
• fully_null_observation_count = 0
• unmatched_db_cell_codes = []
• unmatched_payload_cell_codes = []

این یکی از مهم‌ترین بخش‌های response است، چون ثابت می‌کند:

• matching بین payload و سلول‌های DB کامل بوده
• هیچ observation خالی persist نشده
• تمام cellها usable بوده‌اند

clustering_completed

این بخش خروجی clustering را خلاصه می‌کند:

• cluster_count = 2
• used_cell_count = 12
• skipped_cell_count = 0
• subdivision_result_id = 1

و پارامترهای KMeans:

• max_k = 10
• n_init = 10
• random_state = 42
• selection_strategy = "elbow"
• selected_k = 2

یعنی سیستم با روش elbow، مقدار K = 2 را بهترین انتخاب دیده است.

بخش task

بخش task نسخه task-oriented همین اجرا را نشان می‌دهد.

current_stage

• current_stage = "completed"

یعنی دیگر stage فعالی وجود ندارد و task بسته شده است.

stages

این آرایه تاریخچه stageها را نگه می‌دارد:

• queued
• preparing_analysis_grid
• analysis_grid_ready
• analysis_cells_selected
• fetching_remote_metrics
• remote_metrics_fetched
• observations_persisted
• clustering_completed
• completed

این ترتیب دقیق pipeline را نشان می‌دهد.

metric_progress

این بخش برای UI بسیار مفید است:

• total_metrics = 3
• completed_metric_count = 3
• failed_metrics = []
• active_metric = null

پس هیچ metric نیمه‌کاره یا fail شده‌ای باقی نمانده است.

celery

این بخش وضعیت Celery task را نشان می‌دهد:

• state = "SUCCESS"
• ready = true
• successful = true
• failed = false

و در info هم خلاصه اجرایی برگردانده شده:

• 12 سلول پردازش شده
• 12 observation ساخته شده
• 2 cluster تولید شده

بخش location

این بخش context مکانی تحلیل را نشان می‌دهد.

اطلاعات پایه

• id = 1
• lon = "50.000000"
• lat = "50.000000"
• input_block_count = 1

farm_boundary

یک polygon مربعی کوچک اطراف مختصات 50,50 است.

block_layout

در blocks دو ورودی دیده می‌شود:

1. block پیش‌فرض:

   • source = "default"
   • block_code = "block-1"

2. block تولیدشده از remote sensing:

   • source = "remote_sensing"
   • block_code = ""
   • needs_subdivision = true
   • دارای 2 زیر‌بلوک (cluster-0, cluster-1)

این یعنی سیستم علاوه بر block اولیه، یک layout تحلیلی جدید هم بر اساس داده‌های remote sensing ساخته است.

analysis_grid_summary

• cell_count = 12
• chunk_size_sqm = 900

یعنی farm boundary به 12 cell با اندازه 900 مترمربع شکسته شده است.

satellite_snapshots

دو snapshot وجود دارد:

1. برای block-1

   • status = "missing"
   • یعنی برای آن block خاص snapshot مستقلی وجود ندارد

2. برای block_code = ""

   • status = "completed"
   • run_id = 1
   • cell_count = 12
   • resolved_metrics:
     • ndvi = 0.686502
     • ndwi = -0.598028
     • soil_vv_db = -13.374155

این اعداد همان summary ساده‌ی metrics در کل محدوده هستند.

بخش summary

این بخش خلاصه آماری کل observationها است:

{
  "cell_count": 12,
  "ndvi_mean": 0.686502,
  "ndwi_mean": -0.598028,
  "soil_vv_db_mean": -13.374155
}

معنی:

• 12 سلول در summary لحاظ شده‌اند
• میانگین ndvi حدود 0.6865
• میانگین ndwi حدود -0.5980
• میانگین soil_vv_db حدود -13.3742

بخش cells

این آرایه، داده خام هر سلول را نگه می‌دارد.

هر item شامل این‌ها است:

• cell_code
• block_code
• chunk_size_sqm
• centroid_lat
• centroid_lon
• geometry
• temporal_start
• temporal_end
• ndvi
• ndwi
• soil_vv
• soil_vv_db
• metadata

مثال از یک cell

برای اولین سلول:

• cell_code = loc-1__block-farm__chunk-900__r0000c0000
• ndvi = 0.6622872683737013
• ndwi = -0.583760056230757
• soil_vv = 0.0290423126684294
• soil_vv_db = -15.369688

این یعنی این cell هم داده خام خطی Sentinel-1 (soil_vv) را دارد، هم نسخه dB آن (soil_vv_db).

cells[].metadata

metadata هر سلول شامل این‌ها است:

• run_id
• job_refs
• backend_name
• backend_url
• collections_used
• failed_metrics
• payload_diagnostics

این metadata برای traceability خیلی مفید است، چون مشخص می‌کند این observation از کدام run و کدام jobهای openEO آمده است.

بخش subdivision_result

این بخش خروجی اصلی clustering را نشان می‌دهد.

فیلدهای پایه

• id = 1
• cluster_count = 2
• selected_features = ["ndvi", "ndwi", "soil_vv_db"]
• skipped_cell_codes = []

یعنی:

• نتیجه نهایی clustering دو خوشه دارد
• هیچ cellی حذف نشده

metadata.scaler_means

میانگین هر feature قبل از scaling:

• ndvi = 0.6865018435098507
• ndwi = -0.5980279920277772
• soil_vv_db = -13.374155250000005

metadata.scaler_scales

انحراف معیار/scale هر feature:

• ndvi = 0.018948282260331236
• ndwi = 0.012494317547431832
• soil_vv_db = 0.87754098540943

metadata.imputer_statistics

چون imputer از نوع median بوده:

• median ndvi
• median ndwi
• median soil_vv_db

برای این run ذخیره شده‌اند، حتی اگر در این مورد missing value نداشته‌ایم.

metadata.missing_value_counts

{
  "ndvi": 0,
  "ndwi": 0,
  "soil_vv_db": 0
}

این خیلی مهم است، چون نشان می‌دهد برای featureهای clustering هیچ داده‌ی گم‌شده‌ای وجود نداشته است.

metadata.inertia_curve

این آرایه SSE را برای Kهای مختلف نگه می‌دارد:

• k=1 => sse=36
• k=2 => sse=14.987928
• ...
• k=10 => sse=0.140512

سیستم از این curve برای انتخاب elbow استفاده کرده و در نهایت k=2 را برداشته است.

metadata.cluster_summaries

خلاصه هر cluster:

• cluster-0

  • cell_count = 9
  • centroid_lat = 49.999995
  • centroid_lon = 50.000223

• cluster-1

  • cell_count = 3
  • centroid_lat = 50.000174
  • centroid_lon = 49.99985

یعنی تقسیم‌بندی نهایی مزرعه به دو زیر‌بلوک 9تایی و 3تایی انجام شده است.

assignments

این آرایه برای هر cell مشخص می‌کند:

• عضو کدام cluster است
• raw feature value آن چیست
• scaled feature value آن چیست

مثلاً:

• loc-1__block-farm__chunk-900__r0000c0000
  • cluster_label = 1
  • raw_feature_values.ndvi = 0.662287...
  • raw_feature_values.ndwi = -0.583760...
  • raw_feature_values.soil_vv_db = -15.369688

این بخش برای تحلیل این‌که چرا یک cell داخل یک cluster خاص افتاده بسیار مفید است.

بخش pagination

این بخش صفحه‌بندی را برای دو لیست نشان می‌دهد:

• cells
• assignments

در هر دو مورد:

• page = 1
• page_size = 100
• total_items = 12
• total_pages = 1
• has_next = false
• has_previous = false

یعنی تمام داده‌ها در یک صفحه جا شده‌اند.

نتیجه نهایی این response

اگر بخواهیم این response را در یک جمله خلاصه کنیم:

• سیستم در تاریخ 2026-05-10 یک تحلیل سنجش‌ازدور موفق روی 12 سلول grid انجام داده، metricهای ndvi, ndwi, soil_vv_db را بدون missing value ذخیره کرده، و مزرعه را با روش elbow-based KMeans به 2 زیر‌بلوک تقسیم کرده است.

مهم‌ترین فیلدها برای استفاده عملی

اگر فقط چند بخش برای frontend یا debugging مهم باشد، این‌ها از همه مهم‌ترند:

• data.status
• data.run.selected_features
• data.run.metadata.summary
• data.run.metadata.stage_details.observations_persisted
• data.summary
• data.cells
• data.subdivision_result.metadata.cluster_summaries
• data.subdivision_result.assignments

برداشت فنی از سلامت این run

این response از نظر pipeline یک run سالم را نشان می‌دهد:

• status نهایی completed است
• Celery در SUCCESS است
• هیچ metricی fail نشده
• همه cellها match شده‌اند
• هیچ observationی null کامل نیست
• clustering روی همه سلول‌ها اجرا شده
• output نهایی subdivision ساخته شده

پس این response نمونه‌ی یک اجرای موفق و کامل remote sensing subdivision است.