Ai/fertilization/FERTILIZATION_RECOMMENDATION_API_FIELDS.md

Fertilization Recommendation API Fields

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

Endpoint

POST /api/fertilization/recommend/

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

{
  "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 یا منبع محاسبه است.

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

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

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

مقدار کل = 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