Update Docker Compose ports to 8081 and add new apps and URL routes for crop zoning, plant simulator, pest detection, irrigation recommendation, fertilization recommendation, and farm AI assistant.
This commit is contained in:
@@ -0,0 +1,223 @@
|
||||
# مستندات APIهای توصیه و تشخیص
|
||||
|
||||
این سند سه گروه API را شرح میدهد: **توصیه آبیاری**، **تشخیص آفت** و **توصیه کوددهی**. همهٔ پاسخها در حال حاضر از دادهٔ ثابت (mock) برگردانده میشوند و پارامترهای ورودی در پاسخ استفاده نمیشوند.
|
||||
|
||||
**پایهٔ آدرس API:** `/api/`
|
||||
|
||||
**قالب کلی پاسخ:**
|
||||
`{"status": "success", "data": <payload>}` — فقط با کد وضعیت HTTP 200.
|
||||
|
||||
---
|
||||
|
||||
## ۱. توصیه آبیاری (Irrigation Recommendation)
|
||||
|
||||
**پیشوند:** `api/irrigation-recommendation/`
|
||||
|
||||
### ۱.۱ دریافت تنظیمات (Config)
|
||||
|
||||
- **متد:** `GET`
|
||||
- **آدرس:** `api/irrigation-recommendation/config/`
|
||||
- **هدف:** برگرداندن اطلاعات مزرعه و لیست گزینههای محصول برای فرم توصیه آبیاری (هنگام بارگذاری صفحه).
|
||||
- **ورودی:** ندارد. پارامترهای query خوانده یا استفاده نمیشوند.
|
||||
|
||||
**نمونه پاسخ:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"farmInfo": {
|
||||
"soilType": "Loamy",
|
||||
"waterQuality": "Medium EC",
|
||||
"climateZone": "Temperate"
|
||||
},
|
||||
"cropOptions": [
|
||||
{"id": "wheat", "labelKey": "wheat", "icon": "tabler-wheat"},
|
||||
{"id": "corn", "labelKey": "corn", "icon": "tabler-plant-2"},
|
||||
{"id": "cotton", "labelKey": "cotton", "icon": "tabler-flower"},
|
||||
{"id": "saffron", "labelKey": "saffron", "icon": "tabler-flower-2"},
|
||||
{"id": "canola", "labelKey": "canola", "icon": "tabler-leaf"},
|
||||
{"id": "vegetables", "labelKey": "vegetables", "icon": "tabler-carrot"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| فیلد | نوع | توضیح |
|
||||
|------|-----|--------|
|
||||
| `farmInfo.soilType` | string | نوع خاک |
|
||||
| `farmInfo.waterQuality` | string | کیفیت آب (مثلاً EC) |
|
||||
| `farmInfo.climateZone` | string | منطقه اقلیمی |
|
||||
| `cropOptions` | array | لیست محصولات: `id`, `labelKey`, `icon` |
|
||||
|
||||
---
|
||||
|
||||
### ۱.۲ دریافت توصیه آبیاری (Recommend)
|
||||
|
||||
- **متد:** `POST`
|
||||
- **آدرس:** `api/irrigation-recommendation/recommend/`
|
||||
- **هدف:** برگرداندن یک برنامهٔ آبیاری ثابت (تعداد در هفته، مدت، بهترین زمان، رطوبت، هشدار).
|
||||
- **ورودی (بدن درخواست، اختیاری):** میتوانید JSON با فیلدهایی مثل `crop_id`, `soilType`, `waterQuality`, `climateZone` بفرستید؛ در پاسخ فعلی استفاده نمیشوند.
|
||||
- **CSRF:** این endpoint از CSRF معاف است (برای فراخوانی از فرانت بدون توکن).
|
||||
|
||||
**نمونه پاسخ:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"plan": {
|
||||
"frequencyPerWeek": 4,
|
||||
"durationMinutes": 45,
|
||||
"bestTimeOfDay": "05:00 - 07:00",
|
||||
"moistureLevel": 72,
|
||||
"warning": "Avoid irrigation during midday hours in the coming week due to forecasted high temperatures."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| فیلد | نوع | توضیح |
|
||||
|------|-----|--------|
|
||||
| `plan.frequencyPerWeek` | number | تعداد آبیاری در هفته |
|
||||
| `plan.durationMinutes` | number | مدت هر نوبت (دقیقه) |
|
||||
| `plan.bestTimeOfDay` | string | بهترین بازه زمانی روز |
|
||||
| `plan.moistureLevel` | number | سطح رطوبت هدف (درصد) |
|
||||
| `plan.warning` | string | هشدار یا توصیه اضافه |
|
||||
|
||||
---
|
||||
|
||||
## ۲. تشخیص آفت (Pest Detection)
|
||||
|
||||
**پیشوند:** `api/pest-detection/`
|
||||
|
||||
### ۲.۱ تحلیل تصویر (Analyze)
|
||||
|
||||
- **متد:** `POST`
|
||||
- **آدرس:** `api/pest-detection/analyze/`
|
||||
- **هدف:** برگرداندن نتیجهٔ ثابت تشخیص آفت (نام آفت، اطمینان، توضیح، درمان) — برای زمانی که کاربر تصویر گیاه را آپلود و درخواست تحلیل میکند.
|
||||
- **ورودی (بدن درخواست، اختیاری):** JSON یا form-data (مثلاً شامل `image` یا `file`). در پاسخ فعلی استفاده نمیشود.
|
||||
- **CSRF:** این endpoint از CSRF معاف است.
|
||||
|
||||
**نمونه پاسخ:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"pest": "شپشک",
|
||||
"confidence": 92,
|
||||
"description": "حشرات کوچک مکنده شیره که باعث پیچ خوردگی برگ میشوند.",
|
||||
"treatment": "یک بار در هفته از اسپری روغن نیم استفاده کنید."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| فیلد | نوع | توضیح |
|
||||
|------|-----|--------|
|
||||
| `pest` | string | نام آفت |
|
||||
| `confidence` | number | درصد اطمینان (۰–۱۰۰) |
|
||||
| `description` | string | توضیح کوتاه آفت |
|
||||
| `treatment` | string | توصیه درمان |
|
||||
|
||||
---
|
||||
|
||||
## ۳. توصیه کوددهی (Fertilization Recommendation)
|
||||
|
||||
**پیشوند:** `api/fertilization-recommendation/`
|
||||
|
||||
### ۳.۱ دریافت تنظیمات (Config)
|
||||
|
||||
- **متد:** `GET`
|
||||
- **آدرس:** `api/fertilization-recommendation/config/`
|
||||
- **هدف:** برگرداندن دادهٔ مزرعه، مراحل رشد و گزینههای محصول برای فرم توصیه کوددهی (هنگام بارگذاری صفحه).
|
||||
- **ورودی:** ندارد.
|
||||
|
||||
**نمونه پاسخ:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"farmData": {
|
||||
"soilType": "Loamy",
|
||||
"organicMatter": "Medium (2.5%)",
|
||||
"waterEC": "1.2 dS/m"
|
||||
},
|
||||
"growthStages": [
|
||||
{"id": "prePlanting", "icon": "tabler-seedling"},
|
||||
{"id": "earlyGrowth", "icon": "tabler-leaf"},
|
||||
{"id": "flowering", "icon": "tabler-flower"},
|
||||
{"id": "fruiting", "icon": "tabler-apple"},
|
||||
{"id": "postHarvest", "icon": "tabler-basket"}
|
||||
],
|
||||
"cropOptions": [
|
||||
{"id": "wheat", "labelKey": "wheat", "icon": "tabler-wheat"},
|
||||
{"id": "corn", "labelKey": "corn", "icon": "tabler-plant-2"},
|
||||
{"id": "cotton", "labelKey": "cotton", "icon": "tabler-flower"},
|
||||
{"id": "saffron", "labelKey": "saffron", "icon": "tabler-flower-2"},
|
||||
{"id": "canola", "labelKey": "canola", "icon": "tabler-leaf"},
|
||||
{"id": "vegetables", "labelKey": "vegetables", "icon": "tabler-carrot"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| فیلد | نوع | توضیح |
|
||||
|------|-----|--------|
|
||||
| `farmData.soilType` | string | نوع خاک |
|
||||
| `farmData.organicMatter` | string | ماده آلی خاک |
|
||||
| `farmData.waterEC` | string | EC آب |
|
||||
| `growthStages` | array | مراحل رشد: `id`, `icon` |
|
||||
| `cropOptions` | array | لیست محصولات: `id`, `labelKey`, `icon` |
|
||||
|
||||
---
|
||||
|
||||
### ۳.۲ دریافت توصیه کوددهی (Recommend)
|
||||
|
||||
- **متد:** `POST`
|
||||
- **آدرس:** `api/fertilization-recommendation/recommend/`
|
||||
- **هدف:** برگرداندن یک برنامهٔ کوددهی ثابت (نسبت NPK، مقدار در هکتار، روش و فاصله مصرف، استدلال).
|
||||
- **ورودی (بدن درخواست، اختیاری):** JSON با فیلدهایی مثل `crop_id`, `growth_stage`, `soilType`, `organicMatter`, `waterEC`. در پاسخ فعلی استفاده نمیشوند.
|
||||
- **CSRF:** این endpoint از CSRF معاف است.
|
||||
|
||||
**نمونه پاسخ:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"plan": {
|
||||
"npkRatio": "20-20-20 (NPK)",
|
||||
"amountPerHectare": "150 kg/ha",
|
||||
"applicationMethod": "Foliar spray + soil broadcast",
|
||||
"applicationInterval": "Every 14 days",
|
||||
"reasoning": "Your loamy soil with medium organic matter (2.5%) provides good nutrient retention. Water EC of 1.2 dS/m indicates low salinity—suitable for most crops. At the flowering stage, increased phosphorus supports bloom development. We recommend a balanced NPK to maintain nitrogen for vegetative growth while boosting phosphorous for flowering."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| فیلد | نوع | توضیح |
|
||||
|------|-----|--------|
|
||||
| `plan.npkRatio` | string | نسبت NPK پیشنهادی |
|
||||
| `plan.amountPerHectare` | string | مقدار مصرف در هکتار |
|
||||
| `plan.applicationMethod` | string | روش مصرف (مثلاً محلولپاشی، خاکی) |
|
||||
| `plan.applicationInterval` | string | فاصله بین مصرف |
|
||||
| `plan.reasoning` | string | توضیح/استدلال توصیه |
|
||||
|
||||
---
|
||||
|
||||
## خلاصه Endpointها
|
||||
|
||||
| ماژول | متد | Endpoint |
|
||||
|--------|------|----------|
|
||||
| Irrigation | GET | `/api/irrigation-recommendation/config/` |
|
||||
| Irrigation | POST | `/api/irrigation-recommendation/recommend/` |
|
||||
| Pest Detection | POST | `/api/pest-detection/analyze/` |
|
||||
| Fertilization | GET | `/api/fertilization-recommendation/config/` |
|
||||
| Fertilization | POST | `/api/fertilization-recommendation/recommend/` |
|
||||
|
||||
---
|
||||
|
||||
**توجه:** در نسخهٔ فعلی هیچ پردازش، اعتبارسنجی یا استفاده از پارامترهای ورودی در پاسخ انجام نمیشود؛ همهٔ خروجیها از دادهٔ ثابت (mock) هستند.
|
||||
Reference in New Issue
Block a user