Ai/docs/location_data_remote_sensing_failure_report.md

# گزارش تحلیل خطای `location_data` برای Remote Sensing Run

این سند بر اساس payload دریافتی از endpoint زیر تهیه شده است:

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

نمونه run بررسی‌شده:

- `task_id`: `02959179-63b2-4388-bb2e-a4d79176eca2`
- `run.id`: `6`
- بازه زمانی: `2026-04-09` تا `2026-05-09`
- وضعیت API: `failed`
- وضعیت Celery: `RETRY`

---

## 1) خلاصه خیلی کوتاه

این run تا مرحله واکشی metricها و ذخیره observationها جلو رفته، اما در مرحله ساخت subdivision داده‌محور شکست خورده است.

خطای نهایی:

- `هیچ observation قابل استفاده‌ای برای خوشه‌بندی باقی نماند.`

این خطا در کد دقیقاً زمانی رخ می‌دهد که سیستم بعد از بارگذاری observationها، هیچ ردیفی را برای clustering قابل استفاده تشخیص ندهد.

مسیر کد:

- `location_data/tasks.py`
- `location_data/data_driven_subdivision.py`

---

## 2) جدول مدل‌ها / جدول‌های درگیر

| مدل | جدول Django | نقش |
|---|---|---|
| `SoilLocation` | `location_data_soillocation` | اطلاعات location و farm boundary |
| `BlockSubdivision` | `location_data_blocksubdivision` | تقسیم‌بندی بلوک/مزرعه |
| `RemoteSensingRun` | `location_data_remotesensingrun` | وضعیت اجرای pipeline سنجش‌ازدور |
| `AnalysisGridCell` | `location_data_analysisgridcell` | سلول‌های شبکه تحلیلی |
| `AnalysisGridObservation` | `location_data_analysisgridobservation` | مقادیر metricها برای هر cell |
| `RemoteSensingSubdivisionResult` | `location_data_remotesensingsubdivisionresult` | نتیجه clustering و subdivision نهایی |
| `RemoteSensingClusterAssignment` | `location_data_remotesensingclusterassignment` | نسبت هر cell به cluster |

---

## 3) جدول معنی فیلدهای سطح اول response

| فیلد | مقدار نمونه | توضیح |
|---|---|---|
| `code` | `200` | پاسخ HTTP موفق از API؛ لزوماً به معنای موفق بودن task نیست |
| `msg` | `success` | پیام wrapper API |
| `data.status` | `failed` | وضعیت client-facing run |
| `data.source` | `database` | payload از داده‌های ذخیره‌شده در DB ساخته شده |
| `data.task_id` | UUID | شناسه Celery task |
| `data.run` | object | snapshot اصلی run |
| `data.task` | object | جزئیات stageها، timestamps و وضعیت Celery |

---

## 4) جدول معنی فیلدهای `run`

| فیلد | مقدار نمونه | توضیح |
|---|---|---|
| `id` | `6` | شناسه رکورد run در DB |
| `block_code` | `""` | خالی یعنی کل مزرعه، نه یک بلوک خاص |
| `chunk_size_sqm` | `900` | اندازه هر cell به متر مربع |
| `temporal_start` | `2026-04-09` | شروع بازه تحلیل |
| `temporal_end` | `2026-05-09` | پایان بازه تحلیل |
| `status` | `failure` | مقدار خام DB |
| `status_label` | `failed` | نسخه نرمال‌شده برای client |
| `pipeline_status` | `failed` | تکرار client-facing status |
| `stage` | `observations_persisted` | آخرین stage ذخیره‌شده در metadata |
| `selected_features` | `ndvi`, `ndwi`, `soil_vv_db`, `dem_m`, `slope_deg` | featureهایی که pipeline فکر می‌کند برای clustering لازم‌اند |
| `requested_cluster_count` | `null` | تعداد cluster صریح از کاربر نیامده و الگوریتم باید تصمیم بگیرد |
| `error_message` | متن فارسی خطا | خطای نهایی ثبت‌شده روی run |
| `started_at` | timestamp | زمان شروع واقعی run |
| `finished_at` | timestamp | زمان ثبت failure روی run |
| `created_at` | timestamp | زمان ایجاد رکورد run |
| `updated_at` | timestamp | آخرین به‌روزرسانی رکورد run |

---

## 5) جدول معنی فیلدهای `run.metadata`

| فیلد | توضیح |
|---|---|
| `scope` | scope اجرای تحلیل؛ در این نمونه `all_blocks` |
| `stage` | stage فعلی/آخر ذخیره‌شده |
| `task_id` | شناسه Celery task |
| `pipeline.name` | نام pipeline |
| `pipeline.version` | نسخه pipeline |
| `farm_uuid` | شناسه مزرعه |
| `timestamps` | زمان ورود به هر stage |
| `status_label` | وضعیت client-facing ذخیره‌شده در metadata |
| `requested_via` | مبدا درخواست؛ در این نمونه `api` |
| `stage_details` | جزئیات هر stage |
| `failure_reason` | دلیل نهایی ثبت failure |
| `selected_features` | featureهای مورد استفاده برای clustering |
| `requested_cluster_count` | cluster count درخواستی، اگر وجود داشته باشد |

---

## 6) جدول معنی stageها در این run

| stage | وضعیت مشاهده‌شده | معنی |
|---|---|---|
| `queued` | completed | task در صف قرار گرفته |
| `preparing_analysis_grid` | completed | آماده‌سازی grid تحلیلی |
| `analysis_grid_ready` | completed | grid سلول‌ها آماده بوده |
| `analysis_cells_selected` | completed | 12 سلول برای پردازش انتخاب شده‌اند |
| `fetching_remote_metrics` | completed | metricها از openEO درخواست شده‌اند |
| `remote_metrics_fetched` | completed | jobهای openEO تمام شده‌اند |
| `observations_persisted` | failed | observationها ذخیره شده‌اند ولی pipeline بعد از این مرحله fail شده |
| `failed` | completed | stage شکست نهایی ثبت شده |

نکته مهم:

- در payload فعلی، `run.stage` هنوز `observations_persisted` است اما `data.status` برابر `failed` است.
- این یعنی status و stage با هم perfectly sync نیستند.

---

## 7) جدول معنی `stage_details`

### 7.1) `preparing_analysis_grid`

| فیلد | توضیح |
|---|---|
| `block_code` | بلوک هدف |
| `temporal_extent.start_date` | شروع بازه |
| `temporal_extent.end_date` | پایان بازه |

### 7.2) `analysis_grid_ready`

| فیلد | توضیح |
|---|---|
| `grid_summary.created` | آیا grid همین run ساخته شده یا از قبل وجود داشته |
| `grid_summary.block_code` | کد بلوک |
| `grid_summary.total_count` | تعداد کل cellها |
| `grid_summary.created_count` | تعداد cell تازه ایجادشده |
| `grid_summary.chunk_size_sqm` | اندازه cell |
| `grid_summary.existing_count` | تعداد cellهای موجود از قبل |

### 7.3) `analysis_cells_selected`

| فیلد | توضیح |
|---|---|
| `force_refresh` | آیا cache نادیده گرفته شده |
| `total_cell_count` | تعداد کل cellها |
| `existing_cell_count` | تعداد cellهایی که داده از قبل داشته‌اند |
| `cell_count_to_process` | تعداد cellهایی که باید پردازش شوند |

### 7.4) `fetching_remote_metrics`

| فیلد | توضیح |
|---|---|
| `target_cells` | لیست cellهای هدف |
| `requested_cell_count` | تعداد cellهای هدف |
| `metric_progress.total_metrics` | تعداد metricهایی که pipeline انتظار دارد |
| `metric_progress.completed_metric_count` | تعداد metricهای کامل‌شده |
| `metric_progress.completed_metrics` | metricهای کامل‌شده واقعی |
| `metric_progress.failed_metrics` | metricهای fail شده |
| `metric_progress.states` | وضعیت هر metric از نگاه progress tracker |

### 7.5) `remote_metrics_fetched`

| فیلد | توضیح |
|---|---|
| `failed_metric_count` | تعداد metric fail شده |
| `service_metadata.backend` | backend مورد استفاده |
| `service_metadata.job_refs` | job id هر metric در openEO |
| `service_metadata.backend_url` | آدرس backend |
| `service_metadata.failed_metrics` | خطاهای metric-level |
| `service_metadata.collections_used` | collectionهای مصرف‌شده |

### 7.6) `observations_persisted`

| فیلد | توضیح |
|---|---|
| `created_count` | تعداد observation ساخته‌شده |
| `updated_count` | تعداد observation به‌روزشده |

---

## 8) جدول معنی `task`

| فیلد | مقدار نمونه | توضیح |
|---|---|---|
| `current_stage` | `observations_persisted` | stage فعلی/آخرین stage ثبت‌شده |
| `current_stage_details` | `created_count=12`, `updated_count=0` | جزئیات stage جاری |
| `timestamps` | object | timeline کامل stageها |
| `stages` | list | نسخه ترتیبی از stageها |
| `metric_progress` | object | وضعیت پیشرفت metricها |
| `failure_reason` | متن فارسی | خطای ثبت‌شده |
| `celery.state` | `RETRY` | Celery task هنوز final نشده و در retry است |
| `celery.ready` | `false` | نتیجه نهایی هنوز آماده نیست |
| `celery.successful` | `false` | task هنوز success نشده |
| `celery.failed` | `false` | task هنوز fail نهایی نشده |
| `celery.info` | متن خطا | پیام retry فعلی Celery |

---

## 9) دلیل دقیق خطا

دلیل مستقیم خطا از خود کد:

- در `location_data/data_driven_subdivision.py` اگر بعد از ساخت dataset، هیچ observation قابل استفاده برای clustering باقی نماند، این exception پرتاب می‌شود:
  - `هیچ observation قابل استفاده‌ای برای خوشه‌بندی باقی نماند.`

این یعنی pipeline به این نقطه رسیده:

1. cellها ساخته شده‌اند
2. metricها از openEO درخواست شده‌اند
3. observationها در DB ذخیره شده‌اند
4. اما در زمان ساخت dataset برای clustering، ردیف قابل مصرفی پیدا نشده است

### معنی عملی این خطا

یعنی برای همه observationهای این run، سیستم نتوانسته feature vector قابل استفاده بسازد.

در کد فعلی، observation وقتی از clustering حذف می‌شود که:

- همه featureهای انتخاب‌شده برای آن observation برابر `None` باشند

پس این خطا معمولاً یعنی:

- یا تمام metricهای لازم برای همه cellها `null` شده‌اند
- یا feature set انتخابی با داده‌هایی که واقعاً ذخیره شده‌اند mismatch دارد
- یا persistence / selection طوری انجام شده که clustering به داده قابل استفاده دسترسی پیدا نکرده است

---

## 10) محتمل‌ترین علت‌ها برای همین run

### علت 1: featureهای حذف‌شده هنوز در pipeline زنده هستند

در payload می‌بینیم:

- `selected_features` هنوز شامل `dem_m` و `slope_deg` است
- اما در `location_data/openeo_service.py` این metricها از محاسبه حذف شده‌اند

نتیجه:

- API و metadata هنوز فکر می‌کنند این دو feature بخشی از clustering هستند
- ولی openEO دیگر آن‌ها را تولید نمی‌کند
- بنابراین در observationها این فیلدها عملاً `None` می‌مانند

نکته مهم:

- فقط `None` بودن `dem_m` و `slope_deg` به‌تنهایی برای تولید این خطا کافی نیست
- اما این mismatch یکی از مهم‌ترین نشانه‌های ناسازگاری pipeline است

### علت 2: metricهای اصلی احتمالاً برای همه cellها مقدار قابل استفاده نداشته‌اند

چون این خطا فقط وقتی رخ می‌دهد که هیچ observation usable باقی نماند، محتمل است که برای همه 12 cell:

- `ndvi`
- `ndwi`
- `soil_vv_db`

هم عملاً `None` شده باشند یا آن‌طور که clustering انتظار دارد قابل مصرف نبوده باشند.

این حالت ممکن است از اینجا آمده باشد:

- داده خام provider برای این محدوده/بازه تهی یا نامعتبر بوده
- masking یا aggregation مقدار usable تولید نکرده
- یا در persistence، featureهای محاسبه‌شده به‌درستی به ستون‌های clustering نرسیده‌اند

### علت 3: progress tracker با metricهای واقعی sync نیست

در payload:

- `completed_metrics` شامل `soil_vv` است
- ولی `states` شامل `soil_vv_db` به حالت `pending` است

یعنی tracker با metric واقعی اجراشده sync نیست:

- metric واقعی remote: `soil_vv`
- metric مشتق‌شده محلی: `soil_vv_db`

این باعث می‌شود progress ظاهراً ناقص دیده شود، حتی وقتی داده remote کامل شده است.

### علت 4: وضعیت DB و Celery با هم متناقض‌اند

در payload:

- `data.status = failed`
- ولی `task.celery.state = RETRY`

یعنی:

- از نظر DB، run شکست خورده ثبت شده
- از نظر Celery، task هنوز در حال retry است و failure نهایی نشده

این برای client گیج‌کننده است، چون معلوم نیست باید run را تمام‌شده و fail شده بداند یا منتظر retry بماند.

---

## 11) مشکلات فعلی `location_data` که از کد مشخص هستند

### مشکل 1: `DEFAULT_CLUSTER_FEATURES` هنوز metricهای حذف‌شده را نگه داشته

فایل:

- `location_data/data_driven_subdivision.py`

وضعیت فعلی:

- `dem_m`
- `slope_deg`

هنوز داخل `DEFAULT_CLUSTER_FEATURES` هستند.

اثر:

- `selected_features` اشتباه در run metadata
- progress tracker اشتباه
- clustering contract قدیمی باقی می‌ماند

### مشکل 2: serializer و summary هنوز `dem_m` و `slope_deg` را به API برمی‌گردانند

فایل‌ها:

- `location_data/serializers.py`
- `location_data/views.py`

اثر:

- response API هنوز metricهای حذف‌شده را نمایش می‌دهد
- summary میانگین `dem_m_mean` و `slope_deg_mean` می‌سازد
- مصرف‌کننده API فکر می‌کند این metricها هنوز پشتیبانی می‌شوند

### مشکل 3: `_upsert_grid_observations` هنوز فیلدهای حذف‌شده را persist می‌کند

فایل:

- `location_data/tasks.py`

اثر:

- ستون‌های `dem_m` و `slope_deg` همچنان نوشته می‌شوند، اما عملاً با `None`
- metadata هنوز `slope_supported` را ذخیره می‌کند، در حالی که openEO service دیگر این مفهوم را برنمی‌گرداند

### مشکل 4: progress metricها با metricهای واقعی اجراشده mismatch دارد

فایل:

- `location_data/tasks.py`

نمونه mismatch:

- remote metric واقعی: `soil_vv`
- feature مورد انتظار برای clustering: `soil_vv_db`

اثر:

- `completed_metrics` و `states` با هم ناسازگار می‌شوند
- `soil_vv_db` در response به شکل `pending` دیده می‌شود، با اینکه از `soil_vv` مشتق می‌شود

### مشکل 5: stage و status همیشه هماهنگ نیستند

در payload فعلی:

- `run.status_label = failed`
- `run.stage = observations_persisted`

اثر:

- client نمی‌فهمد خطا دقیقاً در کدام stage رخ داده
- `task.current_stage` هم گمراه‌کننده می‌شود

### مشکل 6: DB failure و Celery retry همزمان به client داده می‌شود

اثر:

- API برای یک run همزمان پیام `failed` و `RETRY` می‌دهد
- از نگاه UX، کاربر نمی‌داند باید retry خودکار را صبر کند یا خطا را final بداند

---

## 12) جمع‌بندی عملی برای همین خطا

بر اساس payload و کد، نتیجه عملی این است:

1. openEO jobها برای `ndvi`, `ndwi`, `soil_vv` اجرا شده‌اند
2. 12 observation در DB ساخته شده‌اند
3. pipeline وارد مرحله clustering شده
4. clustering هیچ observation usable پیدا نکرده
5. run در DB به حالت `failed` رفته
6. اما Celery هنوز task را در حالت `RETRY` نگه داشته

---

## 13) پیشنهادهای اصلاح

### اصلاح ضروری

1. `dem_m` و `slope_deg` را از این نقاط هم حذف کنید:
   - `location_data/data_driven_subdivision.py`
   - `location_data/serializers.py`
   - `location_data/views.py`
   - `location_data/tasks.py`

2. `DEFAULT_CLUSTER_FEATURES` را با metricهای واقعی sync کنید:
   - `ndvi`
   - `ndwi`
   - `soil_vv_db`

3. progress tracker را طوری اصلاح کنید که:
   - completion `soil_vv` به completion `soil_vv_db` هم map شود
   - metricهای حذف‌شده اصلاً در state دیده نشوند

4. منطق status endpoint را طوری تنظیم کنید که:
   - اگر Celery در `RETRY` است، status client نهایی `failed` نباشد
   - یا حداقل یک فیلد صریح مثل `final_status=false` برگردد

5. قبل از clustering، یک diagnostic بهتر ذخیره شود:
   - تعداد observationهای usable
   - تعداد observationهای all-null
   - تعداد null برای هر feature

### اصلاح پیشنهادی برای debug بهتر

در `stage_details` این موارد اضافه شود:

- `usable_observation_count`
- `all_features_missing_cell_codes`
- `feature_null_counts`
- `selected_features_effective`

---

## 14) نتیجه نهایی

این run به احتمال زیاد به خاطر ناسازگاری بین featureهای مورد انتظار pipeline و featureهای واقعاً تولید/ذخیره‌شده شکست خورده است، و علاوه بر آن چند inconsistency مهم در `location_data` وجود دارد:

- metricهای حذف‌شده هنوز در feature contract حضور دارند
- progress report با metricهای واقعی sync نیست
- DB status و Celery status با هم تناقض دارند
- stage نهایی برای failure به شکل واضح و قابل اتکا به client نمایش داده نمی‌شود

اگر بخواهید، مرحله بعدی می‌تواند این باشد که همین موارد را در کد هم اصلاح کنیم، نه فقط مستندسازی.