Logic/Modules/Ai/location_data/LOCATION_DATA_FLOW.md

جریان واقعی location_data

این توضیح دقیقاً بر اساس منطق جدید نوشته شده:

• اول مختصات گوشه‌های کل زمین گرفته می‌شود
• بعد مختصات بلوک‌هایی که کشاورز خودش تعریف کرده گرفته می‌شود
• هر بلوک جداگانه به grid های 30×30 تبدیل می‌شود
• برای هر grid داده‌ی یک بازه زمانی از openEO گرفته می‌شود
• میانگین همان بازه، وضعیت نهایی همان grid حساب می‌شود
• بعد برای همان grid ها KMeans اجرا می‌شود
• برای هر K مقدار SSE / Inertia ذخیره می‌شود
• نمودار K - SSE رسم می‌شود
• نقطه‌ای که افت شیب ناگهانی دارد به عنوان تعداد مناسب زیر‌بلوک‌ها انتخاب می‌شود
• در نهایت هر بلوک کشاورز به چند زیر‌بلوک داده‌محور تقسیم می‌شود

---

1) ورودی مرحله اول

در مرحله اول این داده‌ها ثبت می‌شوند:

• مختصات گوشه‌های کل زمین
• مختصات بلوک‌هایی که کشاورز تعریف کرده
• کد هر بلوک

فایل اصلی:

• location_data/views.py
• location_data/serializers.py
• location_data/models.py

خروجی این مرحله:

• یک SoilLocation برای زمین
• یک block_layout که داخلش boundary هر بلوک هست
• یک BlockSubdivision برای هر بلوک، فقط به عنوان تعریف مرز بلوک کشاورز

نکته مهم:

• در این مرحله هیچ subdivision سنکرونی اجرا نمی‌شود
• هیچ داده خاکی از adapter قدیمی گرفته نمی‌شود

---

2) هر بلوک کشاورز جداگانه grid می‌شود

فایل اصلی:

• location_data/grid_analysis.py

اینجا چه اتفاقی می‌افتد:

• boundary هر بلوک خوانده می‌شود
• آن بلوک به cell های 30×30 متر تبدیل می‌شود
• برای هر cell یک رکورد ساخته می‌شود

مدل ذخیره:

• AnalysisGridCell

هر AnalysisGridCell این چیزها را نگه می‌دارد:

• cell_code
• block_code
• geometry
• centroid_lat
• centroid_lon
• chunk_size_sqm

یعنی از اینجا به بعد، کوچک‌ترین واحد تحلیل ما دیگر خود بلوک نیست؛ بلکه grid های 30×30 داخل هر بلوک هستند.

---

3) داده ماهواره‌ای هر grid از openEO گرفته می‌شود

فایل اصلی:

• location_data/openeo_service.py

منطق این بخش شبیه همان چیزی است که گفتی:

• برای هر بازه زمانی، cube هر سنجنده load می‌شود
• روی زمان mean_time() زده می‌شود
• بعد برای geometry هر grid از aggregate_spatial(..., reducer=\"mean\") استفاده می‌شود

یعنی:

• داده خام چند روز یا یک ماهه می‌آید
• میانگین همان بازه زمانی برای هر grid محاسبه می‌شود
• همان مقدار میانگین، وضعیت نهایی آن grid در آن بازه است

metric هایی که الان گرفته می‌شوند:

• ndvi
• ndwi
• lst_c
• soil_vv
• soil_vv_db
• dem_m
• slope_deg

نکته مهم:

• این داده‌ها برای تمام grid های یک بلوک گرفته می‌شوند
• نه فقط برای مرکز مزرعه
• نه فقط برای geometry خام

---

4) داده هر grid داخل جدول ذخیره می‌شود

فایل اصلی:

• location_data/tasks.py

مدل ذخیره:

• AnalysisGridObservation

برای هر grid و هر بازه زمانی، این داده‌ها ذخیره می‌شوند:

• ndvi
• ndwi
• lst_c
• soil_vv
• soil_vv_db
• dem_m
• slope_deg

پس هر grid یک بردار ویژگی واقعی دارد.

یعنی به زبان ساده:

• هر خانه 30×30 فقط یک polygon نیست
• یک وضعیت داده‌ای واقعی هم دارد

---

5) اینجا یادگیری بدون نظارت استفاده می‌شود

فایل اصلی:

• location_data/data_driven_subdivision.py

اینجا از:

• KMeans

استفاده می‌شود.

این بخش unsupervised است چون:

• هیچ label آماده‌ای نداریم
• فقط می‌خواهیم grid هایی که از نظر رفتار ماهواره‌ای شبیه هم هستند در یک گروه قرار بگیرند

---

6) feature matrix دقیقاً از چه چیزی ساخته می‌شود؟

هر سطر:

• یک AnalysisGridCell

هر ستون:

• یکی از feature های ماهواره‌ای

feature های پیش‌فرض:

• ndvi
• ndwi
• lst_c
• soil_vv_db
• dem_m
• slope_deg

یعنی ورودی KMeans از observation های واقعی می‌آید، نه از مختصات هندسی.

---

7) داده ناقص چطور مدیریت می‌شود؟

قبل از اجرای KMeans:

• اگر یک grid برای همه feature ها خالی باشد، حذف می‌شود
• اگر فقط بعضی feature ها خالی باشند، مقداردهی می‌شود

روش فعلی:

• median imputation

بعد از آن:

• داده‌ها استاندارد می‌شوند

روش فعلی:

• StandardScaler

این کار لازم است چون:

• مقیاس ndvi با dem_m فرق دارد
• مقیاس dem_m با lst_c فرق دارد

---

8) برای هر K مقدار SSE ذخیره می‌شود

فایل اصلی:

• location_data/data_driven_subdivision.py
• location_data/block_subdivision.py

در زمان انتخاب تعداد خوشه:

• برای K = 1, 2, 3, ...
• مدل اجرا می‌شود
• مقدار SSE / Inertia ذخیره می‌شود

این داده داخل metadata نتیجه clustering ذخیره می‌شود.

پس ما برای هر بلوک این را داریم:

• لیست K
• مقدار SSE هر K

---

9) نمودار K - SSE رسم می‌شود

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

هدف نمودار:

• ببینیم از چه جایی به بعد کم شدن SSE دیگر خیلی شدید نیست
• یعنی شیب نمودار ناگهان کمتر می‌شود

همان نقطه:

• تعداد مناسب زیر‌بلوک‌های آن بلوک است

به زبان ساده:

• اگر شیب تا K=3 خیلی زیاد کم شود
• ولی بعد از آن خیلی آرام شود
• K=3 انتخاب مناسب است

---

10) هر بلوک کشاورز جداگانه خوشه‌بندی می‌شود

این خیلی مهم است:

• کل مزرعه یکجا خوشه‌بندی نمی‌شود
• هر بلوکی که کشاورز تعریف کرده جداگانه پردازش می‌شود

پس برای هر بلوک:

1. grid های 30×30 ساخته می‌شوند
2. داده ماهواره‌ای همان grid ها گرفته می‌شود
3. observation ذخیره می‌شود
4. KMeans فقط روی grid های همان بلوک اجرا می‌شود
5. تعداد زیر‌بلوک‌های مناسب همان بلوک تعیین می‌شود

---

11) نتیجه subdivision جدید کجا ذخیره می‌شود؟

مدل اصلی نتیجه:

• RemoteSensingSubdivisionResult

این مدل چیزهای اصلی را نگه می‌دارد:

• block_code
• cluster_count
• selected_features
• skipped_cell_codes
• kmeans_params
• inertia_curve
• cluster_summaries

و برای هر grid هم assignment جدا ذخیره می‌شود در:

• RemoteSensingClusterAssignment

یعنی برای هر grid مشخص است:

• در کدام cluster قرار گرفته
• raw feature هایش چه بوده
• scaled feature هایش چه بوده

---

12) BlockSubdivision الان چه نقشی دارد؟

الان BlockSubdivision دیگر مدل اصلی خوشه‌بندی نیست.

نقشش این است که:

• boundary بلوک کشاورز را نگه دارد
• metadata بلوک را نگه دارد
• به grid سازی و pipeline کمک کند

اما نتیجه اصلی data-driven subdivision در این دو مدل ذخیره می‌شود:

• RemoteSensingSubdivisionResult
• RemoteSensingClusterAssignment

---

13) اجرای async کجا انجام می‌شود؟

فایل اصلی:

• location_data/tasks.py

این pipeline داخل Celery اجرا می‌شود.

مراحل run:

1. run ساخته می‌شود
2. grid های بلوک ساخته می‌شوند
3. داده openEO گرفته می‌شود
4. observation ها ذخیره می‌شوند
5. feature matrix ساخته می‌شود
6. KMeans اجرا می‌شود
7. نتیجه نهایی ذخیره می‌شود

مدل status:

• RemoteSensingRun

وضعیت‌هایی که track می‌شوند:

• pending
• running
• failed
• completed

---

14) چیزی که حذف شده

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

• منطق قدیمی دریافت soil depth
• adapter های خاک
• وابستگی اصلی به SoilDepthData

منبع اصلی داده از این به بعد:

• داده ماهواره‌ای هر grid

یعنی:

• به جای جدول depth-based
• جدول observation های ماهواره‌ای grid-based مرجع اصلی است

---

15) خلاصه خیلی کوتاه

جریان نهایی این است:

1. گوشه‌های زمین و بلوک‌های کشاورز ثبت می‌شوند
2. هر بلوک به grid های 30×30 تبدیل می‌شود
3. برای هر grid داده‌ی ماهواره‌ای یک بازه زمانی از openEO گرفته می‌شود
4. میانگین آن بازه، وضعیت همان grid می‌شود
5. همه grid ها در جدول observation ذخیره می‌شوند
6. برای هر بلوک، روی feature های grid ها KMeans اجرا می‌شود
7. برای هر K مقدار SSE ذخیره می‌شود
8. نمودار K - SSE ساخته می‌شود
9. elbow point تعداد مناسب زیر‌بلوک‌ها را مشخص می‌کند
10. هر بلوک کشاورز به چند زیر‌بلوک داده‌محور تقسیم می‌شود

این دقیقاً همان منطق اصلی جدید سیستم است.