Logic/Modules/Ai/fertilization/FERTILIZATION_RECOMMENDATION_API_FIELDS.md

# Fertilization Recommendation API Fields

این فایل فقط فیلدهای API مربوط به `POST /api/fertilization/recommend/` را توضیح می‌دهد.

## Endpoint

`POST /api/fertilization/recommend/`

## ساختار کلی پاسخ

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "primary_recommendation": {},
    "nutrient_analysis": {},
    "application_guide": {},
    "alternative_recommendations": [],
    "sections": []
  }
}
```

## فیلدهای Request

### `farm_uuid`
- نوع: `string`
- اجباری: بله
- توضیح: شناسه یکتای مزرعه که توصیه برای آن تولید می‌شود.

### `sensor_uuid`
- نوع: `string`
- اجباری: خیر
- توضیح: نام قدیمی برای `farm_uuid`. اگر `farm_uuid` ارسال نشده باشد، این مقدار به جای آن استفاده می‌شود.

### `crop_id`
- نوع: `string`
- اجباری: خیر
- توضیح: شناسه یا نام محصول. اگر `plant_name` ارسال نشده باشد، همین مقدار به عنوان نام گیاه استفاده می‌شود.

### `plant_name`
- نوع: `string`
- اجباری: خیر
- توضیح: نام گیاه یا محصول هدف برای تولید توصیه.

### `growth_stage`
- نوع: `string`
- اجباری: خیر
- توضیح: مرحله رشد گیاه مثل `flowering` یا `fruiting`.

### `query`
- نوع: `string`
- اجباری: خیر
- توضیح: سوال یا درخواست متنی اختیاری برای جهت دادن به توصیه.

## فیلدهای لایه اول Response

### `code`
- نوع: `number`
- توضیح: کد وضعیت پاسخ در قالب استاندارد API پروژه.

### `msg`
- نوع: `string`
- توضیح: پیام وضعیت پاسخ. در حالت موفق معمولاً `success` است.

### `data`
- نوع: `object`
- توضیح: بدنه اصلی توصیه کودهی ساختاریافته.

## فیلدهای `data`

### `primary_recommendation`
- نوع: `object`
- توضیح: پیشنهاد اصلی کودهی که فرانت باید در Hero Card و ماشین حساب مصرف از آن استفاده کند.

### `nutrient_analysis`
- نوع: `object`
- توضیح: تحلیل ساختاریافته عناصر غذایی اصلی و ریزمغذی‌ها.

### `application_guide`
- نوع: `object`
- توضیح: هشدار ایمنی و مراحل اجرای مصرف.

### `alternative_recommendations`
- نوع: `array`
- توضیح: فهرست کودهای جایگزین قابل استفاده در شرایط مشابه.

### `sections`
- نوع: `array`
- توضیح: ساختار legacy برای سازگاری با فرانت یا کلاینت‌های قدیمی.

## فیلدهای `data.primary_recommendation`

### `fertilizer_code`
- نوع: `string`
- توضیح: کد یکتای کود پیشنهادی.

### `fertilizer_name`
- نوع: `string`
- توضیح: نام اصلی کود پیشنهادی برای نمایش.

### `display_title`
- نوع: `string`
- توضیح: عنوان نمایشی آماده برای کارت اصلی.

### `fertilizer_type`
- نوع: `string`
- توضیح: نوع کود مثل `NPK`.

### `npk_ratio`
- نوع: `object`
- توضیح: نسبت NPK به صورت ساختاریافته.

### `application_method`
- نوع: `object`
- توضیح: روش مصرف کود.

### `application_interval`
- نوع: `object`
- توضیح: فاصله زمانی پیشنهادی بین دفعات مصرف.

### `dosage`
- نوع: `object`
- توضیح: مقادیر پایه مصرف که فرانت با آن‌ها مقدار مورد نیاز را حساب می‌کند.

### `reasoning`
- نوع: `string`
- توضیح: توضیح علمی و عملی درباره دلیل انتخاب این توصیه.

### `summary`
- نوع: `string`
- توضیح: خلاصه کوتاه و مناسب نمایش در بخش اصلی فرانت.

## فیلدهای `data.primary_recommendation.npk_ratio`

### `n`
- نوع: `number`
- توضیح: درصد نیتروژن در کود پیشنهادی.

### `p`
- نوع: `number`
- توضیح: درصد فسفر در کود پیشنهادی.

### `k`
- نوع: `number`
- توضیح: درصد پتاسیم در کود پیشنهادی.

### `label`
- نوع: `string`
- توضیح: نمایش متنی نسبت NPK مثل `20-20-20`.

## فیلدهای `data.primary_recommendation.application_method`

### `id`
- نوع: `string`
- توضیح: شناسه استاندارد روش مصرف مثل `fertigation` یا `foliar_fertigation`.

### `label`
- نوع: `string`
- توضیح: متن آماده نمایش برای روش مصرف.

## فیلدهای `data.primary_recommendation.application_interval`

### `value`
- نوع: `number`
- توضیح: فاصله مصرف به صورت عددی.

### `unit`
- نوع: `string`
- توضیح: واحد فاصله مصرف مثل `day`.

### `label`
- نوع: `string`
- توضیح: متن آماده نمایش مثل `هر 14 روز`.

## فیلدهای `data.primary_recommendation.dosage`

### `base_amount_per_hectare`
- نوع: `number`
- توضیح: مقدار پایه مصرف در هر هکتار.

### `base_amount_per_square_meter`
- نوع: `number`
- توضیح: مقدار پایه مصرف در هر متر مربع.

### `unit`
- نوع: `string`
- توضیح: واحد مقدار مصرف مثل `kg`.

### `label`
- نوع: `string`
- توضیح: متن آماده نمایش دوز مثل `65 کیلوگرم در هکتار`.

### `calculation_basis`
- نوع: `string`
- توضیح: مبنای محاسبه دوز؛ معمولاً نام engine یا منبع محاسبه است.

## نکته محاسبه برای فرانت

فرانت باید مقدار نهایی را خودش با استفاده از نسبت پایه محاسبه کند.

فرمول پیشنهادی:

```text
مقدار کل = base_amount_per_square_meter × مساحت مزرعه
```

## فیلدهای `data.nutrient_analysis`

### `macro`
- نوع: `array`
- توضیح: لیست عناصر اصلی شامل N، P و K.

### `micro`
- نوع: `array`
- توضیح: لیست ریزمغذی‌ها مثل آهن، روی، منگنز و غیره. ممکن است خالی باشد.

## فیلدهای هر آیتم در `data.nutrient_analysis.macro[]` و `data.nutrient_analysis.micro[]`

### `key`
- نوع: `string`
- توضیح: کلید استاندارد عنصر مثل `n`، `p`، `k`، `fe` یا `zn`.

### `name`
- نوع: `string`
- توضیح: نام نمایشی عنصر.

### `value`
- نوع: `number`
- توضیح: مقدار عنصر، معمولاً به صورت درصد.

### `unit`
- نوع: `string`
- توضیح: واحد عنصر، معمولاً `percent`.

### `description`
- نوع: `string`
- توضیح: توضیح کوتاه درباره نقش یا اهمیت آن عنصر.

## فیلدهای `data.application_guide`

### `safety_warning`
- نوع: `string`
- توضیح: هشدار ایمنی و اجرایی قبل از مصرف.

### `steps`
- نوع: `array`
- توضیح: مراحل پیشنهادی اجرا.

## فیلدهای هر آیتم در `data.application_guide.steps[]`

### `step_number`
- نوع: `number`
- توضیح: شماره مرحله اجرا.

### `title`
- نوع: `string`
- توضیح: عنوان کوتاه مرحله.

### `description`
- نوع: `string`
- توضیح: توضیح کامل مرحله.

## فیلدهای هر آیتم در `data.alternative_recommendations[]`

### `fertilizer_code`
- نوع: `string`
- توضیح: کد یکتای کود جایگزین.

### `fertilizer_name`
- نوع: `string`
- توضیح: نام کود جایگزین.

### `fertilizer_type`
- نوع: `string`
- توضیح: نوع کود جایگزین.

### `usage_method`
- نوع: `string`
- توضیح: روش مصرف کود جایگزین.

### `description`
- نوع: `string`
- توضیح: توضیح اینکه این جایگزین در چه شرایطی مفید است.

## فیلدهای هر آیتم در `data.sections[]`

### `type`
- نوع: `string`
- توضیح: نوع بخش مثل `recommendation`، `list` یا `warning`.

### `title`
- نوع: `string`
- توضیح: عنوان بخش.

### `icon`
- نوع: `string`
- توضیح: آیکون نمایشی بخش.

### `content`
- نوع: `string`
- توضیح: متن اصلی بخش.

### `items`
- نوع: `array`
- توضیح: لیست آیتم‌های متنی برای بخش‌های لیستی.

### `fertilizerType`
- نوع: `string`
- توضیح: نسخه legacy نوع کود برای نمایش در کلاینت‌های قدیمی.

### `amount`
- نوع: `string`
- توضیح: نسخه legacy مقدار مصرف برای کلاینت‌های قدیمی.

### `applicationMethod`
- نوع: `string`
- توضیح: نسخه legacy روش مصرف.

### `timing`
- نوع: `string`
- توضیح: نسخه legacy زمان مناسب اجرا.

### `validityPeriod`
- نوع: `string`
- توضیح: نسخه legacy مدت اعتبار توصیه.

### `expandableExplanation`
- نوع: `string`
- توضیح: نسخه legacy توضیح کامل‌تر برای نمایش بازشونده.

## فیلدهای حذف شده

فیلدهای زیر دیگر در خروجی اصلی استفاده نمی‌شوند:

- `recommendation_id`
- `crop`
- `growth_stage`
- `total_amount`
- `area` در request