1534 lines
33 KiB
Markdown
1534 lines
33 KiB
Markdown
# مستند کامل APIهای CropLogic AI
|
|
|
|
این فایل مرجع اجرایی APIهای پروژه است و بر اساس کد فعلی `config/urls.py`، `views.py` و `serializers.py` تهیه شده است.
|
|
|
|
## نکات کلی
|
|
|
|
- پیشوند تمام APIها: `/api/`
|
|
- اکثر endpointها خروجی را در envelope زیر برمیگردانند:
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {}
|
|
}
|
|
```
|
|
|
|
- بعضی endpointهای AI علاوه بر داده نهایی، این فیلدها را هم برمیگردانند:
|
|
- `raw_response`: متن خام خروجی مدل
|
|
- `knowledge_base`: نام knowledge base مرتبط
|
|
- در چند endpoint قدیمی، بهجای `farm_uuid` میتوان `sensor_uuid` فرستاد؛ در صورت وجود، backend آن را به `farm_uuid` تبدیل میکند.
|
|
- فیلدهایی که در این داکیومنت با برچسب `الزامی` آمدهاند، باید حتما ارسال شوند.
|
|
|
|
---
|
|
|
|
## 1) RAG
|
|
|
|
### 1.1) چت RAG
|
|
|
|
- مسیر: `POST /api/rag/chat/`
|
|
- نوع خروجی: `application/json`
|
|
|
|
#### ورودی
|
|
|
|
- `farm_uuid` — `string` — الزامی
|
|
- `query` — `string` — اختیاری، ولی اگر تصویر نفرستید عملا الزامی است
|
|
- `message` — `string` — نام قدیمی `query`
|
|
- `history` — `array | string(JSON)` — اختیاری
|
|
- `image_urls` — `array` — اختیاری
|
|
- `image` — `file` — اختیاری
|
|
- `images` — `file[]` — اختیاری
|
|
|
|
#### قواعد الزامی
|
|
|
|
- اگر `query/message` خالی باشد و هیچ تصویری ارسال نشده باشد، درخواست `400` میگیرد
|
|
- `farm_uuid` نباید خالی باشد
|
|
- `history` باید آرایه باشد یا رشته JSON معتبرِ آرایه
|
|
|
|
#### خروجی موفق
|
|
|
|
- خروجی این endpoint بهصورت JSON ساختاریافته برمیگردد
|
|
- پاسخ موفق داخل `data` شامل آرایه `sections` است
|
|
|
|
#### شکل خروجی
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"sections": [
|
|
{
|
|
"type": "recommendation",
|
|
"title": "جمع بندي اصلي",
|
|
"icon": "message-circle",
|
|
"content": "خلاصه يک جمله اي از بهترين پاسخ يا اقدام اصلي",
|
|
"primaryAction": "اقدام اصلي پيشنهادي",
|
|
"timing": "بهترين زمان اجرا يا بررسي",
|
|
"validityPeriod": "مدت اعتبار اين پاسخ يا توصيه",
|
|
"expandableExplanation": "توضيح روشن درباره دليل پاسخ با ارجاع به داده مزرعه، آب و هوا، گياه و شبيه سازي"
|
|
},
|
|
{
|
|
"type": "list",
|
|
"title": "نکات اجرايي",
|
|
"icon": "list",
|
|
"items": [
|
|
"نکته عملي 1",
|
|
"نکته عملي 2"
|
|
]
|
|
},
|
|
{
|
|
"type": "warning",
|
|
"title": "هشدار يا محدوديت",
|
|
"icon": "alert-triangle",
|
|
"content": "هشدار کوتاه و کاربردي"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `400`: ورودی نامعتبر، `farm_uuid` خالی، `history` نامعتبر، `query` خالی
|
|
- `404`: `farm` پیدا نشد
|
|
|
|
---
|
|
|
|
## 2) Farm Alerts
|
|
|
|
### 2.1) Tracker هشدارهای مزرعه
|
|
|
|
- مسیر: `POST /api/farm-alerts/tracker/`
|
|
|
|
#### ورودی
|
|
|
|
- `farm_uuid` — `string` — الزامی
|
|
- `sensor_uuid` — `string` — اختیاری، alias
|
|
- `query` — `string` — اختیاری
|
|
|
|
#### خروجی موفق
|
|
|
|
خروجی این endpoint برای نمایش وضعیت هشدارهای مزرعه به این شکل است:
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"headline": "string",
|
|
"overview": "string",
|
|
"status_level": "info | warning | danger",
|
|
"notifications": []
|
|
}
|
|
}
|
|
```
|
|
|
|
`notifications` معمولا رکوردهای ذخیرهشده هشدار یا هشدارهای نرمالشده را برمیگرداند.
|
|
|
|
#### خطاها
|
|
|
|
- `400`: نبودن `farm_uuid`
|
|
- `500`: خطا در تولید tracker
|
|
|
|
---
|
|
|
|
### 2.2) Timeline هشدارهای مزرعه
|
|
|
|
- مسیر: `POST /api/farm-alerts/timeline/`
|
|
|
|
#### ورودی
|
|
|
|
- `farm_uuid` — `string` — الزامی
|
|
- `sensor_uuid` — `string` — اختیاری، alias
|
|
- `query` — `string` — اختیاری
|
|
|
|
#### خروجی موفق
|
|
|
|
خروجی این endpoint برای نمایش timeline هشدارها به این شکل است:
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"headline": "string",
|
|
"overview": "string",
|
|
"timeline": [],
|
|
"notifications": []
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `400`: نبودن `farm_uuid`
|
|
- `500`: خطا در تولید timeline
|
|
|
|
---
|
|
|
|
## 3) Soil Data
|
|
|
|
### 3.1) دریافت داده خاک با GET
|
|
|
|
- مسیر: `GET /api/soil-data/?lat=...&lon=...`
|
|
|
|
#### ورودی
|
|
|
|
- `lat` — `decimal(9,6)` — الزامی
|
|
- `lon` — `decimal(9,6)` — الزامی
|
|
|
|
#### خروجی موفق از دیتابیس
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"source": "database",
|
|
"id": 1,
|
|
"lon": 51.400000,
|
|
"lat": 35.700000,
|
|
"depths": [
|
|
{
|
|
"depth_label": "0-5cm",
|
|
"bdod": null,
|
|
"cec": null,
|
|
"cfvo": null,
|
|
"clay": 22.0,
|
|
"nitrogen": 14.0,
|
|
"ocd": null,
|
|
"ocs": null,
|
|
"phh2o": 6.6,
|
|
"sand": 40.0,
|
|
"silt": 25.0,
|
|
"soc": null,
|
|
"wv0010": 0.41,
|
|
"wv0033": 0.28,
|
|
"wv1500": 0.12
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خروجی وقتی داده هنوز آماده نیست
|
|
|
|
```json
|
|
{
|
|
"code": 202,
|
|
"msg": "تسک در صف. وضعیت را با task_id بررسی کنید.",
|
|
"data": {
|
|
"source": "task",
|
|
"task_id": "string",
|
|
"lon": 51.4,
|
|
"lat": 35.7,
|
|
"status_url": "/api/soil-data/tasks/<task_id>/status/"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `400`: نبودن `lat/lon` یا نامعتبر بودن آنها
|
|
|
|
---
|
|
|
|
### 3.2) دریافت داده خاک با POST
|
|
|
|
- مسیر: `POST /api/soil-data/`
|
|
|
|
#### ورودی
|
|
|
|
- `lat` — `decimal(9,6)` — الزامی
|
|
- `lon` — `decimal(9,6)` — الزامی
|
|
|
|
#### خروجی
|
|
|
|
- دقیقا مشابه endpoint قبلی
|
|
|
|
---
|
|
|
|
### 3.3) وضعیت تسک داده خاک
|
|
|
|
- مسیر: `GET /api/soil-data/tasks/<task_id>/status/`
|
|
|
|
#### ورودی
|
|
|
|
- `task_id` از path — الزامی
|
|
|
|
#### خروجی موفق
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"task_id": "string",
|
|
"status": "PENDING | PROGRESS | SUCCESS | FAILURE",
|
|
"message": "...",
|
|
"progress": {},
|
|
"result": {},
|
|
"error": "..."
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 3.4) NDVI سلامت مزرعه
|
|
|
|
- مسیر: `POST /api/soil-data/ndvi-health/`
|
|
|
|
#### ورودی
|
|
|
|
- `farm_uuid` — `uuid` — الزامی
|
|
|
|
#### خروجی موفق
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"ndviIndex": 0.73,
|
|
"mean_ndvi": 0.73,
|
|
"ndvi_map": {},
|
|
"vegetation_health_class": "Healthy",
|
|
"observation_date": "2026-04-10",
|
|
"satellite_source": "sentinel-2",
|
|
"healthData": [
|
|
{
|
|
"title": "string",
|
|
"value": {},
|
|
"color": "string",
|
|
"icon": "string"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `400`: ورودی نامعتبر
|
|
- `404`: مزرعه پیدا نشد
|
|
|
|
---
|
|
|
|
## 4) Soile
|
|
|
|
### 4.1) Heatmap رطوبت خاک
|
|
|
|
- مسیر: `POST /api/soile/moisture-heatmap/`
|
|
|
|
#### ورودی
|
|
|
|
- `farm_uuid` — `uuid` — الزامی
|
|
|
|
#### خروجی موفق
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"farm_uuid": "string",
|
|
"location": {},
|
|
"current_sensor": {},
|
|
"soil_profile": [],
|
|
"timestamp": "string | null",
|
|
"grid_resolution": {},
|
|
"grid_cells": [],
|
|
"sensor_points": [],
|
|
"quality_legend": {}
|
|
}
|
|
}
|
|
```
|
|
|
|
خروجی واقعی معمولا علاوه بر موارد بالا شامل `depth_layers`, `model_metadata`, `summary` هم هست.
|
|
|
|
#### خطاها
|
|
|
|
- `400`: ورودی نامعتبر
|
|
- `404`: مزرعه پیدا نشد
|
|
|
|
---
|
|
|
|
### 4.2) خلاصه سلامت خاک
|
|
|
|
- مسیر: `POST /api/soile/health-summary/`
|
|
|
|
#### ورودی
|
|
|
|
- `farm_uuid` — `uuid` — الزامی
|
|
|
|
#### خروجی موفق
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"farm_uuid": "string",
|
|
"healthScore": 82,
|
|
"profileSource": "Tomato",
|
|
"healthScoreDetails": {},
|
|
"healthLanguage": {},
|
|
"avgSoilMoisture": 46,
|
|
"avgSoilMoistureRaw": 46.0,
|
|
"avgSoilMoistureStatus": "بهینه"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `400`: ورودی نامعتبر
|
|
- `404`: مزرعه پیدا نشد
|
|
|
|
---
|
|
|
|
### 4.3) تحلیل ناهنجاری خاک
|
|
|
|
- مسیر: `POST /api/soile/anomaly-detection/`
|
|
|
|
#### ورودی
|
|
|
|
- `farm_uuid` — `uuid` — الزامی
|
|
|
|
#### خروجی موفق
|
|
|
|
خروجی این endpoint شامل تحلیل ناهنجاری خاک به همراه metadata تکمیلی است:
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"farm_uuid": "string",
|
|
"summary": "جمع بندی کوتاه ناهنجاری",
|
|
"explanation": "توضیح کوتاه",
|
|
"likely_cause": "علت محتمل",
|
|
"recommended_action": "اقدام عملی",
|
|
"monitoring_priority": "low | medium | high | urgent",
|
|
"confidence": 0.0,
|
|
"generated_at": "string",
|
|
"anomalies": [],
|
|
"interpretation": {},
|
|
"knowledge_base": "string | null",
|
|
"raw_response": "string | null"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `400`: ورودی نامعتبر
|
|
- `404`: مزرعه پیدا نشد
|
|
- `500`: خطا در تحلیل
|
|
|
|
---
|
|
|
|
## 5) Farm Data
|
|
|
|
### 5.1) ایجاد/آپدیت farm data
|
|
|
|
- مسیر: `POST /api/farm-data/`
|
|
|
|
#### ورودی
|
|
|
|
- `farm_uuid` — `uuid` — الزامی
|
|
- `farm_boundary` — `object` — الزامی
|
|
- `sensor_key` — `string` — اختیاری، پیشفرض: `sensor-7-1`
|
|
- `sensor_payload` — `object` — اختیاری
|
|
- `plant_ids` — `integer[]` — اختیاری
|
|
- `irrigation_method_id` — `integer | null` — اختیاری
|
|
|
|
#### نکته مهم
|
|
|
|
- حداقل یکی از این سه فیلد باید ارسال شود:
|
|
- `sensor_payload`
|
|
- `plant_ids`
|
|
- `irrigation_method_id`
|
|
|
|
#### ساختار `farm_boundary`
|
|
|
|
دو فرم اصلی در کد پشتیبانی میشود:
|
|
|
|
1. GeoJSON Polygon
|
|
|
|
```json
|
|
{
|
|
"type": "Polygon",
|
|
"coordinates": [
|
|
[
|
|
[51.39, 35.70],
|
|
[51.41, 35.70],
|
|
[51.41, 35.72],
|
|
[51.39, 35.72],
|
|
[51.39, 35.70]
|
|
]
|
|
]
|
|
}
|
|
```
|
|
|
|
2. corners
|
|
|
|
```json
|
|
{
|
|
"corners": [
|
|
{"lat": 35.70, "lon": 51.39},
|
|
{"lat": 35.70, "lon": 51.41},
|
|
{"lat": 35.72, "lon": 51.41},
|
|
{"lat": 35.72, "lon": 51.39}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### ساختار `sensor_payload`
|
|
|
|
```json
|
|
{
|
|
"sensor-7-1": {
|
|
"soil_moisture": 45.2,
|
|
"soil_temperature": 22.5,
|
|
"soil_ph": 6.8,
|
|
"electrical_conductivity": 1.2,
|
|
"nitrogen": 30.0,
|
|
"phosphorus": 15.0,
|
|
"potassium": 20.0
|
|
},
|
|
"leaf-sensor": {
|
|
"leaf_wetness": 11.0
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خروجی موفق
|
|
|
|
بخش `insight` این endpoint خلاصه تحلیلی و عملیاتی نیاز آبی را برمیگرداند:
|
|
|
|
```json
|
|
{
|
|
"code": 201,
|
|
"msg": "success",
|
|
"data": {
|
|
"farm_uuid": "uuid",
|
|
"center_location_id": 1,
|
|
"weather_forecast_id": 10,
|
|
"sensor_payload": {},
|
|
"plant_ids": [1, 2],
|
|
"irrigation_method_id": 3,
|
|
"created_at": "datetime",
|
|
"updated_at": "datetime"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `400`: ورودی نامعتبر، boundary نامعتبر، `sensor_payload` نامعتبر
|
|
- `502`: خطا در sync دادههای بیرونی خاک/آبوهوا
|
|
|
|
---
|
|
|
|
### 5.2) جزئیات کامل farm
|
|
|
|
- مسیر: `GET /api/farm-data/<farm_uuid>/detail/`
|
|
|
|
#### ورودی
|
|
|
|
- `farm_uuid` در path — الزامی
|
|
|
|
#### خروجی موفق
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"center_location": {
|
|
"id": 1,
|
|
"lat": 35.700000,
|
|
"lon": 51.400000,
|
|
"farm_boundary": {}
|
|
},
|
|
"weather": {
|
|
"id": 10,
|
|
"forecast_date": "2026-04-10",
|
|
"temperature_min": 12.0,
|
|
"temperature_max": 23.0,
|
|
"temperature_mean": 18.0,
|
|
"precipitation": 1.2,
|
|
"precipitation_probability": 35.0,
|
|
"humidity_mean": 52.0,
|
|
"wind_speed_max": 11.0,
|
|
"et0": 3.4,
|
|
"weather_code": 0
|
|
},
|
|
"sensor_payload": {},
|
|
"soil": {
|
|
"resolved_metrics": {},
|
|
"metric_sources": {},
|
|
"depths": []
|
|
},
|
|
"plant_ids": [1, 2],
|
|
"plants": [],
|
|
"irrigation_method_id": 3,
|
|
"irrigation_method": {},
|
|
"created_at": "datetime",
|
|
"updated_at": "datetime"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `404`: farm یافت نشد
|
|
|
|
---
|
|
|
|
### 5.3) تعریف/ویرایش پارامتر سنسور
|
|
|
|
- مسیر: `POST /api/farm-data/parameters/`
|
|
|
|
#### ورودی
|
|
|
|
- `sensor_key` — `string` — اختیاری، پیشفرض `sensor-7-1`
|
|
- `code` — `string` — الزامی
|
|
- `name_fa` — `string` — الزامی
|
|
- `unit` — `string` — اختیاری
|
|
- `data_type` — `string` — اختیاری، پیشفرض `float`
|
|
- `metadata` — `object` — اختیاری
|
|
|
|
#### خروجی موفق
|
|
|
|
```json
|
|
{
|
|
"code": 201,
|
|
"msg": "success",
|
|
"data": {
|
|
"id": 1,
|
|
"sensor_key": "sensor-7-1",
|
|
"code": "soil_moisture",
|
|
"name_fa": "رطوبت خاک",
|
|
"unit": "%",
|
|
"data_type": "float",
|
|
"metadata": {},
|
|
"created_at": "datetime",
|
|
"action": "added | modified"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `400`: ورودی نامعتبر
|
|
|
|
---
|
|
|
|
## 6) Weather
|
|
|
|
### 6.1) کارت آبوهوای مزرعه
|
|
|
|
- مسیر: `POST /api/weather/farm-card/`
|
|
|
|
#### ورودی
|
|
|
|
- `farm_uuid` — `uuid` — الزامی
|
|
|
|
#### خروجی موفق
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"condition": "صاف",
|
|
"temperature": 28.0,
|
|
"unit": "°C",
|
|
"humidity": 42.0,
|
|
"windSpeed": 15.0,
|
|
"windUnit": "km/h",
|
|
"chartData": {
|
|
"labels": ["2026-04-01", "2026-04-02"],
|
|
"series": [[28.0, 29.0]]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `400`: ورودی نامعتبر
|
|
- `404`: مزرعه یافت نشد
|
|
|
|
---
|
|
|
|
### 6.2) پیشبینی نیاز آبی
|
|
|
|
- مسیر: `POST /api/weather/water-need-prediction/`
|
|
|
|
#### ورودی
|
|
|
|
- `farm_uuid` — `uuid` — الزامی
|
|
|
|
#### خروجی موفق
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"farm_uuid": "string",
|
|
"totalNext7Days": 24.6,
|
|
"unit": "mm",
|
|
"categories": ["روز 1", "روز 2"],
|
|
"series": [],
|
|
"dailyBreakdown": [],
|
|
"insight": {
|
|
"summary": "جمع بندی نیاز آبی بازه کوتاه مدت",
|
|
"irrigation_outlook": "برداشت عملیاتی از روند آبیاری روزهای آینده",
|
|
"recommended_action": "اقدام عملی پیشنهادی برای آبیاری",
|
|
"risk_note": "ریسک یا عدم قطعیت مهم",
|
|
"confidence": 0.0
|
|
},
|
|
"knowledge_base": "water_need_prediction",
|
|
"raw_response": "..."
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `400`: ورودی نامعتبر
|
|
- `404`: مزرعه یافت نشد
|
|
- `500`: خطا در تحلیل
|
|
|
|
---
|
|
|
|
## 7) Economy
|
|
|
|
### 7.1) نمای اقتصادی مزرعه
|
|
|
|
- مسیر: `POST /api/economy/overview/`
|
|
|
|
#### ورودی
|
|
|
|
- `farm_uuid` — `uuid` — الزامی
|
|
|
|
#### خروجی موفق
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"farm_uuid": "string",
|
|
"source": "mock",
|
|
"economicData": [
|
|
{
|
|
"title": "string",
|
|
"value": "string",
|
|
"subtitle": "string",
|
|
"avatarIcon": "string",
|
|
"avatarColor": "string"
|
|
}
|
|
],
|
|
"chartSeries": [
|
|
{
|
|
"name": "string",
|
|
"data": [1.0, 2.0]
|
|
}
|
|
],
|
|
"chartCategories": ["فروردین", "اردیبهشت"]
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `400`: ورودی نامعتبر
|
|
|
|
---
|
|
|
|
## 8) Plants
|
|
|
|
### 8.1) لیست گیاهان
|
|
|
|
- مسیر: `GET /api/plants/`
|
|
|
|
#### خروجی موفق
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "گوجهفرنگی",
|
|
"light": "آفتاب کامل",
|
|
"watering": "منظم",
|
|
"soil": "لومی",
|
|
"temperature": "20-30",
|
|
"growth_stage": "رویشی",
|
|
"planting_season": "بهار",
|
|
"harvest_time": "70-90 روز",
|
|
"spacing": "45-60 سانتیمتر",
|
|
"fertilizer": "NPK",
|
|
"created_at": "datetime",
|
|
"updated_at": "datetime"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 8.2) ایجاد گیاه
|
|
|
|
- مسیر: `POST /api/plants/`
|
|
|
|
#### ورودی
|
|
|
|
- `name` — `string` — الزامی
|
|
- `light` — `string` — اختیاری
|
|
- `watering` — `string` — اختیاری
|
|
- `soil` — `string` — اختیاری
|
|
- `temperature` — `string` — اختیاری
|
|
- `growth_stage` — `string` — اختیاری
|
|
- `planting_season` — `string` — اختیاری
|
|
- `harvest_time` — `string` — اختیاری
|
|
- `spacing` — `string` — اختیاری
|
|
- `fertilizer` — `string` — اختیاری
|
|
|
|
#### خروجی موفق
|
|
|
|
- همان ساختار `PlantSerializer`
|
|
- status: `201`
|
|
|
|
#### خطاها
|
|
|
|
- `400`: ورودی نامعتبر
|
|
|
|
---
|
|
|
|
### 8.3) جزئیات گیاه
|
|
|
|
- مسیر: `GET /api/plants/<pk>/`
|
|
|
|
#### خروجی موفق
|
|
|
|
- همان `PlantSerializer`
|
|
|
|
#### خطاها
|
|
|
|
- `404`: گیاه یافت نشد
|
|
|
|
---
|
|
|
|
### 8.4) ویرایش کامل گیاه
|
|
|
|
- مسیر: `PUT /api/plants/<pk>/`
|
|
|
|
#### ورودی
|
|
|
|
- تمام فیلدهای `PlantSerializer`
|
|
- عملا `name` باید وجود داشته باشد
|
|
|
|
#### خروجی موفق
|
|
|
|
- همان `PlantSerializer`
|
|
|
|
#### خطاها
|
|
|
|
- `400`: ورودی نامعتبر
|
|
- `404`: گیاه یافت نشد
|
|
|
|
---
|
|
|
|
### 8.5) ویرایش جزئی گیاه
|
|
|
|
- مسیر: `PATCH /api/plants/<pk>/`
|
|
|
|
#### ورودی
|
|
|
|
- هر زیرمجموعهای از فیلدهای `PlantSerializer`
|
|
|
|
#### خروجی موفق
|
|
|
|
- همان `PlantSerializer`
|
|
|
|
#### خطاها
|
|
|
|
- `400`, `404`
|
|
|
|
---
|
|
|
|
### 8.6) حذف گیاه
|
|
|
|
- مسیر: `DELETE /api/plants/<pk>/`
|
|
|
|
#### خروجی موفق
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "گیاه با موفقیت حذف شد.",
|
|
"data": null
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `404`: گیاه یافت نشد
|
|
|
|
---
|
|
|
|
### 8.7) دریافت اطلاعات گیاه از API خارجی
|
|
|
|
- مسیر: `POST /api/plants/fetch-info/`
|
|
|
|
#### ورودی
|
|
|
|
- `name` — `string` — الزامی
|
|
|
|
#### خروجی موفق
|
|
|
|
- object شامل اطلاعات گیاه
|
|
- ساختار مورد انتظار مشابه `PlantSerializer` است
|
|
|
|
#### خطاها
|
|
|
|
- `400`: نام گیاه ارسال نشده
|
|
- `503`: سرویس خارجی در دسترس نیست یا پیادهسازی نشده
|
|
|
|
---
|
|
|
|
## 9) Pest & Disease
|
|
|
|
### 9.1) تشخیص آفت/بیماری از روی تصویر
|
|
|
|
- مسیر: `POST /api/pest-disease/detect/`
|
|
|
|
#### ورودی
|
|
|
|
- `farm_uuid` — `string` — الزامی
|
|
- `sensor_uuid` — `string` — اختیاری
|
|
- `plant_name` — `string` — اختیاری
|
|
- `query` — `string` — اختیاری
|
|
- `image_urls` — `array` — اختیاری
|
|
- `image` — `file` — اختیاری
|
|
- `images` — `file[]` — اختیاری
|
|
|
|
#### قاعده مهم
|
|
|
|
- حداقل یک تصویر باید به یکی از این روشها ارسال شود: `image_urls` یا `image` یا `images`
|
|
|
|
#### خروجی موفق
|
|
|
|
خروجی این endpoint برای تشخیص آفت/بیماری از روی تصویر به این شکل است:
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"has_issue": true,
|
|
"category": "pest | disease | nutrient_stress | abiotic_stress | no_issue | unknown",
|
|
"confidence": 0.0,
|
|
"severity": "low | medium | high",
|
|
"summary": "جمع بندی کوتاه تشخیص",
|
|
"detected_signs": [],
|
|
"possible_causes": [],
|
|
"immediate_actions": [],
|
|
"reasoning": []
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `400`: نبودن `farm_uuid` یا نبودن تصویر
|
|
- `500`: خطا در تحلیل تصویر
|
|
|
|
---
|
|
|
|
### 9.2) پیشبینی ریسک آفات و بیماری
|
|
|
|
- مسیر: `POST /api/pest-disease/risk/`
|
|
|
|
#### ورودی
|
|
|
|
- `farm_uuid` — `string` — الزامی
|
|
- `sensor_uuid` — `string` — اختیاری
|
|
- `plant_name` — `string` — اختیاری
|
|
- `growth_stage` — `string` — اختیاری
|
|
- `query` — `string` — اختیاری
|
|
|
|
#### خروجی موفق
|
|
|
|
خروجی این endpoint برای پیش بینی ریسک آفات و بیماری به این شکل است:
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"summary": "جمع بندی کوتاه ریسک",
|
|
"forecast_window": "بازه زمانی",
|
|
"overall_risk": "low | medium | high",
|
|
"disease_risk": {
|
|
"score": 0.0,
|
|
"level": "low | medium | high",
|
|
"likely_conditions": [],
|
|
"reasoning": []
|
|
},
|
|
"pest_risk": {
|
|
"score": 0.0,
|
|
"level": "low | medium | high",
|
|
"likely_conditions": [],
|
|
"reasoning": []
|
|
},
|
|
"key_drivers": [],
|
|
"recommended_actions": []
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `400`: نبودن `farm_uuid`
|
|
- `500`: خطا در پیشبینی
|
|
|
|
---
|
|
|
|
## 10) Irrigation
|
|
|
|
### 10.1) لیست روشهای آبیاری
|
|
|
|
- مسیر: `GET /api/irrigation/`
|
|
|
|
#### خروجی موفق
|
|
|
|
- آرایهای از `IrrigationMethodSerializer`
|
|
|
|
#### فیلدهای هر آیتم
|
|
|
|
- `id`
|
|
- `name`
|
|
- `category`
|
|
- `description`
|
|
- `water_efficiency_percent`
|
|
- `water_pressure_required`
|
|
- `flow_rate`
|
|
- `coverage_area`
|
|
- `soil_type`
|
|
- `climate_suitability`
|
|
- `created_at`
|
|
- `updated_at`
|
|
|
|
---
|
|
|
|
### 10.2) ایجاد روش آبیاری
|
|
|
|
- مسیر: `POST /api/irrigation/`
|
|
|
|
#### ورودی
|
|
|
|
- `name` — `string` — الزامی
|
|
- `category` — `string` — اختیاری
|
|
- `description` — `string` — اختیاری
|
|
- `water_efficiency_percent` — `float | null` — اختیاری
|
|
- `water_pressure_required` — `string` — اختیاری
|
|
- `flow_rate` — `string` — اختیاری
|
|
- `coverage_area` — `string` — اختیاری
|
|
- `soil_type` — `string` — اختیاری
|
|
- `climate_suitability` — `string` — اختیاری
|
|
|
|
#### خروجی موفق
|
|
|
|
- همان `IrrigationMethodSerializer`
|
|
|
|
#### خطاها
|
|
|
|
- `400`: ورودی نامعتبر
|
|
|
|
---
|
|
|
|
### 10.3) جزئیات روش آبیاری
|
|
|
|
- مسیر: `GET /api/irrigation/<pk>/`
|
|
|
|
#### خروجی موفق
|
|
|
|
- همان `IrrigationMethodSerializer`
|
|
|
|
#### خطاها
|
|
|
|
- `404`: یافت نشد
|
|
|
|
---
|
|
|
|
### 10.4) ویرایش کامل روش آبیاری
|
|
|
|
- مسیر: `PUT /api/irrigation/<pk>/`
|
|
|
|
#### ورودی
|
|
|
|
- تمام فیلدهای `IrrigationMethodSerializer`
|
|
|
|
#### خروجی موفق
|
|
|
|
- همان `IrrigationMethodSerializer`
|
|
|
|
#### خطاها
|
|
|
|
- `400`, `404`
|
|
|
|
---
|
|
|
|
### 10.5) ویرایش جزئی روش آبیاری
|
|
|
|
- مسیر: `PATCH /api/irrigation/<pk>/`
|
|
|
|
#### ورودی
|
|
|
|
- هر زیرمجموعهای از فیلدهای `IrrigationMethodSerializer`
|
|
|
|
#### خروجی موفق
|
|
|
|
- همان `IrrigationMethodSerializer`
|
|
|
|
#### خطاها
|
|
|
|
- `400`, `404`
|
|
|
|
---
|
|
|
|
### 10.6) حذف روش آبیاری
|
|
|
|
- مسیر: `DELETE /api/irrigation/<pk>/`
|
|
|
|
#### خروجی موفق
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "روش آبیاری با موفقیت حذف شد.",
|
|
"data": null
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `404`: یافت نشد
|
|
|
|
---
|
|
|
|
### 10.7) توصیه آبیاری
|
|
|
|
- مسیر: `POST /api/irrigation/recommend/`
|
|
|
|
#### ورودی
|
|
|
|
- `farm_uuid` — `string` — الزامی
|
|
- `sensor_uuid` — `string` — اختیاری
|
|
- `plant_name` — `string` — اختیاری
|
|
- `growth_stage` — `string` — اختیاری
|
|
- `irrigation_method_name` — `string` — اختیاری
|
|
- `query` — `string` — اختیاری
|
|
|
|
#### خروجی موفق
|
|
|
|
این endpoint فقط آبجکت نهایی و قابل استفاده برای کشاورز را برمیگرداند و فیلدهای داخلی مثل `simulation_optimizer`، `water_balance`، `mergeMetadata`، `selected_irrigation_method` و `raw_response` در پاسخ public نمایش داده نمیشوند. خروجی نهایی به این شکل است:
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"sections": [
|
|
{
|
|
"type": "recommendation",
|
|
"title": "برنامه آبیاری بهینه",
|
|
"icon": "droplet",
|
|
"content": "خلاصه یک جمله ای از بهترین سناریوی شبیه سازی",
|
|
"frequency": "تعداد نوبت آبیاری در بازه اعتبار",
|
|
"amount": "مقدار آب در هر نوبت و جمع کل",
|
|
"timing": "بهترین زمان اجرا",
|
|
"validityPeriod": "مدت اعتبار دقیق توصیه",
|
|
"expandableExplanation": "توضیح دلیل انتخاب این سناریو با ارجاع به تنش آبی، دما، بارش و شبیه سازی"
|
|
},
|
|
{
|
|
"type": "list",
|
|
"title": "اقدامات اجرایی",
|
|
"icon": "list",
|
|
"items": ["نکته عملی 1", "نکته عملی 2"]
|
|
},
|
|
{
|
|
"type": "warning",
|
|
"title": "هشدار آبیاری",
|
|
"icon": "alert-triangle",
|
|
"content": "هشدار کوتاه و کاربردی"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `400`: نبودن `farm_uuid`
|
|
- `500`: خطا در تولید توصیه
|
|
|
|
---
|
|
|
|
### 10.8) شاخص تنش آبی
|
|
|
|
- مسیر: `POST /api/irrigation/water-stress/`
|
|
|
|
#### ورودی
|
|
|
|
- `farm_uuid` — `string` — الزامی
|
|
- `sensor_uuid` — `string` — اختیاری
|
|
|
|
#### خروجی موفق
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"farm_uuid": "string",
|
|
"waterStressIndex": 12,
|
|
"level": "پایین",
|
|
"sourceMetric": {}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `400`: نبودن `farm_uuid`
|
|
- `404`: مزرعه پیدا نشد
|
|
|
|
---
|
|
|
|
## 11) Fertilization
|
|
|
|
### 11.1) توصیه کودهی
|
|
|
|
- مسیر: `POST /api/fertilization/recommend/`
|
|
|
|
#### ورودی
|
|
|
|
- `farm_uuid` — `string` — الزامی
|
|
- `sensor_uuid` — `string` — اختیاری
|
|
- `plant_name` — `string` — اختیاری
|
|
- `growth_stage` — `string` — اختیاری
|
|
- `query` — `string` — اختیاری
|
|
|
|
#### خروجی موفق
|
|
|
|
این endpoint فقط خروجی نهایی بهینه شده و آماده استفاده را برمیگرداند و جزئیات داخلی مثل `simulation_optimizer`، `mergeMetadata` و `raw_response` را در پاسخ public برنمیگرداند. خروجی نهایی به این شکل است:
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"sections": [
|
|
{
|
|
"type": "recommendation",
|
|
"title": "برنامه کودهی بهینه",
|
|
"icon": "leaf",
|
|
"content": "خلاصه یک جمله ای از سناریوی منتخب",
|
|
"fertilizerType": "نوع کود پیشنهادی",
|
|
"amount": "مقدار مصرف دقیق",
|
|
"applicationMethod": "روش مصرف",
|
|
"timing": "بهترین زمان اجرا",
|
|
"validityPeriod": "مدت اعتبار این توصیه",
|
|
"expandableExplanation": "دلیل انتخاب این سناریو بر اساس کمبود عناصر، pH، مرحله رشد و شبیه سازی"
|
|
},
|
|
{
|
|
"type": "list",
|
|
"title": "نکات اجرایی و اختلاط",
|
|
"icon": "list",
|
|
"items": ["نکته عملی 1", "نکته عملی 2"]
|
|
},
|
|
{
|
|
"type": "warning",
|
|
"title": "هشدار کودهی",
|
|
"icon": "alert-triangle",
|
|
"content": "هشدار کوتاه و کاربردی"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `400`: نبودن `farm_uuid`
|
|
- `500`: خطا در تولید توصیه
|
|
|
|
---
|
|
|
|
## 12) Crop Simulation
|
|
|
|
### 12.1) شروع شبیهسازی رشد
|
|
|
|
- مسیر: `POST /api/crop-simulation/growth/`
|
|
|
|
#### ورودی
|
|
|
|
- `plant_name` — `string` — الزامی
|
|
- `dynamic_parameters` — `string[]` — الزامی و نباید خالی باشد
|
|
- `farm_uuid` — `uuid | null` — اختیاری
|
|
- `weather` — `object | array` — اختیاری
|
|
- `soil_parameters` — `object` — اختیاری
|
|
- `site_parameters` — `object` — اختیاری
|
|
- `crop_parameters` — `object` — اختیاری
|
|
- `agromanagement` — `object` — اختیاری
|
|
- `page_size` — `integer` — اختیاری، بین 1 تا 50
|
|
|
|
#### قاعده مهم
|
|
|
|
- حداقل یکی از `farm_uuid` یا `weather` باید ارسال شود
|
|
|
|
#### خروجی موفق
|
|
|
|
```json
|
|
{
|
|
"code": 202,
|
|
"msg": "تسک شبیه سازی رشد در صف قرار گرفت.",
|
|
"data": {
|
|
"task_id": "string",
|
|
"status_url": "/api/crop-simulation/growth/<task_id>/status/",
|
|
"plant_name": "گوجهفرنگی"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `400`: ورودی نامعتبر
|
|
|
|
---
|
|
|
|
### 12.2) وضعیت شبیهسازی رشد
|
|
|
|
- مسیر: `GET /api/crop-simulation/growth/<task_id>/status/`
|
|
|
|
#### query params
|
|
|
|
- `page` — `integer` — اختیاری
|
|
- `page_size` — `integer` — اختیاری
|
|
|
|
#### خروجی موفق
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"task_id": "string",
|
|
"status": "PENDING | PROGRESS | SUCCESS | FAILURE",
|
|
"message": "string",
|
|
"progress": {},
|
|
"result": {
|
|
"plant_name": "string",
|
|
"dynamic_parameters": ["DVS", "LAI"],
|
|
"engine": "string | null",
|
|
"model_name": "string | null",
|
|
"scenario_id": 1,
|
|
"simulation_warning": "",
|
|
"summary_metrics": {},
|
|
"stage_timeline": [],
|
|
"stages_page": [],
|
|
"pagination": {
|
|
"page": 1,
|
|
"page_size": 10,
|
|
"total_items": 2,
|
|
"total_pages": 1,
|
|
"has_next": false,
|
|
"has_previous": false
|
|
},
|
|
"daily_records_count": 51,
|
|
"default_page_size": 10
|
|
},
|
|
"error": "string"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 12.3) chart وضعیت فعلی مزرعه
|
|
|
|
- مسیر: `POST /api/crop-simulation/current-farm-chart/`
|
|
|
|
#### ورودی
|
|
|
|
- `farm_uuid` — `uuid` — الزامی
|
|
- `plant_name` — `string` — اختیاری
|
|
|
|
#### خروجی موفق
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"farm_uuid": "string | null",
|
|
"plant_name": "string",
|
|
"engine": "string | null",
|
|
"model_name": "string | null",
|
|
"scenario_id": 1,
|
|
"simulation_warning": "",
|
|
"categories": [],
|
|
"series": {},
|
|
"summary": {},
|
|
"current_state": {},
|
|
"metrics": {},
|
|
"daily_output": {}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `400`: ورودی نامعتبر
|
|
- `500`: خطا در اجرای chart
|
|
|
|
---
|
|
|
|
### 12.4) پیشبینی برداشت
|
|
|
|
- مسیر: `POST /api/crop-simulation/harvest-prediction/`
|
|
|
|
#### ورودی
|
|
|
|
- `farm_uuid` — `uuid` — الزامی
|
|
- `plant_name` — `string` — اختیاری
|
|
|
|
#### خروجی موفق
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"date": "2026-07-15",
|
|
"dateFormatted": "15 Jul 2026",
|
|
"daysUntil": 96,
|
|
"description": "string",
|
|
"optimalWindowStart": "2026-07-10",
|
|
"optimalWindowEnd": "2026-07-20",
|
|
"gddDetails": {}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `400`, `500`
|
|
|
|
---
|
|
|
|
### 12.5) پیشبینی عملکرد
|
|
|
|
- مسیر: `POST /api/crop-simulation/yield-prediction/`
|
|
|
|
#### ورودی
|
|
|
|
- `farm_uuid` — `uuid` — الزامی
|
|
- `plant_name` — `string` — اختیاری
|
|
|
|
#### خروجی موفق
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "success",
|
|
"data": {
|
|
"farm_uuid": "string",
|
|
"plant_name": "string | null",
|
|
"predictedYieldTons": 8.4,
|
|
"predictedYieldRaw": 8400.0,
|
|
"unit": "t/ha",
|
|
"sourceUnit": "kg/ha",
|
|
"simulationEngine": "string | null",
|
|
"simulationModel": "string | null",
|
|
"scenarioId": 1,
|
|
"simulationWarning": "",
|
|
"supportingMetrics": {}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### خطاها
|
|
|
|
- `400`, `500`
|
|
|
|
---
|
|
|
|
## 13) وضعیت کدهای HTTP
|
|
|
|
- `200` — موفق
|
|
- `201` — ایجاد/آپدیت موفق
|
|
- `202` — تسک async در صف قرار گرفت
|
|
- `400` — ورودی نامعتبر یا فیلد الزامی ارسال نشده
|
|
- `404` — رکورد/مزرعه/گیاه پیدا نشد
|
|
- `500` — خطای داخلی در پردازش تحلیلی
|
|
- `502` — خطا در sync داده بیرونی
|
|
- `503` — سرویس خارجی در دسترس نیست
|
|
|
|
---
|
|
|
|
## 14) endpointهای نهایی بهصورت خلاصه
|
|
|
|
- `POST /api/rag/chat/`
|
|
- `POST /api/farm-alerts/tracker/`
|
|
- `POST /api/farm-alerts/timeline/`
|
|
- `GET /api/soil-data/`
|
|
- `POST /api/soil-data/`
|
|
- `GET /api/soil-data/tasks/<task_id>/status/`
|
|
- `POST /api/soil-data/ndvi-health/`
|
|
- `POST /api/soile/moisture-heatmap/`
|
|
- `POST /api/soile/health-summary/`
|
|
- `POST /api/soile/anomaly-detection/`
|
|
- `POST /api/farm-data/`
|
|
- `GET /api/farm-data/<farm_uuid>/detail/`
|
|
- `POST /api/farm-data/parameters/`
|
|
- `POST /api/weather/farm-card/`
|
|
- `POST /api/weather/water-need-prediction/`
|
|
- `POST /api/economy/overview/`
|
|
- `GET /api/plants/`
|
|
- `POST /api/plants/`
|
|
- `GET /api/plants/<pk>/`
|
|
- `PUT /api/plants/<pk>/`
|
|
- `PATCH /api/plants/<pk>/`
|
|
- `DELETE /api/plants/<pk>/`
|
|
- `POST /api/plants/fetch-info/`
|
|
- `POST /api/pest-disease/detect/`
|
|
- `POST /api/pest-disease/risk/`
|
|
- `GET /api/irrigation/`
|
|
- `POST /api/irrigation/`
|
|
- `GET /api/irrigation/<pk>/`
|
|
- `PUT /api/irrigation/<pk>/`
|
|
- `PATCH /api/irrigation/<pk>/`
|
|
- `DELETE /api/irrigation/<pk>/`
|
|
- `POST /api/irrigation/recommend/`
|
|
- `POST /api/irrigation/water-stress/`
|
|
- `POST /api/fertilization/recommend/`
|
|
- `POST /api/crop-simulation/growth/`
|
|
- `GET /api/crop-simulation/growth/<task_id>/status/`
|
|
- `POST /api/crop-simulation/current-farm-chart/`
|
|
- `POST /api/crop-simulation/harvest-prediction/`
|
|
- `POST /api/crop-simulation/yield-prediction/`
|