UPDATE
This commit is contained in:
@@ -0,0 +1,883 @@
|
||||
# Crop Zoning Code Logic
|
||||
|
||||
این فایل یک توضیح کامل و شفاف از منطق سه فایل زیر است:
|
||||
|
||||
- `crop_zoning/views.py`
|
||||
- `crop_zoning/services.py`
|
||||
- `crop_zoning/tests.py`
|
||||
|
||||
هدف این داکیومنت این است که بدون نیاز به خواندن مستقیم کد، بتوان فهمید هر endpoint چه میکند، دادهها چگونه ساخته میشوند، taskها چگونه مدیریت میشوند، و تستها چه رفتارهایی را پوشش میدهند.
|
||||
|
||||
---
|
||||
|
||||
## تصویر کلی ماژول
|
||||
|
||||
ماژول `crop_zoning` برای این ساخته شده که:
|
||||
|
||||
1. یک polygon مربوط به زمین را دریافت یا پیدا کند.
|
||||
2. آن را به چند zone مربعی تقسیم کند.
|
||||
3. برای هر zone داده اولیه تولید کند.
|
||||
4. برای هر zone یک task پردازش جداگانه ثبت کند.
|
||||
5. خروجی مناسب برای فرانت برگرداند تا هم وضعیت پردازش را بداند و هم zoneها را روی نقشه نمایش دهد.
|
||||
|
||||
این ماژول دو نوع داده برای zoneها دارد:
|
||||
|
||||
- داده اولیه و rule-based که سریع ساخته میشود و برای خالی نبودن UI استفاده میشود.
|
||||
- داده تحلیلی که بعدا از طریق task و داده خاک تکمیل میشود.
|
||||
|
||||
---
|
||||
|
||||
## منطق `crop_zoning/views.py`
|
||||
|
||||
فایل `views.py` فقط لایه HTTP است.
|
||||
یعنی کار اصلی را خودش انجام نمیدهد، بلکه:
|
||||
|
||||
- ورودی request را میخواند
|
||||
- آن را validate میکند یا به serviceها میسپارد
|
||||
- خروجی مناسب را به صورت JSON response برمیگرداند
|
||||
|
||||
### 1) `AreaView`
|
||||
|
||||
این مهمترین endpoint ماژول است.
|
||||
|
||||
### کار این view
|
||||
|
||||
- `farm_uuid` را از query params میگیرد.
|
||||
- `page` و `page_size` را هم از query params میگیرد.
|
||||
- از service میخواهد مطمئن شود برای این sensor یک area معتبر و zoneهای آن وجود دارند.
|
||||
- اگر zoneها وجود نداشته باشند، ساخته میشوند.
|
||||
- اگر taskهای پردازش لازم باشند، dispatch میشوند.
|
||||
- در نهایت خروجی area + zoneهای همان صفحه + اطلاعات pagination را برمیگرداند.
|
||||
|
||||
### ورودیهای `AreaView`
|
||||
|
||||
- `farm_uuid`: اجباری
|
||||
- `page`: اختیاری، پیشفرض `1`
|
||||
- `page_size`: اختیاری، پیشفرض `10`
|
||||
|
||||
### خروجی `AreaView`
|
||||
|
||||
خروجی سه بخش مهم دارد:
|
||||
|
||||
- `task`: وضعیت پردازش کل area
|
||||
- `area`: polygon اصلی زمین
|
||||
- `zones`: فقط zoneهای مربوط به همان صفحه
|
||||
- `pagination`: اطلاعات صفحهبندی zoneها
|
||||
|
||||
### مدیریت خطا در `AreaView`
|
||||
|
||||
اگر هر کدام از این موارد رخ بدهد، خطای `400` داده میشود:
|
||||
|
||||
- `farm_uuid` ارسال نشده باشد
|
||||
- `farm_uuid` معتبر نباشد یا farm پیدا نشود
|
||||
- `page` نامعتبر باشد
|
||||
- `page_size` نامعتبر باشد
|
||||
|
||||
اگر تنظیمات سمت سرور مشکل داشته باشند، خطای `500` داده میشود.
|
||||
|
||||
---
|
||||
|
||||
### 2) `ProductsView`
|
||||
|
||||
این endpoint لیست محصولات قابل کشت را برمیگرداند.
|
||||
|
||||
### کار این view
|
||||
|
||||
- از service میخواهد محصولات پیشفرض داخل دیتابیس sync شوند.
|
||||
- سپس لیست محصولات را به فرمت مناسب فرانت برمیگرداند.
|
||||
|
||||
این view ساده است و منطق تحلیلی ندارد.
|
||||
|
||||
---
|
||||
|
||||
### 3) `ZonesInitialView`
|
||||
|
||||
این view برای ساخت zoneها از روی یک polygon ورودی استفاده میشود.
|
||||
|
||||
### کار این view
|
||||
|
||||
- polygon را از یکی از این کلیدها میگیرد:
|
||||
- `area`
|
||||
- `area_geojson`
|
||||
- `boundary`
|
||||
- اگر هیچکدام نباشد، از area پیشفرض mock استفاده میکند.
|
||||
- در صورت ارسال، `cell_side_km` را هم میگیرد.
|
||||
- service را صدا میزند تا area و zoneها ساخته شوند.
|
||||
- response اولیه zoneها را برمیگرداند.
|
||||
|
||||
### تفاوت با `AreaView`
|
||||
|
||||
- `AreaView` بر اساس `farm_uuid` کار میکند و وضعیت taskها را هم برمیگرداند.
|
||||
- `ZonesInitialView` بیشتر برای ساخت اولیه zoneها از روی polygon مناسب است.
|
||||
|
||||
---
|
||||
|
||||
### 4) `ZonesWaterNeedView`
|
||||
|
||||
این view لایه نیاز آبی zoneها را برمیگرداند.
|
||||
|
||||
### کار این view
|
||||
|
||||
- از request، `zoneIds` را میگیرد.
|
||||
- service را صدا میزند.
|
||||
- برای هر zone، level و value و color مربوط به آب را برمیگرداند.
|
||||
|
||||
---
|
||||
|
||||
### 5) `ZonesSoilQualityView`
|
||||
|
||||
این view لایه کیفیت خاک zoneها را برمیگرداند.
|
||||
|
||||
### خروجی اصلی
|
||||
|
||||
برای هر zone:
|
||||
|
||||
- `level`
|
||||
- `score`
|
||||
- `color`
|
||||
|
||||
---
|
||||
|
||||
### 6) `ZonesCultivationRiskView`
|
||||
|
||||
این view لایه ریسک کشت zoneها را برمیگرداند.
|
||||
|
||||
### خروجی اصلی
|
||||
|
||||
برای هر zone:
|
||||
|
||||
- `level`
|
||||
- `color`
|
||||
|
||||
---
|
||||
|
||||
### 7) `ZoneDetailsView`
|
||||
|
||||
این endpoint جزئیات یک zone را برمیگرداند.
|
||||
|
||||
### کار این view
|
||||
|
||||
- `zone_id` را از URL میگیرد.
|
||||
- جزئیات recommendation آن zone را از service میخواند.
|
||||
- اگر zone پیدا نشود، `404` برمیگرداند.
|
||||
|
||||
### خروجی اصلی
|
||||
|
||||
- crop پیشنهادی
|
||||
- درصد تطابق
|
||||
- نیاز آبی
|
||||
- سود تخمینی
|
||||
- reason
|
||||
- criteria
|
||||
- مساحت zone
|
||||
|
||||
---
|
||||
|
||||
## منطق `crop_zoning/services.py`
|
||||
|
||||
این فایل قلب اصلی ماژول است.
|
||||
بیشتر منطق واقعی اینجا پیادهسازی شده.
|
||||
|
||||
برای فهم بهتر، این فایل را میتوان به 8 بخش تقسیم کرد.
|
||||
|
||||
---
|
||||
|
||||
## بخش 1: تنظیمات و utilityهای اولیه
|
||||
|
||||
### ثابتها
|
||||
|
||||
چند constant اصلی در ابتدای فایل تعریف شدهاند:
|
||||
|
||||
- `DEFAULT_CELL_SIDE_KM`: اندازه پیشفرض ضلع هر zone
|
||||
- `DEFAULT_ZONE_PAGE_SIZE`: تعداد پیشفرض zoneها در هر صفحه response
|
||||
- `RULE_BASED_ALGORITHM`: نام الگوریتم rule-based
|
||||
- `RULE_BASED_PRODUCTS`: داده اولیه محصولات و اطلاعات نمایشی آنها
|
||||
|
||||
### `get_default_cell_side_km()`
|
||||
|
||||
این تابع اندازه پیشفرض ضلع هر zone را مشخص میکند.
|
||||
|
||||
اولویتها:
|
||||
|
||||
1. اگر `CROP_ZONE_CELL_SIDE_KM` در settings وجود داشته باشد، همان استفاده میشود.
|
||||
2. اگر نبود، از `CROP_ZONE_CHUNK_AREA_SQM` استفاده میکند و از روی آن ضلع مربع را حساب میکند.
|
||||
3. اگر هیچکدام نباشند، از `DEFAULT_CELL_SIDE_KM` استفاده میشود.
|
||||
|
||||
### `get_task_stale_seconds()`
|
||||
|
||||
این تابع مشخص میکند بعد از چند ثانیه یک task ممکن است stale محسوب شود.
|
||||
یعنی اگر task گیر کرده باشد، دوباره dispatch شود.
|
||||
|
||||
### `get_cell_side_km(cell_side_km=None)`
|
||||
|
||||
اگر کاربر اندازه zone را داده باشد، آن را validate میکند.
|
||||
اگر نداده باشد، مقدار پیشفرض را برمیگرداند.
|
||||
|
||||
### `get_chunk_area_sqm(cell_side_km=None)`
|
||||
|
||||
مساحت zone را از روی ضلع آن حساب میکند:
|
||||
|
||||
- ضلع بر حسب کیلومتر دریافت میشود
|
||||
- به متر تبدیل میشود
|
||||
- مربع آن به عنوان مساحت zone برگردانده میشود
|
||||
|
||||
### `parse_positive_int(...)`
|
||||
|
||||
برای validate کردن پارامترهای عددی مثبت استفاده میشود.
|
||||
الان برای `page` و `page_size` استفاده میشود.
|
||||
|
||||
### `get_zone_page_request_params(query_params)`
|
||||
|
||||
این تابع پارامترهای pagination را از query params میگیرد:
|
||||
|
||||
- `page`
|
||||
- `page_size`
|
||||
|
||||
اگر ارسال نشده باشند، از default استفاده میکند.
|
||||
اگر نامعتبر باشند، `ValueError` میدهد.
|
||||
|
||||
---
|
||||
|
||||
## بخش 2: آمادهسازی polygon و محاسبات هندسی
|
||||
|
||||
این بخش مسئول کار با GeoJSON و polygon است.
|
||||
|
||||
### `get_default_area_feature()`
|
||||
|
||||
یک area پیشفرض از داده mock برمیگرداند.
|
||||
|
||||
### `normalize_area_feature(area_feature)`
|
||||
|
||||
این تابع ورودی area را normalize میکند تا همیشه ساختار `Feature` داشته باشد.
|
||||
|
||||
### کارهای این تابع
|
||||
|
||||
- بررسی میکند ورودی null نباشد
|
||||
- بررسی میکند ورودی dict باشد
|
||||
- اگر ورودی از نوع `Feature` نباشد، آن را به `Feature` تبدیل میکند
|
||||
- بررسی میکند geometry از نوع `Polygon` باشد
|
||||
- بررسی میکند polygon حداقل 4 نقطه داشته باشد
|
||||
|
||||
### `get_polygon_ring(area_feature)`
|
||||
|
||||
حلقه اصلی polygon را استخراج میکند.
|
||||
|
||||
### `polygon_area_sqm(ring)`
|
||||
|
||||
مساحت polygon را به متر مربع حساب میکند.
|
||||
برای این کار نقاط جغرافیایی را به مختصات مسطح تقریبی تبدیل میکند و فرمول shoelace را اجرا میکند.
|
||||
|
||||
### `normalize_points(ring)`
|
||||
|
||||
اگر آخر polygon با نقطه اول بسته شده باشد، نقطه تکراری آخر را حذف میکند.
|
||||
|
||||
### `calculate_center(points)`
|
||||
|
||||
مرکز تقریبی polygon یا مربع را از میانگین نقاط حساب میکند.
|
||||
|
||||
### `get_bbox(points)`
|
||||
|
||||
کمینه و بیشینه طول و عرض جغرافیایی را برمیگرداند تا محدوده کلی polygon مشخص شود.
|
||||
|
||||
### `meters_to_latitude_delta(meters)` و `meters_to_longitude_delta(meters, latitude)`
|
||||
|
||||
این دو تابع فاصله متر را به اختلاف latitude و longitude تبدیل میکنند.
|
||||
برای ساخت grid مربعی از این دو تابع استفاده میشود.
|
||||
|
||||
---
|
||||
|
||||
## بخش 3: تشخیص برخورد polygon و cell
|
||||
|
||||
این بخش مشخص میکند که آیا یک مربع grid واقعا با polygon زمین برخورد دارد یا نه.
|
||||
|
||||
### `point_in_polygon(point, polygon_points)`
|
||||
|
||||
چک میکند یک نقطه داخل polygon هست یا نه.
|
||||
|
||||
### `_orientation`, `_on_segment`, `segments_intersect`
|
||||
|
||||
این توابع utilityهای هندسی برای تشخیص برخورد دو خط هستند.
|
||||
|
||||
### `rectangle_contains_point(point, cell_points)`
|
||||
|
||||
چک میکند یک نقطه داخل مربع cell قرار دارد یا نه.
|
||||
|
||||
### `polygon_intersects_cell(polygon_points, cell_points)`
|
||||
|
||||
این مهمترین تابع تقاطع است.
|
||||
اگر یکی از شرایط زیر برقرار باشد، cell معتبر در نظر گرفته میشود:
|
||||
|
||||
- مرکز cell داخل polygon باشد
|
||||
- یکی از گوشههای cell داخل polygon باشد
|
||||
- یکی از نقاط polygon داخل cell باشد
|
||||
- یکی از اضلاع polygon با اضلاع cell برخورد داشته باشد
|
||||
|
||||
نتیجه: فقط مربعهایی zone میشوند که واقعا با زمین همپوشانی داشته باشند.
|
||||
|
||||
---
|
||||
|
||||
## بخش 4: ساخت zoneها از روی area
|
||||
|
||||
### `build_square_points(...)`
|
||||
|
||||
چهار گوشه یک مربع را از روی مرزهای آن میسازد.
|
||||
|
||||
### `build_zone_square(area_points, center, zone_area_sqm)`
|
||||
|
||||
اگر area خیلی کوچک باشد یا zoneی تولید نشود، یک مربع fallback حول center area ساخته میشود.
|
||||
|
||||
### `split_area_into_zones(area_feature, cell_side_km=None)`
|
||||
|
||||
این تابع مهمترین بخش ساخت zoneها است.
|
||||
|
||||
### مراحل اجرای آن
|
||||
|
||||
1. polygon area را میگیرد.
|
||||
2. center و bbox و total area را حساب میکند.
|
||||
3. اندازه ضلع zone را مشخص میکند.
|
||||
4. روی bbox یک grid مربعی میسازد.
|
||||
5. هر cell را با `polygon_intersects_cell` بررسی میکند.
|
||||
6. اگر cell با polygon تقاطع داشته باشد، یک zone جدید میسازد.
|
||||
7. برای هر zone این دادهها تولید میشود:
|
||||
- `zone_id`
|
||||
- `geometry`
|
||||
- `points`
|
||||
- `center`
|
||||
- `area_sqm`
|
||||
- `area_hectares`
|
||||
- `sequence`
|
||||
8. اگر هیچ zoneی ساخته نشود، یک zone fallback میسازد.
|
||||
9. در نهایت area summary و لیست zoneها را برمیگرداند.
|
||||
|
||||
### نکته مهم
|
||||
|
||||
در این پروژه zoneها grid-based هستند، نه بر اساس تقسیم واقعی shape زمین.
|
||||
یعنی ابتدا grid مربعی ساخته میشود و بعد فقط مربعهایی که با زمین برخورد دارند نگه داشته میشوند.
|
||||
|
||||
---
|
||||
|
||||
## بخش 5: تولید recommendation و لایههای تحلیلی
|
||||
|
||||
این بخش داده پیشنهادی هر zone را تولید میکند.
|
||||
|
||||
### `build_rule_based_zone_metrics(index, coords)`
|
||||
|
||||
این تابع بدون نیاز به API خارجی، برای هر zone یک recommendation اولیه میسازد.
|
||||
|
||||
### هدف آن
|
||||
|
||||
وقتی zone تازه ساخته میشود، فرانت از همان ابتدا داده خالی نداشته باشد.
|
||||
|
||||
### خروجی آن
|
||||
|
||||
- `recommended_crop`
|
||||
- `match_percent`
|
||||
- `water_need_level`
|
||||
- `water_need_value`
|
||||
- `soil_quality_score`
|
||||
- `soil_level`
|
||||
- `cultivation_risk_level`
|
||||
- `estimated_profit`
|
||||
- `reason`
|
||||
- `criteria`
|
||||
|
||||
این دادهها از روی مختصات zone و `sequence` به صورت deterministic ساخته میشوند.
|
||||
|
||||
### `build_initial_zone_payload(zone)`
|
||||
|
||||
خروجی سبک و اولیه برای endpoint ساخت zoneها تولید میکند.
|
||||
|
||||
### `build_area_zone_payload(zone)`
|
||||
|
||||
خروجی کاملتر برای `AreaView` تولید میکند و این بخشها را شامل میشود:
|
||||
|
||||
- geometry
|
||||
- center
|
||||
- area
|
||||
- processing status
|
||||
- crop recommendation
|
||||
- water layer
|
||||
- soil layer
|
||||
- risk layer
|
||||
|
||||
### `persist_zone_analysis_metrics(zone, metrics)`
|
||||
|
||||
metrics را داخل مدلهای مختلف ذخیره میکند:
|
||||
|
||||
- recommendation
|
||||
- criteria
|
||||
- water need layer
|
||||
- soil quality layer
|
||||
- cultivation risk layer
|
||||
|
||||
### `ensure_rule_based_zone_data(zone, force=False)`
|
||||
|
||||
اگر zone هنوز recommendation نداشته باشد، با rule-based data آن را پر میکند.
|
||||
|
||||
---
|
||||
|
||||
## بخش 6: تحلیل خاک واقعی و ذخیره نتیجه
|
||||
|
||||
### `_get_level_color_map(...)`
|
||||
|
||||
رنگ هر level را برای سه لایه water / soil / risk برمیگرداند.
|
||||
|
||||
### `_pick_level(...)`
|
||||
|
||||
از روی score مشخص میکند level برابر `low` یا `medium` یا `high` است.
|
||||
|
||||
### `_format_range(...)`
|
||||
|
||||
برای ساخت رشتههایی مثل `3000-4000 m³/ha` استفاده میشود.
|
||||
|
||||
### `_derive_analysis_metrics(depths)`
|
||||
|
||||
این تابع از داده depthهای خاک، recommendation نهایی را میسازد.
|
||||
|
||||
### ورودی آن
|
||||
|
||||
آرایهای از depthها که از سرویس خارجی خاک میآید.
|
||||
|
||||
### محاسبات مهم آن
|
||||
|
||||
از میانگین این فیلدها استفاده میکند:
|
||||
|
||||
- `phh2o`
|
||||
- `soc`
|
||||
- `clay`
|
||||
- `nitrogen`
|
||||
- `wv0033`
|
||||
|
||||
بعد از اینها محاسبه میشود:
|
||||
|
||||
- کیفیت خاک
|
||||
- نیاز آبی
|
||||
- ریسک کشت
|
||||
- محصول پیشنهادی
|
||||
- درصد تطابق
|
||||
- reason
|
||||
- criteria
|
||||
|
||||
### `fetch_soil_data_for_zone(zone)`
|
||||
|
||||
برای یک zone به سرویس خارجی AI درخواست میزند و داده خاک میگیرد.
|
||||
|
||||
### payload ارسالی
|
||||
|
||||
- longitude
|
||||
- latitude
|
||||
- geometry zone
|
||||
- center
|
||||
- area
|
||||
|
||||
### `analyze_and_store_zone_soil_data(zone_id)`
|
||||
|
||||
این تابع منطق اصلی پردازش هر zone در worker است.
|
||||
|
||||
### مراحل آن
|
||||
|
||||
1. zone از دیتابیس خوانده میشود.
|
||||
2. اگر قبلا کامل شده باشد، دوباره کاری نمیکند.
|
||||
3. status روی `processing` میرود.
|
||||
4. از API خارجی داده خاک میگیرد.
|
||||
5. depthها را استخراج میکند.
|
||||
6. recommendation واقعیتر را از روی خاک میسازد.
|
||||
7. نتیجه را داخل مدلهای analysis و recommendation ذخیره میکند.
|
||||
8. status را `completed` میکند.
|
||||
9. اگر هر خطایی رخ دهد، status روی `failed` میرود و متن خطا ذخیره میشود.
|
||||
|
||||
---
|
||||
|
||||
## بخش 7: مدیریت taskهای zone
|
||||
|
||||
چون هر zone جداگانه پردازش میشود، باید taskها مدیریت شوند.
|
||||
|
||||
### `_get_stale_zone_ids(zones)`
|
||||
|
||||
این تابع zoneهایی را پیدا میکند که task آنها stale شده است.
|
||||
|
||||
### چه zoneهایی stale محسوب میشوند؟
|
||||
|
||||
- zone کامل نشده باشد
|
||||
- task_id داشته باشد
|
||||
- task خیلی قدیمی شده باشد
|
||||
- یا task_id آن با task یک zone completed مشترک باشد
|
||||
- یا state task در celery یکی از stateهای نامعتبر برای ادامه باشد
|
||||
|
||||
### `dispatch_zone_processing_tasks(crop_area_id=None, zone_ids=None, force=False)`
|
||||
|
||||
این تابع برای zoneهای انتخابشده task celery ثبت میکند.
|
||||
|
||||
### رفتار آن
|
||||
|
||||
- zoneهای completed را رد میکند
|
||||
- اگر zone pending/processing باشد و task_id معتبر داشته باشد، دوباره dispatch نمیکند مگر `force=True`
|
||||
- برای هر zone یک task جدا ثبت میکند
|
||||
- اگر celery broker در دسترس نباشد، باز هم یک `task_id` محلی تولید میکند
|
||||
- متن خطا را در `processing_error` ذخیره میکند
|
||||
|
||||
### اهمیت این طراحی
|
||||
|
||||
این باعث میشود:
|
||||
|
||||
- هر zone مستقل پردازش شود
|
||||
- fail شدن یک zone بقیه را متوقف نکند
|
||||
- فرانت بتواند وضعیت هر zone را جدا ببیند
|
||||
|
||||
---
|
||||
|
||||
## بخش 8: ساخت area، بازیابی area و ساخت payload response
|
||||
|
||||
### `create_missing_zones_for_area(crop_area)`
|
||||
|
||||
اگر area در دیتابیس وجود داشته باشد ولی zoneهایش از بین رفته باشند یا ساخته نشده باشند، دوباره از روی geometry آن zoneها را میسازد.
|
||||
|
||||
### `get_farm_for_uuid(farm_uuid)`
|
||||
|
||||
اعتبارسنجی میکند که:
|
||||
|
||||
- `farm_uuid` ارسال شده باشد
|
||||
- farm واقعا در دیتابیس وجود داشته باشد
|
||||
|
||||
### `ensure_latest_area_ready_for_processing(farm_uuid, area_feature=None)`
|
||||
|
||||
این یکی از مهمترین توابع کل فایل است.
|
||||
|
||||
### منطق آن
|
||||
|
||||
1. sensor را پیدا میکند.
|
||||
2. آخرین area مربوط به آن sensor را میگیرد.
|
||||
3. اگر area وجود نداشته باشد:
|
||||
- area پیشفرض یا area ورودی را میگیرد
|
||||
- area و zoneها را میسازد
|
||||
- taskها را dispatch میکند
|
||||
4. اگر area وجود داشته باشد:
|
||||
- مطمئن میشود zoneها وجود دارند
|
||||
- برای هر zone، rule-based data را در صورت نبود ایجاد میکند
|
||||
- zoneهای stale را پیدا میکند
|
||||
- zoneهای لازم را دوباره dispatch میکند
|
||||
- area تازه از دیتابیس خوانده میشود و برگردانده میشود
|
||||
|
||||
### نتیجه این تابع
|
||||
|
||||
وقتی `AreaView` این تابع را صدا میزند، همیشه یک area آماده برای نمایش و پردازش دارد.
|
||||
|
||||
### `create_zones_and_dispatch(area_feature, cell_side_km=None, sensor=None)`
|
||||
|
||||
این تابع area جدید را میسازد.
|
||||
|
||||
### مراحل آن
|
||||
|
||||
1. productها sync میشوند.
|
||||
2. area normalize میشود.
|
||||
3. area به zoneها تقسیم میشود.
|
||||
4. داخل transaction:
|
||||
- یک `CropArea` ساخته میشود
|
||||
- همه `CropZone`ها bulk create میشوند
|
||||
5. zoneها دوباره از دیتابیس خوانده میشوند
|
||||
6. rule-based data برای هر zone ساخته میشود
|
||||
7. taskهای پردازش dispatch میشوند
|
||||
8. area و zones برگردانده میشوند
|
||||
|
||||
### `_zones_queryset(zone_ids=None)`
|
||||
|
||||
یک queryset آماده برمیگرداند که relationهای لازم را از قبل load میکند:
|
||||
|
||||
- recommendation
|
||||
- product
|
||||
- criteria
|
||||
- water layer
|
||||
- soil layer
|
||||
- risk layer
|
||||
|
||||
این باعث میشود responseسازی سریعتر و با query کمتر انجام شود.
|
||||
|
||||
### `get_latest_area_payload(area=None, page=1, page_size=DEFAULT_ZONE_PAGE_SIZE)`
|
||||
|
||||
این تابع خروجی نهایی `AreaView` را میسازد.
|
||||
|
||||
### کارهای این تابع
|
||||
|
||||
1. area را پیدا میکند.
|
||||
2. وضعیت همه zoneها را میخواند.
|
||||
3. تعداد completed / pending / processing / failed را حساب میکند.
|
||||
4. `task.status` را تعیین میکند.
|
||||
5. `stage` و `stage_label` را تعیین میکند.
|
||||
6. درصد پیشرفت را حساب میکند.
|
||||
7. zoneهای همان صفحه را با slicing برمیدارد.
|
||||
8. `pagination` را میسازد.
|
||||
9. payload نهایی را برمیگرداند.
|
||||
|
||||
### منطق `task.status`
|
||||
|
||||
- اگر zone failed داشته باشیم: `FAILURE`
|
||||
- اگر همه complete باشند: `SUCCESS`
|
||||
- اگر بخشی complete یا processing باشند: `PROCESSING`
|
||||
- در غیر این صورت: `PENDING`
|
||||
|
||||
### منطق pagination
|
||||
|
||||
- `page` و `page_size` از request گرفته میشوند
|
||||
- `total_pages` از تقسیم تعداد کل zoneها بر `page_size` محاسبه میشود
|
||||
- فقط zoneهای همان بازه برگردانده میشوند
|
||||
- اطلاعات page فعلی، تعداد صفحات و وجود صفحه قبل/بعد در body قرار میگیرد
|
||||
|
||||
### `get_initial_zones_payload(crop_area)`
|
||||
|
||||
payload سادهتر برای endpoint اولیه zoneها میسازد.
|
||||
|
||||
### `get_water_need_payload(zone_ids=None)`
|
||||
|
||||
خروجی لایه نیاز آبی را برمیگرداند.
|
||||
|
||||
### `get_soil_quality_payload(zone_ids=None)`
|
||||
|
||||
خروجی لایه کیفیت خاک را برمیگرداند.
|
||||
|
||||
### `get_cultivation_risk_payload(zone_ids=None)`
|
||||
|
||||
خروجی لایه ریسک کشت را برمیگرداند.
|
||||
|
||||
### `get_zone_details_payload(zone_id)`
|
||||
|
||||
خروجی دیتیل یک zone را میسازد.
|
||||
|
||||
---
|
||||
|
||||
## جریان کامل اجرای `GET /api/crop-zoning/area/`
|
||||
|
||||
اگر بخواهیم کل flow را از ابتدا تا انتها خیلی ساده توضیح بدهیم:
|
||||
|
||||
1. فرانت `farm_uuid` و احتمالا `page` و `page_size` را میفرستد.
|
||||
2. `AreaView` پارامترها را میخواند.
|
||||
3. `ensure_latest_area_ready_for_processing` اجرا میشود.
|
||||
4. اگر area وجود نداشته باشد، area و zoneها ساخته میشوند.
|
||||
5. اگر zoneها ناقص باشند، کامل میشوند.
|
||||
6. اگر recommendation اولیه نباشد، ساخته میشود.
|
||||
7. اگر taskهای لازم وجود نداشته باشند یا stale باشند، dispatch میشوند.
|
||||
8. `get_latest_area_payload` اجرا میشود.
|
||||
9. وضعیت کلی task و zoneهای صفحه فعلی ساخته میشود.
|
||||
10. response نهایی به فرانت برمیگردد.
|
||||
|
||||
---
|
||||
|
||||
## منطق `crop_zoning/tests.py`
|
||||
|
||||
این فایل تست رفتار کلیدی API را پوشش میدهد.
|
||||
|
||||
تستها با `Django TestCase` و `APIRequestFactory` نوشته شدهاند.
|
||||
|
||||
### تنظیمات مشترک تستها
|
||||
|
||||
در تستها از این تنظیمات استفاده شده:
|
||||
|
||||
- `USE_EXTERNAL_API_MOCK=True`
|
||||
- `CROP_ZONE_CHUNK_AREA_SQM=200000`
|
||||
|
||||
هدف این است که:
|
||||
|
||||
- وابستگی به API خارجی واقعی حذف شود
|
||||
- zoneها با اندازه مشخص و قابل پیشبینی ساخته شوند
|
||||
|
||||
---
|
||||
|
||||
## کلاس `ZonesInitialViewTests`
|
||||
|
||||
### `test_post_accepts_area_geojson_alias`
|
||||
|
||||
این تست بررسی میکند که اگر polygon با کلید `area_geojson` ارسال شود:
|
||||
|
||||
- endpoint آن را قبول کند
|
||||
- پاسخ `200` بدهد
|
||||
- zone ساخته شود
|
||||
- تعداد zoneهای خروجی با `zone_count` یکسان باشد
|
||||
|
||||
این تست در عمل alias بودن `area_geojson` را validate میکند.
|
||||
|
||||
---
|
||||
|
||||
## کلاس `AreaViewTests`
|
||||
|
||||
این کلاس رفتارهای اصلی `AreaView` را تست میکند.
|
||||
|
||||
### `setUp`
|
||||
|
||||
در شروع هر تست:
|
||||
|
||||
- یک user ساخته میشود
|
||||
- یک sensor برای آن user ساخته میشود
|
||||
- `APIRequestFactory` آماده میشود
|
||||
|
||||
### `_create_area(...)`
|
||||
|
||||
یک helper برای ساخت سریع `CropArea` در تستها است.
|
||||
|
||||
### `_request()`
|
||||
|
||||
یک request استاندارد برای `AreaView` با `farm_uuid` معتبر میسازد.
|
||||
|
||||
### `_request_with_pagination(page, page_size)`
|
||||
|
||||
یک request برای تست pagination میسازد.
|
||||
|
||||
---
|
||||
|
||||
### تستهای اصلی `AreaView`
|
||||
|
||||
#### `test_get_requires_farm_uuid`
|
||||
|
||||
بررسی میکند اگر `farm_uuid` ارسال نشود، پاسخ `400` برگردد.
|
||||
|
||||
#### `test_get_returns_pending_task_status_until_all_zones_complete`
|
||||
|
||||
بررسی میکند اگر zoneها pending و processing باشند:
|
||||
|
||||
- status کلی `PROCESSING` باشد
|
||||
- area برگردد
|
||||
- zoneها در response باشند
|
||||
- فیلد `processing_status` برای zone موجود باشد
|
||||
|
||||
#### `test_get_returns_area_when_all_tasks_complete`
|
||||
|
||||
بررسی میکند وقتی همه zoneها complete باشند:
|
||||
|
||||
- status کلی `SUCCESS` باشد
|
||||
- zoneها برگردند
|
||||
- فیلدهای recommendation و layerها موجود باشند
|
||||
|
||||
#### `test_get_returns_paginated_zones`
|
||||
|
||||
تست جدید pagination است.
|
||||
|
||||
بررسی میکند که:
|
||||
|
||||
- با `page=2` و `page_size=1`
|
||||
- فقط zone دوم برگردد
|
||||
- اطلاعات pagination درست باشد
|
||||
- `total_pages`, `has_next`, `has_previous` درست باشند
|
||||
|
||||
#### `test_get_rejects_invalid_pagination_params`
|
||||
|
||||
بررسی میکند اگر `page=0` باشد:
|
||||
|
||||
- پاسخ `400` بدهد
|
||||
- پیام خطا مناسب برگردد
|
||||
|
||||
#### `test_get_dispatches_zone_task_when_task_id_is_missing`
|
||||
|
||||
با mock کردن `dispatch_zone_processing_tasks` بررسی میکند که:
|
||||
|
||||
- اگر zone task_id نداشته باشد
|
||||
- در زمان فراخوانی `AreaView`
|
||||
- dispatch انجام شود
|
||||
|
||||
#### `test_get_creates_area_when_sensor_has_no_data`
|
||||
|
||||
با mock کردن `create_zones_and_dispatch` بررسی میکند که:
|
||||
|
||||
- اگر sensor هنوز area نداشته باشد
|
||||
- سیستم area جدید بسازد
|
||||
- همان sensor را به service پاس بدهد
|
||||
|
||||
#### `test_each_zone_gets_its_own_task`
|
||||
|
||||
بررسی میکند برای دو zone جدا:
|
||||
|
||||
- دو task مستقل ایجاد شود
|
||||
- هر zone task_id جدا داشته باشد
|
||||
|
||||
این تست خیلی مهم است چون تایید میکند taskها shared نیستند و per-zone هستند.
|
||||
|
||||
#### `test_get_generates_local_task_id_when_broker_is_unavailable`
|
||||
|
||||
با mock کردن celery و ایجاد `OperationalError` بررسی میکند که:
|
||||
|
||||
- حتی وقتی broker در دسترس نیست
|
||||
- سیستم task_id محلی بسازد
|
||||
- response خراب نشود
|
||||
- وضعیت کلی درست بماند
|
||||
|
||||
#### `test_get_stores_task_id_and_reuses_it_on_next_request`
|
||||
|
||||
بررسی میکند:
|
||||
|
||||
- وقتی اولین request task_id را ثبت کرد
|
||||
- request بعدی دوباره task تازه نسازد
|
||||
- همان task_id قبلی reuse شود
|
||||
|
||||
این تست جلوی dispatch تکراری را میگیرد.
|
||||
|
||||
#### `test_get_redispatches_pending_zone_when_shared_task_already_completed`
|
||||
|
||||
این تست سناریوی قدیمی یا خراب را پوشش میدهد.
|
||||
|
||||
سناریو:
|
||||
|
||||
- یک zone completed شده
|
||||
- zone دیگر pending مانده
|
||||
- هر دو task_id یکسان دارند
|
||||
|
||||
در این حالت سیستم باید zone stale را دوباره dispatch کند.
|
||||
|
||||
این تست نشان میدهد منطق stale detection واقعا کار میکند.
|
||||
|
||||
---
|
||||
|
||||
## جمعبندی معماری
|
||||
|
||||
اگر خیلی خلاصه بخواهیم نقش هر فایل را بگوییم:
|
||||
|
||||
### `views.py`
|
||||
|
||||
لایه HTTP است.
|
||||
|
||||
- request را میگیرد
|
||||
- service مناسب را صدا میزند
|
||||
- response برمیگرداند
|
||||
|
||||
### `services.py`
|
||||
|
||||
لایه business logic است.
|
||||
|
||||
- area را validate میکند
|
||||
- polygon را به zone تبدیل میکند
|
||||
- recommendation اولیه و نهایی میسازد
|
||||
- taskها را مدیریت میکند
|
||||
- payload response را میسازد
|
||||
|
||||
### `tests.py`
|
||||
|
||||
لایه اطمینان از رفتار سیستم است.
|
||||
|
||||
- ساخت area
|
||||
- ساخت zone
|
||||
- status task
|
||||
- dispatch task
|
||||
- stale task
|
||||
- pagination
|
||||
- خطاهای ورودی
|
||||
|
||||
را تست میکند.
|
||||
|
||||
---
|
||||
|
||||
## نکات مهم برای فرانت
|
||||
|
||||
- endpoint `area` الان pagination دارد و `zones` همیشه همه zoneها را برنمیگرداند.
|
||||
- تعداد کل zoneها از `task.total_zones` یا `pagination.total_zones` قابل خواندن است.
|
||||
- تعداد کل صفحهها از `pagination.total_pages` قابل خواندن است.
|
||||
- برای نمایش progress باید از `task.progress_percent` و `task.status` استفاده شود.
|
||||
- `task.status` وضعیت کلی area است، نه وضعیت تکتک zoneها.
|
||||
- وضعیت هر zone داخل `processing_status` قرار دارد.
|
||||
- در صورت نیاز به جزئیات بیشتر برای یک zone باید `ZoneDetailsView` صدا زده شود.
|
||||
|
||||
---
|
||||
|
||||
## نکات مهم برای بکاند
|
||||
|
||||
- منطق grid سازی و پردازش zoneها تقریبا کامل داخل `services.py` متمرکز شده است.
|
||||
- `AreaView` عمدا thin نگه داشته شده تا business logic وارد view نشود.
|
||||
- rule-based data نقش fallback سریع برای UI را دارد.
|
||||
- data واقعیتر بعدا با taskهای تحلیل خاک جایگزین یا تکمیل میشود.
|
||||
- تستها بیشتر روی پایداری flow پردازش و task dispatch تمرکز دارند.
|
||||
|
||||
Reference in New Issue
Block a user