Ai/docs/location_data_current_structure.md

ساختار فعلی location_data

این فایل وضعیت فعلی اپ location_data را توضیح می‌دهد؛ هم از نظر ساختار فایل‌ها و هم از نظر مدل‌ها، APIها و جریان داده.

هدف فعلی اپ

اپ location_data فعلاً این مسئولیت‌ها را دارد:

• نگه‌داری موقعیت زمین با lat و lon
• نگه‌داری مرز مزرعه در farm_boundary
• نگه‌داری ساختار بلوک‌های زمین در block_layout
• نگه‌داری داده‌های خاک برای عمق‌های مختلف در SoilDepthData
• نگه‌داری مشاهدات NDVI در NdviObservation
• برگرداندن ساختار بلوک‌های زمین از API محلی بدون نیاز به API خارجی در فاز فعلی

نکته مهم:

• در فاز فعلی، endpoint اصلی location_data برای ساختار زمین، فقط داده را در دیتابیس می‌خواند/ذخیره می‌کند.
• فعلاً برای بلوک‌ها، زیر‌بلوک‌ها و داده‌های ماهواره‌ای هیچ درخواست خارجی زده نمی‌شود.

ساختار فایل‌ها

location_data/
├── admin.py
├── apps.py
├── models.py
├── serializers.py
├── views.py
├── urls.py
├── tasks.py
├── soil_adapters.py
├── remote_sensing.py
├── ndvi.py
├── test_soil_api.py
├── test_soil_adapters.py
├── test_ndvi_health_api.py
├── postman/
│   └── soil_data.json
├── management/
│   └── commands/
└── migrations/
    ├── 0001_initial.py
    ├── 0002_soildepthdata_refactor.py
    ├── 0002_soillocation_ideal_sensor_profile.py
    ├── 0003_rename_app_label.py
    ├── 0004_soillocation_farm_boundary.py
    ├── 0005_merge_20260327_0840.py
    ├── 0006_remove_soillocation_ideal_sensor_profile.py
    ├── 0007_ndviobservation.py
    └── 0008_soillocation_block_layout.py

مدل‌ها و جدول‌ها

1) SoilLocation

مدل اصلی اپ است و نماینده یک موقعیت یکتا برای زمین یا مرکز زمین محسوب می‌شود.

فیلدهای اصلی:

فیلد	نوع	توضیح
id	BigAutoField	شناسه داخلی رکورد
latitude	DecimalField(9,6)	عرض جغرافیایی
longitude	DecimalField(9,6)	طول جغرافیایی
task_id	CharField	شناسه تسک Celery برای جریان قدیمی واکشی خاک
farm_boundary	JSONField	مرز مزرعه به شکل Polygon یا corners
input_block_count	PositiveIntegerField	تعداد بلوک اولیه‌ای که از ورودی کشاورز می‌آید
block_layout	JSONField	ساختار بلوک‌ها و زیر‌بلوک‌های زمین
created_at	DateTimeField	زمان ایجاد
updated_at	DateTimeField	زمان آخرین تغییر

قیدها:

• روی ترکیب latitude و longitude یکتا است.

رفتار مهم:

• اگر input_block_count ارسال نشود، مقدار پیش‌فرض 1 است.
• اگر block_layout خالی باشد، به صورت خودکار با یک بلوک کامل ساخته می‌شود.
• متد set_input_block_count() ساختار اولیه بلوک‌ها را می‌سازد.

2) SoilDepthData

این مدل داده‌های خاک را برای هر عمق نگه می‌دارد و به SoilLocation وصل است.

عمق‌های فعلی:

• 0-5cm
• 5-15cm
• 15-30cm

فیلدهای مهم:

فیلد	نوع	توضیح
soil_location	ForeignKey	ارتباط با SoilLocation
depth_label	CharField	برچسب عمق
bdod تا wv1500	FloatField	پارامترهای مختلف خاک
created_at	DateTimeField	زمان ثبت رکورد

قیدها:

• برای هر soil_location و هر depth_label فقط یک رکورد وجود دارد.

3) NdviObservation

این مدل برای ذخیره مشاهده‌های NDVI استفاده می‌شود.

فیلدهای مهم:

فیلد	نوع	توضیح
location	ForeignKey	ارتباط با SoilLocation
observation_date	DateField	تاریخ مشاهده
mean_ndvi	FloatField	میانگین NDVI
ndvi_map	JSONField	داده مکانی NDVI
vegetation_health_class	CharField	کلاس سلامت پوشش گیاهی
satellite_source	CharField	منبع تصویر ماهواره‌ای
cloud_cover	FloatField	درصد ابر
metadata	JSONField	داده تکمیلی

ساختار block_layout

فیلد block_layout فعلاً ساختار پایه تقسیم زمین را نگه می‌دارد.

نمونه پیش‌فرض وقتی کل زمین یک بلوک باشد:

{
  "input_block_count": 1,
  "default_full_farm": true,
  "algorithm_status": "pending",
  "blocks": [
    {
      "block_code": "block-1",
      "order": 1,
      "source": "default",
      "needs_subdivision": null,
      "sub_blocks": []
    }
  ]
}

نمونه وقتی ورودی مثلاً block_count = 3 باشد:

{
  "input_block_count": 3,
  "default_full_farm": false,
  "algorithm_status": "pending",
  "blocks": [
    {
      "block_code": "block-1",
      "order": 1,
      "source": "input",
      "needs_subdivision": null,
      "sub_blocks": []
    },
    {
      "block_code": "block-2",
      "order": 2,
      "source": "input",
      "needs_subdivision": null,
      "sub_blocks": []
    },
    {
      "block_code": "block-3",
      "order": 3,
      "source": "input",
      "needs_subdivision": null,
      "sub_blocks": []
    }
  ]
}

معنای فیلدها:

فیلد	توضیح
input_block_count	تعداد بلوک اولیه
default_full_farm	آیا کل زمین هنوز یک بلوک کامل است یا نه
algorithm_status	وضعیت اجرای الگوریتم تقسیم‌بندی
blocks	لیست بلوک‌های فعلی
block_code	کد بلوک
order	ترتیب بلوک
source	منشأ بلوک: default یا input
needs_subdivision	آیا الگوریتم تشخیص داده که این بلوک باید خردتر شود یا نه
sub_blocks	لیست زیر‌بلوک‌ها

Serializerها

SoilDataRequestSerializer

ورودی endpoint اصلی location_data:

فیلد	اجباری	توضیح
lat	بله	عرض جغرافیایی
lon	بله	طول جغرافیایی
block_count	خیر	تعداد بلوک اولیه، پیش‌فرض 1

SoilLocationResponseSerializer

خروجی اصلی برای یک location:

• id
• lat
• lon
• input_block_count
• block_layout
• depths

SoilDepthDataSerializer

لیست پارامترهای خاک برای هر عمق را برمی‌گرداند.

NdviHealthRequestSerializer و NdviHealthResponseSerializer

برای endpoint مربوط به NDVI استفاده می‌شوند.

Viewها و APIها

1) SoilDataView

مسیر:

• GET /api/soil-data/
• POST /api/soil-data/

وظیفه فعلی:

• گرفتن lat و lon
• گرفتن block_count در صورت وجود
• ساخت یا پیدا کردن SoilLocation
• ذخیره input_block_count
• ساخت block_layout
• برگرداندن پاسخ با source = local

رفتار فعلی:

• اگر location وجود نداشته باشد، ساخته می‌شود.
• اگر block_count تغییر کند، ساختار block_layout دوباره ساخته می‌شود.
• فعلاً هیچ fetch خارجی برای اطلاعات خاک یا ماهواره‌ای انجام نمی‌شود.

2) SoilDataTaskStatusView

مسیر:

• GET /api/soil-data/tasks/<task_id>/status/

وضعیت فعلی:

• هنوز در کد وجود دارد.
• برای جریان قدیمی مبتنی بر Celery طراحی شده است.
• با تغییر اخیر، endpoint اصلی location_data دیگر به‌طور پیش‌فرض task جدیدی صف نمی‌کند.

3) NdviHealthView

مسیر:

• POST /api/soil-data/ndvi-health/

وظیفه:

• دریافت farm_uuid
• خواندن داده NDVI از سرویس داخلی NDVI
• برگرداندن اطلاعات سلامت پوشش گیاهی

فایل tasks.py

این فایل هنوز منطق قدیمی واکشی داده خاک را نگه می‌دارد.

اجزای اصلی:

• fetch_soil_data_for_coordinates()
• fetch_soil_data_task()

نکته:

• این بخش هنوز برای سازگاری و جریان‌های قدیمی در پروژه باقی مانده است.
• ولی در فاز فعلی تقسیم بلوک‌ها، از این task برای endpoint اصلی location_data استفاده نمی‌شود.

فایل soil_adapters.py

این فایل abstraction مربوط به تامین داده خاک را نگه می‌دارد.

کاربرد آن:

• mock provider
• live soil provider
• ساختار depth-based data fetch

در وضعیت فعلی:

• برای منطق بلوک‌بندی فعلی لازم نیست.
• اما برای جریان قدیمی یا مراحل بعدی می‌تواند دوباره استفاده شود.

فایل remote_sensing.py

این فایل مربوط به منطق سنجش‌ازدور و داده‌های ماهواره‌ای است.

در وضعیت فعلی:

• برای block layout فعلاً استفاده فعال ندارد.
• بعداً می‌تواند برای تحلیل هر بلوک یا زیر‌بلوک استفاده شود.

فایل ndvi.py

این فایل سرویس/منطق NDVI را نگه می‌دارد و برای endpoint NDVI استفاده می‌شود.

migrationها

مهم‌ترین migrationهای فعلی:

migration	توضیح
0001_initial.py	ساختار اولیه SoilLocation
0002_soildepthdata_refactor.py	جداسازی داده‌های عمقی در SoilDepthData
0004_soillocation_farm_boundary.py	اضافه شدن farm_boundary
0007_ndviobservation.py	اضافه شدن NdviObservation
0008_soillocation_block_layout.py	اضافه شدن input_block_count و block_layout

تست‌ها

فایل‌های تست اصلی:

• location_data/test_soil_api.py

  • تست ساختار محلی بلوک‌ها
  • تست پیش‌فرض یک بلوک
  • تست تغییر block_count

• location_data/test_soil_adapters.py

  • تست adapterهای خاک
  • تست ذخیره depth data

• location_data/test_ndvi_health_api.py

  • تست endpoint NDVI

ارتباط با farm_data

location_data مستقیماً توسط farm_data استفاده می‌شود.

نمونه وابستگی‌ها:

• farm_data از SoilLocation به عنوان center_location استفاده می‌کند.
• farm_boundary از سمت farm_data می‌آید.
• block_count هم از ورودی farm_data قابل ثبت است.
• farm_data فعلاً فقط location و block layout را ذخیره می‌کند و برای این بخش sync خارجی انجام نمی‌دهد.

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

الان location_data دو لایه دارد:

1. لایه فعلی فعال برای بلوک‌بندی زمین

   • محلی
   • ساده
   • بدون API خارجی
   • با input_block_count و block_layout

2. لایه قدیمی/جانبی برای خاک و NDVI

   • SoilDepthData
   • tasks.py
   • soil_adapters.py
   • NdviObservation
   • remote_sensing.py

یعنی از نظر معماری، اپ الان هم داده مکانی زمین را نگه می‌دارد و هم زیرساختی برای تحلیل خاک/NDVI دارد، ولی منطق جدید بلوک‌ها فعلاً مستقل و محلی پیاده شده است.