# مستندات جداول پایگاه داده — CropLogic AI

این سند تمام جداول (مدل‌های Django) موجود در پروژه را به همراه توضیح ستون‌ها و روابط بین آن‌ها شرح می‌دهد.

---

## فهرست جداول

| اپ | جدول | توضیح کوتاه |
|---|---|---|
| `location_data` | `SoilLocation` | موقعیت جغرافیایی (lat/lon) |
| `location_data` | `SoilDepthData` | داده‌های خاک به تفکیک عمق |
| `sensor_data` | `SensorData` | آخرین خوانش سنسور برای یک موقعیت |
| `sensor_data` | `SensorDataHistory` | تاریخچه خوانش‌های سنسور |
| `sensor_data` | `SensorParameter` | تعریف پارامترهای سنسور |
| `sensor_data` | `ParameterUpdateLog` | لاگ تغییرات پارامترهای سنسور |
| `weather` | `WeatherParameter` | تعریف پارامترهای هواشناسی |
| `weather` | `WeatherForecast` | پیش‌بینی آب‌وهوای روزانه |
| `plant` | `Plant` | اطلاعات گیاهان |
| `irrigation` | `IrrigationMethod` | روش‌های آبیاری |

---

## اپ: `location_data`

### جدول `SoilLocation`

موقعیت‌های جغرافیایی که داده‌های خاک و سنسور به آن‌ها متصل هستند.

| ستون | نوع | توضیح |
|---|---|---|
| `id` | PK (auto) | شناسه اتوماتیک |
| `latitude` | DecimalField (9,6) | عرض جغرافیایی |
| `longitude` | DecimalField (9,6) | طول جغرافیایی |
| `task_id` | CharField | شناسه تسک Celery در حال پردازش |
| `created_at` | DateTimeField | زمان ایجاد |
| `updated_at` | DateTimeField | آخرین زمان به‌روزرسانی |

**محدودیت‌ها:**
- ترکیب `(latitude, longitude)` باید یکتا باشد.

**روابط:**
- ← `SoilDepthData.soil_location` (یک به چند)
- ← `SensorData.location` (یک به چند)
- ← `WeatherForecast.location` (یک به چند)

---

### جدول `SoilDepthData`

داده‌های خاک از API SoilGrids برای سه عمق مختلف، مرتبط با هر `SoilLocation`.

| ستون | نوع | توضیح |
|---|---|---|
| `id` | PK (auto) | شناسه اتوماتیک |
| `soil_location` | FK → SoilLocation | موقعیت مکانی مرتبط |
| `depth_label` | CharField | عمق: `0-5cm` / `5-15cm` / `15-30cm` |
| `bdod` | FloatField | چگالی ظاهری خاک (Bulk Density) |
| `cec` | FloatField | ظرفیت تبادل کاتیونی (CEC) |
| `cfvo` | FloatField | درصد حجمی سنگریزه |
| `clay` | FloatField | درصد رس |
| `nitrogen` | FloatField | نیتروژن کل |
| `ocd` | FloatField | تراکم کربن آلی |
| `ocs` | FloatField | ذخیره کربن آلی |
| `phh2o` | FloatField | pH خاک در آب |
| `sand` | FloatField | درصد شن |
| `silt` | FloatField | درصد سیلت |
| `soc` | FloatField | کربن آلی خاک (SOC) |
| `wv0010` | FloatField | رطوبت حجمی در ۱۰ kPa |
| `wv0033` | FloatField | ظرفیت زراعی — رطوبت در ۳۳ kPa |
| `wv1500` | FloatField | نقطه پژمردگی — رطوبت در ۱۵۰۰ kPa |
| `created_at` | DateTimeField | زمان ایجاد |

**محدودیت‌ها:**
- ترکیب `(soil_location, depth_label)` باید یکتا باشد.

---

## اپ: `sensor_data`

### جدول `SensorData`

آخرین خوانش سنسور فیزیکی برای یک موقعیت. هنگام به‌روزرسانی، نسخه قبلی به `SensorDataHistory` منتقل می‌شود.

| ستون | نوع | توضیح |
|---|---|---|
| `uuid_sensor` | UUIDField (PK) | شناسه یکتای سنسور |
| `location` | FK → SoilLocation | موقعیت مکانی (ستون DB: `location_id`) |
| `soil_moisture` | FloatField | رطوبت خاک |
| `soil_temperature` | FloatField | دمای خاک |
| `soil_ph` | FloatField | pH خاک |
| `electrical_conductivity` | FloatField | هدایت الکتریکی (EC) |
| `nitrogen` | FloatField | ازت (N) |
| `phosphorus` | FloatField | فسفر (P) |
| `potassium` | FloatField | پتاسیم (K) |
| `plants` | M2M → Plant | گیاهان مرتبط با این سنسور |
| `created_at` | DateTimeField | زمان ایجاد |
| `updated_at` | DateTimeField | آخرین زمان به‌روزرسانی |

---

### جدول `SensorDataHistory`

تاریخچه کامل خوانش‌های سنسور. هر بار که `SensorData` به‌روز می‌شود، نسخه قبلی اینجا ذخیره می‌شود.

| ستون | نوع | توضیح |
|---|---|---|
| `id` | PK (auto) | شناسه اتوماتیک |
| `uuid_sensor` | UUIDField | شناسه سنسور اصلی |
| `location_id` | IntegerField | شناسه موقعیت مکانی |
| `soil_moisture` | FloatField | رطوبت خاک |
| `soil_temperature` | FloatField | دمای خاک |
| `soil_ph` | FloatField | pH خاک |
| `electrical_conductivity` | FloatField | هدایت الکتریکی |
| `nitrogen` | FloatField | ازت |
| `phosphorus` | FloatField | فسفر |
| `potassium` | FloatField | پتاسیم |
| `recorded_at` | DateTimeField | زمان ثبت در تاریخچه |

> **نکته:** این جدول FK مستقیم به SoilLocation ندارد تا در صورت حذف موقعیت، تاریخچه حفظ شود.

---

### جدول `SensorParameter`

کاتالوگ پارامترهای قابل اندازه‌گیری توسط سنسورها.

| ستون | نوع | توضیح |
|---|---|---|
| `id` | PK (auto) | شناسه اتوماتیک |
| `code` | CharField (unique) | کد یکتا (مثال: `soil_moisture`) |
| `name_fa` | CharField | نام فارسی پارامتر |
| `unit` | CharField | واحد اندازه‌گیری |
| `created_at` | DateTimeField | زمان ایجاد |

---

### جدول `ParameterUpdateLog`

لاگ تغییرات (افزودن یا ویرایش) پارامترهای سنسور.

| ستون | نوع | توضیح |
|---|---|---|
| `id` | PK (auto) | شناسه اتوماتیک |
| `parameter` | FK → SensorParameter | پارامتر مرتبط |
| `action` | CharField | نوع عملیات: `added` یا `modified` |
| `updated_at` | DateTimeField | زمان ثبت لاگ |

---

## اپ: `weather`

### جدول `WeatherParameter`

کاتالوگ پارامترهای هواشناسی تعریف‌شده در سیستم.

| ستون | نوع | توضیح |
|---|---|---|
| `id` | PK (auto) | شناسه اتوماتیک |
| `code` | CharField (unique) | کد یکتا (مثال: `temperature_max`) |
| `name_fa` | CharField | نام فارسی پارامتر |
| `unit` | CharField | واحد اندازه‌گیری |
| `created_at` | DateTimeField | زمان ایجاد |

---

### جدول `WeatherForecast`

پیش‌بینی روزانه آب‌وهوا (تا ۷ روز آینده) برای هر موقعیت مکانی.

| ستون | نوع | توضیح |
|---|---|---|
| `id` | PK (auto) | شناسه اتوماتیک |
| `location` | FK → SoilLocation | موقعیت مکانی مرتبط |
| `forecast_date` | DateField | تاریخ پیش‌بینی |
| `temperature_min` | FloatField | حداقل دمای هوا (°C) |
| `temperature_max` | FloatField | حداکثر دمای هوا (°C) |
| `temperature_mean` | FloatField | میانگین دمای هوا (°C) |
| `precipitation` | FloatField | مجموع بارش (mm) |
| `precipitation_probability` | FloatField | احتمال بارش (%) |
| `humidity_mean` | FloatField | میانگین رطوبت نسبی (%) |
| `wind_speed_max` | FloatField | حداکثر سرعت باد (km/h) |
| `et0` | FloatField | تبخیر-تعرق مرجع ET₀ (mm/day) |
| `weather_code` | IntegerField | کد وضعیت آب‌وهوا (WMO) |
| `fetched_at` | DateTimeField | آخرین زمان واکشی از API |
| `created_at` | DateTimeField | زمان ایجاد |

**محدودیت‌ها:**
- ترکیب `(location, forecast_date)` باید یکتا باشد.

**Property:**
- `will_rain` → `True` اگر `precipitation > 0`

---

## اپ: `plant`

### جدول `Plant`

اطلاعات گیاهان شامل شرایط کاشت، نگهداری و برداشت.

| ستون | نوع | توضیح |
|---|---|---|
| `id` | PK (auto) | شناسه اتوماتیک |
| `name` | CharField (unique) | نام گیاه |
| `light` | CharField | نور مورد نیاز |
| `watering` | CharField | نیاز آبیاری |
| `soil` | CharField | نوع خاک مناسب |
| `temperature` | CharField | دمای مناسب رشد |
| `planting_season` | CharField | فصل کاشت |
| `harvest_time` | CharField | زمان برداشت |
| `spacing` | CharField | فاصله کاشت |
| `fertilizer` | CharField | کود مناسب |
| `created_at` | DateTimeField | زمان ایجاد |
| `updated_at` | DateTimeField | آخرین زمان به‌روزرسانی |

**روابط:**
- ← `SensorData.plants` (M2M از طریق جدول واسط)

---

## اپ: `irrigation`

### جدول `IrrigationMethod`

مشخصات فنی روش‌های مختلف آبیاری.

| ستون | نوع | توضیح |
|---|---|---|
| `id` | PK (auto) | شناسه اتوماتیک |
| `name` | CharField (unique) | نام روش آبیاری |
| `category` | CharField | دسته‌بندی (موضعی / تحت فشار / سطحی) |
| `description` | TextField | توضیحات کامل |
| `water_efficiency_percent` | FloatField | راندمان مصرف آب (%) |
| `water_pressure_required` | CharField | فشار مورد نیاز |
| `flow_rate` | CharField | دبی / میزان جریان آب |
| `coverage_area` | CharField | مساحت قابل پوشش |
| `soil_type` | CharField | نوع خاک مناسب |
| `climate_suitability` | CharField | اقلیم مناسب |
| `created_at` | DateTimeField | زمان ایجاد |
| `updated_at` | DateTimeField | آخرین زمان به‌روزرسانی |

---

## نمودار روابط (خلاصه)

```
SoilLocation
    ├── SoilDepthData        (1:N  —  depth_label: 0-5cm, 5-15cm, 15-30cm)
    ├── SensorData           (1:N  —  uuid_sensor PK)
    │       └── Plant        (M:N  —  جدول واسط)
    └── WeatherForecast      (1:N  —  یکتا per location+date)

SensorParameter
    └── ParameterUpdateLog   (1:N  —  action: added/modified)

Plant           (مستقل — از طریق M2M به SensorData متصل)
IrrigationMethod (مستقل — بدون FK)
WeatherParameter (مستقل — کاتالوگ)
```