891 lines
23 KiB
Markdown
891 lines
23 KiB
Markdown
# مستند تحویل تغییرات بکاند به فرانت
|
|
|
|
این فایل خلاصه و جمعبندی دقیقی از تغییرات انجامشده در بکاند است تا تیم فرانت بتواند بدون بررسی diffها، مصرف APIها را بهروزرسانی کند.
|
|
|
|
---
|
|
|
|
## جمعبندی خیلی کوتاه
|
|
|
|
بزرگترین تغییر این release این است که محور اصلی دادهها از `sensor` به `farm` منتقل شده است.
|
|
|
|
یعنی:
|
|
|
|
- مسیر `sensor-hub` حذف شده و به `farm-hub` تغییر کرده است.
|
|
- در endpointهای مختلف، `sensor_uuid` حذف و `farm_uuid` جایگزین شده است.
|
|
- چند API که قبلا عمومی یا mock بودند، حالا per-farm و وابسته به مزرعهی انتخابشده هستند.
|
|
- بعضی responseها فیلد `farm_uuid` را هم برمیگردانند تا state فرانت دقیقتر بماند.
|
|
- بعضی endpointهایی که در داک قبلی/پستمن وجود داشتند، الان route فعال ندارند و نباید از سمت فرانت صدا زده شوند.
|
|
|
|
---
|
|
|
|
## اقدام لازم برای فرانت
|
|
|
|
فرانت باید از این به بعد یک `farm_uuid` فعال/انتخابشده در state سراسری داشته باشد و آن را در درخواستهای مرتبط ارسال کند.
|
|
|
|
در عمل:
|
|
|
|
1. بعد از گرفتن لیست مزارع از `GET /api/farm-hub/`، یک مزرعهی active/current انتخاب کنید.
|
|
2. `farm_uuid` همان مزرعه را برای dashboard، crop zoning، AI assistant، irrigation recommendation و fertilization recommendation ارسال کنید.
|
|
3. هر جایی که قبلا `sensor_uuid` استفاده میشد، باید با `farm_uuid` جایگزین شود.
|
|
|
|
---
|
|
|
|
## Breaking Changes
|
|
|
|
### 1) تغییر مسیر اصلی ماژول مزرعه
|
|
|
|
- قبلی: `/api/sensor-hub/`
|
|
- جدید: `/api/farm-hub/`
|
|
|
|
اگر فرانت هنوز route قبلی را صدا بزند، دیگر کار نخواهد کرد.
|
|
|
|
---
|
|
|
|
### 2) حذف `sensor_uuid` از crop zoning
|
|
|
|
در crop zoning دیگر `sensor_uuid` معتبر نیست.
|
|
|
|
- قبلی:
|
|
|
|
```http
|
|
GET /api/crop-zoning/area/?sensor_uuid=<uuid>
|
|
```
|
|
|
|
- جدید:
|
|
|
|
```http
|
|
GET /api/crop-zoning/area/?farm_uuid=<uuid>
|
|
```
|
|
|
|
---
|
|
|
|
### 3) dashboard config و dashboard cards حالا per-farm هستند
|
|
|
|
این دو endpoint دیگر global نیستند و بدون `farm_uuid` نباید مصرف شوند:
|
|
|
|
- `GET /api/farm-dashboard-config/?farm_uuid=...`
|
|
- `PATCH /api/farm-dashboard-config/`
|
|
- `GET /api/farm-dashboard/?farm_uuid=...`
|
|
|
|
نکته مهم:
|
|
|
|
- در `GET`، `farm_uuid` باید در query باشد.
|
|
- در `PATCH`، `farm_uuid` باید داخل body باشد.
|
|
|
|
---
|
|
|
|
### 4) Farm AI Assistant حالا کاملا farm-scoped است
|
|
|
|
تمام flow چت حالا به مزرعه گره خورده است.
|
|
|
|
یعنی:
|
|
|
|
- لیست چتها per-farm است.
|
|
- ساخت conversation جدید بدون `farm_uuid` ممکن نیست.
|
|
- گرفتن پیامها و حذف conversation هم نیاز به `farm_uuid` دارد.
|
|
- responseها در چند endpoint جدیدا `farm_uuid` برمیگردانند.
|
|
|
|
---
|
|
|
|
### 5) Recommendation APIها بدون `farm_uuid` معتبر نیستند
|
|
|
|
برای هر دو ماژول:
|
|
|
|
- `fertilization-recommendation`
|
|
- `irrigation-recommendation`
|
|
|
|
الان `farm_uuid` اجباری شده است:
|
|
|
|
- در `config` بهصورت query param
|
|
- در `recommend` بهصورت body
|
|
- در `status` بهصورت query param
|
|
|
|
---
|
|
|
|
## نکته مهم درباره routeهای فعال
|
|
|
|
چند endpoint در کد view وجود دارند یا در داکهای قدیمی/پستمن دیده میشوند، ولی الان route فعال ندارند. فرانت نباید روی آنها حساب کند.
|
|
|
|
### routeهای غیرفعال فعلی
|
|
|
|
- `POST /api/farm-ai-assistant/chat/`
|
|
- `GET /api/farm-dashboard/cards/`
|
|
- `POST /api/crop-zoning/zones/initial/`
|
|
- `POST /api/crop-zoning/zones/water-need/`
|
|
- `POST /api/crop-zoning/zones/soil-quality/`
|
|
- `POST /api/crop-zoning/zones/cultivation-risk/`
|
|
|
|
### routeهای فعال فعلی
|
|
|
|
فقط routeهایی که در این فایل آمدهاند مبنای فرانت باشند.
|
|
|
|
---
|
|
|
|
## 1) Farm Hub
|
|
|
|
### هدف
|
|
|
|
ماژول جدید `farm-hub` جایگزین `sensor-hub` شده و موجودیت اصلی فرانت برای انتخاب مزرعه، نمایش سنسورها، ساخت مزرعه و مدیریت فعال/غیرفعال بودن مزرعه است.
|
|
|
|
### Base Path
|
|
|
|
```text
|
|
/api/farm-hub/
|
|
```
|
|
|
|
### endpointهای فعال
|
|
|
|
| Method | Path | توضیح |
|
|
|---|---|---|
|
|
| GET | `/api/farm-hub/` | لیست مزارع کاربر |
|
|
| POST | `/api/farm-hub/` | ساخت مزرعه جدید |
|
|
| GET | `/api/farm-hub/{farm_uuid}/` | جزئیات مزرعه |
|
|
| PATCH | `/api/farm-hub/{farm_uuid}/` | آپدیت مزرعه |
|
|
| DELETE | `/api/farm-hub/{farm_uuid}/` | حذف مزرعه |
|
|
| POST | `/api/farm-hub/active/` | فعالکردن مزرعه |
|
|
| POST | `/api/farm-hub/deactive/` | غیرفعالکردن مزرعه |
|
|
|
|
### ساختار response مزرعه
|
|
|
|
```json
|
|
{
|
|
"farm_uuid": "550e8400-e29b-41d4-a716-446655440000",
|
|
"name": "مزرعه نمونه",
|
|
"is_active": true,
|
|
"customization": {},
|
|
"farm_type": {
|
|
"uuid": "11111111-1111-1111-1111-111111111111",
|
|
"name": "زراعی",
|
|
"description": "",
|
|
"metadata": {}
|
|
},
|
|
"products": [
|
|
{
|
|
"uuid": "22222222-2222-2222-2222-222222222222",
|
|
"name": "گندم",
|
|
"description": "",
|
|
"metadata": {}
|
|
}
|
|
],
|
|
"sensors": [
|
|
{
|
|
"uuid": "33333333-3333-3333-3333-333333333333",
|
|
"name": "Station 1",
|
|
"sensor_type": "weather_station",
|
|
"is_active": true,
|
|
"specifications": {},
|
|
"power_source": {},
|
|
"customization": {},
|
|
"last_updated": "2025-02-18T12:00:00Z"
|
|
}
|
|
],
|
|
"last_updated": "2025-02-18T12:00:00Z"
|
|
}
|
|
```
|
|
|
|
### نکات مهم برای فرانت
|
|
|
|
- شناسه اصلی مزرعه `farm_uuid` است.
|
|
- هر مزرعه `farm_type`، `products` و `sensors` را بهصورت nested برمیگرداند.
|
|
- سنسورها دیگر top-level resource مستقل برای UI نیستند؛ داخل خود مزرعه برمیگردند.
|
|
- endpoint جداگانهای برای catalog نوع مزرعه/محصول در این diff اضافه نشده است.
|
|
|
|
### ساخت مزرعه
|
|
|
|
نمونه body:
|
|
|
|
```json
|
|
{
|
|
"name": "farm-1",
|
|
"farm_type_uuid": "11111111-1111-1111-1111-111111111111",
|
|
"product_uuids": [
|
|
"22222222-2222-2222-2222-222222222222"
|
|
],
|
|
"customization": {
|
|
"report_interval_sec": 300
|
|
},
|
|
"sensors": [
|
|
{
|
|
"name": "Station 1",
|
|
"sensor_type": "weather_station",
|
|
"is_active": true,
|
|
"specifications": {
|
|
"model": "FH-1"
|
|
},
|
|
"power_source": {
|
|
"type": "battery"
|
|
},
|
|
"customization": {
|
|
"report_interval_sec": 300
|
|
}
|
|
}
|
|
],
|
|
"area_geojson": {
|
|
"type": "Feature",
|
|
"properties": {},
|
|
"geometry": {
|
|
"type": "Polygon",
|
|
"coordinates": [
|
|
[
|
|
[51.418934, 35.706815],
|
|
[51.423054, 35.691062],
|
|
[51.384258, 35.689389],
|
|
[51.418934, 35.706815]
|
|
]
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### تغییر مهم در create farm
|
|
|
|
اگر `area_geojson` ارسال شود:
|
|
|
|
- مزرعه ساخته میشود
|
|
- zoning اولیه هم برای همان مزرعه ساخته میشود
|
|
- در response، فیلد `zoning` هم برمیگردد
|
|
|
|
این برای فرانت خیلی مهم است چون بعد از ساخت مزرعه میتواند مستقیم zoning اولیه را برای map استفاده کند و لازم نیست منتظر call جداگانه باشد.
|
|
|
|
### فعال/غیرفعال کردن مزرعه
|
|
|
|
body هر دو endpoint:
|
|
|
|
```json
|
|
{
|
|
"farm_uuid": "550e8400-e29b-41d4-a716-446655440000"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 2) Crop Zoning
|
|
|
|
### Base Path
|
|
|
|
```text
|
|
/api/crop-zoning/
|
|
```
|
|
|
|
### endpointهای فعال
|
|
|
|
| Method | Path | توضیح |
|
|
|---|---|---|
|
|
| GET | `/api/crop-zoning/area/?farm_uuid=...&page=1&page_size=10` | گرفتن area + task status + zones |
|
|
| GET | `/api/crop-zoning/products/` | گرفتن لیست محصولات قابل کشت |
|
|
| GET | `/api/crop-zoning/zones/{zone_id}/details/` | جزئیات یک زون |
|
|
|
|
### breaking change
|
|
|
|
فقط `farm_uuid` معتبر است و request باید روی مزرعهی متعلق به همان کاربر انجام شود.
|
|
|
|
### نمونه request
|
|
|
|
```http
|
|
GET /api/crop-zoning/area/?farm_uuid=<farm_uuid>&page=1&page_size=10
|
|
```
|
|
|
|
### نمونه response
|
|
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"data": {
|
|
"task": {
|
|
"status": "SUCCESS",
|
|
"stage": "completed",
|
|
"stage_label": "پردازش همه زونها کامل شده است",
|
|
"area_uuid": "c0eaa4d7-92bf-4542-a60d-6010b45e7c96",
|
|
"total_zones": 364,
|
|
"completed_zones": 364,
|
|
"processing_zones": 0,
|
|
"pending_zones": 0,
|
|
"failed_zones": 0,
|
|
"remaining_zones": 0,
|
|
"progress_percent": 100,
|
|
"summary": {
|
|
"done": 364,
|
|
"in_progress": 0,
|
|
"remaining": 0,
|
|
"failed": 0
|
|
},
|
|
"message": "از مجموع 364 زون، 364 زون پردازش شده، 0 زون در حال پردازش و 0 زون باقی مانده است.",
|
|
"failed_zone_errors": [],
|
|
"cell_side_km": 0.1
|
|
},
|
|
"area": {
|
|
"type": "Feature",
|
|
"geometry": {
|
|
"type": "Polygon",
|
|
"coordinates": []
|
|
},
|
|
"properties": {
|
|
"center": {
|
|
"latitude": 35.69575533,
|
|
"longitude": 51.40874867
|
|
},
|
|
"area_sqm": 3109868.97,
|
|
"cell_side_km": 0.1,
|
|
"area_hectares": 310.9869
|
|
}
|
|
},
|
|
"zones": [],
|
|
"pagination": {
|
|
"page": 1,
|
|
"page_size": 10,
|
|
"total_pages": 37,
|
|
"total_zones": 364,
|
|
"returned_zones": 10,
|
|
"has_next": true,
|
|
"has_previous": false
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### نکات مهم برای فرانت
|
|
|
|
- `zones` صفحهبندیشده است؛ کل زونها در هر response برنمیگردند.
|
|
- فرانت باید با `task.status` و `task.stage` polling را مدیریت کند.
|
|
- `page` و `page_size` هنوز اختیاری هستند.
|
|
- اگر مزرعه area نداشته باشد، بکاند خودش area/zones را برای همان مزرعه ایجاد میکند.
|
|
|
|
### خطاها
|
|
|
|
#### نبودن `farm_uuid`
|
|
|
|
```json
|
|
{
|
|
"status": "error",
|
|
"message": "farm_uuid is required."
|
|
}
|
|
```
|
|
|
|
#### پیدا نشدن مزرعه
|
|
|
|
```json
|
|
{
|
|
"status": "error",
|
|
"message": "Farm not found."
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3) Farm Dashboard
|
|
|
|
### Base Path
|
|
|
|
```text
|
|
/api/farm-dashboard/
|
|
```
|
|
|
|
### Config Path
|
|
|
|
```text
|
|
/api/farm-dashboard-config/
|
|
```
|
|
|
|
### تغییر اصلی
|
|
|
|
dashboard config دیگر mock/global نیست و برای هر مزرعه جداگانه در دیتابیس ذخیره میشود.
|
|
|
|
### endpointهای فعال
|
|
|
|
| Method | Path | توضیح |
|
|
|---|---|---|
|
|
| GET | `/api/farm-dashboard-config/?farm_uuid=...` | گرفتن تنظیمات داشبورد همان مزرعه |
|
|
| PATCH | `/api/farm-dashboard-config/` | آپدیت partial تنظیمات داشبورد همان مزرعه |
|
|
| GET | `/api/farm-dashboard/?farm_uuid=...` | گرفتن داده کارتهای داشبورد برای همان مزرعه |
|
|
|
|
### نکات مهم برای فرانت
|
|
|
|
- `GET /api/farm-dashboard/cards/` الان route فعال ندارد؛ فقط base path فعال است.
|
|
- در response config، فیلد `farm_uuid` اضافه شده است.
|
|
- در `PATCH` حتی اگر فقط یک فیلد را تغییر میدهید، باز هم باید `farm_uuid` را بفرستید.
|
|
|
|
### GET config
|
|
|
|
```http
|
|
GET /api/farm-dashboard-config/?farm_uuid=<farm_uuid>
|
|
```
|
|
|
|
### GET config response
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"msg": "OK",
|
|
"data": {
|
|
"farm_uuid": "550e8400-e29b-41d4-a716-446655440000",
|
|
"disabled_card_ids": [],
|
|
"row_order": [
|
|
"overviewKpis",
|
|
"weatherAlerts",
|
|
"sensorMonitoring",
|
|
"sensorCharts",
|
|
"alertsWater",
|
|
"predictions",
|
|
"soilHeatmap",
|
|
"ndviRecommendations",
|
|
"economic"
|
|
],
|
|
"enable_drag_reorder": true
|
|
}
|
|
}
|
|
```
|
|
|
|
### PATCH config sample
|
|
|
|
```json
|
|
{
|
|
"farm_uuid": "550e8400-e29b-41d4-a716-446655440000",
|
|
"disabled_card_ids": [
|
|
"farmWeatherCard"
|
|
]
|
|
}
|
|
```
|
|
|
|
### rule مهم PATCH
|
|
|
|
اگر body فقط این باشد:
|
|
|
|
```json
|
|
{
|
|
"farm_uuid": "..."
|
|
}
|
|
```
|
|
|
|
خطای validation میگیرید، چون باید حداقل یکی از اینها هم باشد:
|
|
|
|
- `disabled_card_ids`
|
|
- `row_order`
|
|
- `enable_drag_reorder`
|
|
|
|
### خطاهای متداول
|
|
|
|
#### نبودن `farm_uuid`
|
|
|
|
```json
|
|
{
|
|
"farm_uuid": [
|
|
"This field is required."
|
|
]
|
|
}
|
|
```
|
|
|
|
#### مزرعه متعلق به کاربر نباشد
|
|
|
|
```json
|
|
{
|
|
"farm_uuid": [
|
|
"Farm not found."
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4) Farm AI Assistant
|
|
|
|
### Base Path
|
|
|
|
```text
|
|
/api/farm-ai-assistant/
|
|
```
|
|
|
|
### endpointهای فعال
|
|
|
|
| Method | Path | توضیح |
|
|
|---|---|---|
|
|
| GET | `/api/farm-ai-assistant/context/?farm_uuid=...` | گرفتن context مزرعه برای نوار/summary |
|
|
| GET | `/api/farm-ai-assistant/chats/?farm_uuid=...` | لیست conversationهای همان مزرعه |
|
|
| POST | `/api/farm-ai-assistant/chats/` | ساخت conversation جدید |
|
|
| GET | `/api/farm-ai-assistant/chats/{conversation_id}/messages/?farm_uuid=...` | گرفتن پیامها |
|
|
| DELETE | `/api/farm-ai-assistant/chats/{conversation_id}/?farm_uuid=...` | حذف conversation |
|
|
| POST | `/api/farm-ai-assistant/chat/task/` | ایجاد task چت |
|
|
| GET | `/api/farm-ai-assistant/chat/task/{task_id}/status/?farm_uuid=...` | گرفتن وضعیت task |
|
|
|
|
### نکته خیلی مهم
|
|
|
|
`POST /api/farm-ai-assistant/chat/` الان route فعال ندارد.
|
|
|
|
پس flow فعلی فرانت باید async باشد:
|
|
|
|
1. `POST /chat/task/`
|
|
2. polling روی `GET /chat/task/{task_id}/status/`
|
|
|
|
### تغییرات مهم response
|
|
|
|
فیلد `farm_uuid` در این قسمتها اضافه شده است:
|
|
|
|
- conversation summary
|
|
- لیست پیامها
|
|
- delete response
|
|
- task create response
|
|
- task status response
|
|
- assistant payload نهایی
|
|
|
|
### GET context
|
|
|
|
```http
|
|
GET /api/farm-ai-assistant/context/?farm_uuid=<farm_uuid>
|
|
```
|
|
|
|
نمونه response:
|
|
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"data": {
|
|
"farm_uuid": "550e8400-e29b-41d4-a716-446655440000",
|
|
"soilType": "Loamy",
|
|
"waterEC": "1.2 dS/m",
|
|
"selectedCrop": "Tomato",
|
|
"growthStage": "Flowering",
|
|
"lastIrrigationStatus": "2 days ago"
|
|
}
|
|
}
|
|
```
|
|
|
|
### GET chats response
|
|
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"data": [
|
|
{
|
|
"id": "conv-123",
|
|
"farm_uuid": "550e8400-e29b-41d4-a716-446655440000",
|
|
"message_count": 4
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### POST chats request
|
|
|
|
```json
|
|
{
|
|
"farm_uuid": "550e8400-e29b-41d4-a716-446655440000",
|
|
"title": "New chat",
|
|
"farm_context": {
|
|
"soilType": "Loamy"
|
|
}
|
|
}
|
|
```
|
|
|
|
### POST chat task request
|
|
|
|
```json
|
|
{
|
|
"farm_uuid": "550e8400-e29b-41d4-a716-446655440000",
|
|
"conversation_id": "7a26d99a-8d67-467d-a4a8-4c46b62b6bc2",
|
|
"content": "What is the best irrigation plan?",
|
|
"images": [],
|
|
"farm_context": {
|
|
"soilType": "Loamy"
|
|
}
|
|
}
|
|
```
|
|
|
|
### POST chat task response
|
|
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"data": {
|
|
"task_id": "farm-ai-chat-task-123",
|
|
"status": "PENDING",
|
|
"status_url": "/api/tasks/farm-ai-chat-task-123/status/",
|
|
"conversation_id": "7a26d99a-8d67-467d-a4a8-4c46b62b6bc2",
|
|
"message_id": "2cbd4d61-363d-4f7c-a46a-a78cf28f6dd8",
|
|
"farm_uuid": "550e8400-e29b-41d4-a716-446655440000"
|
|
}
|
|
}
|
|
```
|
|
|
|
### GET task status response در حالت success
|
|
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"data": {
|
|
"task_id": "farm-ai-chat-task-123",
|
|
"status": "SUCCESS",
|
|
"conversation_id": "7a26d99a-8d67-467d-a4a8-4c46b62b6bc2",
|
|
"farm_uuid": "550e8400-e29b-41d4-a716-446655440000",
|
|
"result": {
|
|
"message_id": "msg-001",
|
|
"conversation_id": "7a26d99a-8d67-467d-a4a8-4c46b62b6bc2",
|
|
"farm_uuid": "550e8400-e29b-41d4-a716-446655440000",
|
|
"content": "Here is the recommended plan.",
|
|
"sections": []
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### نکات مهم برای فرانت
|
|
|
|
- conversationها حالا per-farm هستند؛ لیست چت مزرعه A لزوما برای مزرعه B مشترک نیست.
|
|
- برای گرفتن messages و delete هم باید `farm_uuid` در query بفرستید.
|
|
- در response پیامها، هم top-level و هم هر message شامل `farm_uuid` است.
|
|
|
|
### خطاها
|
|
|
|
- اگر `farm_uuid` نفرستید: `400`
|
|
- اگر مزرعه پیدا نشود: در این ماژول معمولا `404`
|
|
|
|
---
|
|
|
|
## 5) Fertilization Recommendation
|
|
|
|
### Base Path
|
|
|
|
```text
|
|
/api/fertilization-recommendation/
|
|
```
|
|
|
|
### endpointهای فعال
|
|
|
|
| Method | Path | توضیح |
|
|
|---|---|---|
|
|
| GET | `/api/fertilization-recommendation/config/?farm_uuid=...` | گرفتن داده اولیه فرم |
|
|
| POST | `/api/fertilization-recommendation/recommend/` | ساخت recommendation |
|
|
| GET | `/api/fertilization-recommendation/recommend/status/{task_id}/?farm_uuid=...` | وضعیت task |
|
|
|
|
### breaking change
|
|
|
|
`farm_uuid` برای این ماژول اجباری شده است.
|
|
|
|
### GET config
|
|
|
|
```http
|
|
GET /api/fertilization-recommendation/config/?farm_uuid=<farm_uuid>
|
|
```
|
|
|
|
### response config
|
|
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"data": {
|
|
"farm_uuid": "550e8400-e29b-41d4-a716-446655440000",
|
|
"farmData": {
|
|
"soilType": "Loamy",
|
|
"organicMatter": "Medium (2.5%)",
|
|
"waterEC": "1.2 dS/m"
|
|
},
|
|
"growthStages": [],
|
|
"cropOptions": []
|
|
}
|
|
}
|
|
```
|
|
|
|
### POST recommend request
|
|
|
|
```json
|
|
{
|
|
"farm_uuid": "550e8400-e29b-41d4-a716-446655440000",
|
|
"crop_id": "wheat",
|
|
"growth_stage": "flowering",
|
|
"farm_data": {
|
|
"soilType": "Loamy",
|
|
"organicMatter": "Medium (2.5%)",
|
|
"waterEC": "1.2 dS/m"
|
|
}
|
|
}
|
|
```
|
|
|
|
### نکات مهم برای فرانت
|
|
|
|
- اگر `farm_uuid` نفرستید، validation error میگیرید.
|
|
- در status endpoint هم `farm_uuid` باید query param باشد.
|
|
- بکاند درخواست/پاسخ recommendation را برای هر مزرعه ذخیره میکند، ولی این persistence فعلا response shape فرانت را تغییر نمیدهد.
|
|
|
|
### نمونه خطا
|
|
|
|
```json
|
|
{
|
|
"code": 400,
|
|
"msg": "داده نامعتبر.",
|
|
"data": {
|
|
"farm_uuid": [
|
|
"This field is required."
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 6) Irrigation Recommendation
|
|
|
|
### Base Path
|
|
|
|
```text
|
|
/api/irrigation-recommendation/
|
|
```
|
|
|
|
### endpointهای فعال
|
|
|
|
| Method | Path | توضیح |
|
|
|---|---|---|
|
|
| GET | `/api/irrigation-recommendation/config/?farm_uuid=...` | گرفتن داده اولیه فرم |
|
|
| POST | `/api/irrigation-recommendation/recommend/` | ساخت recommendation |
|
|
| GET | `/api/irrigation-recommendation/recommend/status/{task_id}/?farm_uuid=...` | وضعیت task |
|
|
|
|
### breaking change
|
|
|
|
`farm_uuid` برای این ماژول هم اجباری شده است.
|
|
|
|
### GET config
|
|
|
|
```http
|
|
GET /api/irrigation-recommendation/config/?farm_uuid=<farm_uuid>
|
|
```
|
|
|
|
### response config
|
|
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"data": {
|
|
"farm_uuid": "550e8400-e29b-41d4-a716-446655440000",
|
|
"farmInfo": {
|
|
"soilType": "Loamy",
|
|
"waterQuality": "Medium EC",
|
|
"climateZone": "Temperate"
|
|
},
|
|
"cropOptions": []
|
|
}
|
|
}
|
|
```
|
|
|
|
### POST recommend request
|
|
|
|
```json
|
|
{
|
|
"farm_uuid": "550e8400-e29b-41d4-a716-446655440000",
|
|
"crop_id": "wheat",
|
|
"farm_data": {
|
|
"soilType": "Loamy",
|
|
"waterQuality": "Medium EC",
|
|
"climateZone": "Temperate"
|
|
}
|
|
}
|
|
```
|
|
|
|
### نکات مهم برای فرانت
|
|
|
|
- route جداگانهای برای `task create` در urls فعال نیست؛ همان `POST /recommend/` را استفاده کنید.
|
|
- برای status هم حتما `farm_uuid` را در query بفرستید.
|
|
- response نهایی ممکن است شامل `plan`، `water_balance`، `raw_response` و `status` باشد.
|
|
|
|
### نمونه خطا
|
|
|
|
```json
|
|
{
|
|
"code": 400,
|
|
"msg": "داده نامعتبر.",
|
|
"data": {
|
|
"farm_uuid": [
|
|
"This field is required."
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## الگوی مشترک خطاها
|
|
|
|
بسته به ماژول، شکل خطا یکسان نیست. فرانت بهتر است هر دو الگوی زیر را پشتیبانی کند:
|
|
|
|
### الگوی 1
|
|
|
|
```json
|
|
{
|
|
"status": "error",
|
|
"message": "Farm not found."
|
|
}
|
|
```
|
|
|
|
### الگوی 2
|
|
|
|
```json
|
|
{
|
|
"farm_uuid": [
|
|
"Farm not found."
|
|
]
|
|
}
|
|
```
|
|
|
|
### الگوی 3
|
|
|
|
```json
|
|
{
|
|
"detail": "Farm not found"
|
|
}
|
|
```
|
|
|
|
پس بهتر است parsing خطا فقط روی یک shape ثابت بسته نشود.
|
|
|
|
---
|
|
|
|
## وضعیت احراز هویت
|
|
|
|
برای endpointهای این فایل، فرانت بهتر است همیشه این هدرها را بفرستد:
|
|
|
|
```http
|
|
Authorization: Bearer <access_token>
|
|
Content-Type: application/json
|
|
```
|
|
|
|
بهخصوص در این ماژولها:
|
|
|
|
- `farm-hub`
|
|
- `farm-dashboard`
|
|
- `farm-ai-assistant`
|
|
- `crop-zoning`
|
|
- `fertilization-recommendation`
|
|
- `irrigation-recommendation`
|
|
|
|
---
|
|
|
|
## چکلیست تغییرات لازم در فرانت
|
|
|
|
### اجباری
|
|
|
|
- همه referenceهای `sensor_uuid` را به `farm_uuid` تغییر دهید.
|
|
- همه callهای `sensor-hub` را به `farm-hub` تغییر دهید.
|
|
- یک state مرکزی برای `selectedFarm` یا `currentFarm` داشته باشید.
|
|
- قبل از callهای dashboard/zoning/assistant/recommendation، `farm_uuid` مزرعه انتخابی را inject کنید.
|
|
- flow چت را از sync به async task-based تغییر دهید.
|
|
|
|
### مهم
|
|
|
|
- `GET /api/farm-dashboard/cards/` را با `GET /api/farm-dashboard/?farm_uuid=...` جایگزین کنید.
|
|
- در dashboard config patch، `farm_uuid` را داخل body بفرستید.
|
|
- اگر روی routeهای crop zoning قدیمی مثل `zones/water-need` حساب کردهاید، آنها را از flow حذف کنید.
|
|
|
|
### بهتر است
|
|
|
|
- هندل خطا را tolerant بنویسید چون shape خطا بین ماژولها یکسان نیست.
|
|
- `farm_uuid` برگشتی responseها را با state فرانت sync نگه دارید.
|
|
- بعد از create farm اگر response شامل `zoning` بود، مستقیم آن را برای map استفاده کنید.
|
|
|
|
---
|
|
|
|
## جمعبندی نهایی
|
|
|
|
اگر بخواهیم خیلی عملی بگوییم، فرانت برای این release فقط باید این سه اصل را رعایت کند:
|
|
|
|
1. همه چیز را بر اساس `farm_uuid` مصرف کند، نه `sensor_uuid`.
|
|
2. تمام ماژولهای اصلی را روی مزرعهی انتخابی کاربر scope کند.
|
|
3. فقط routeهای فعال فعلی را مصرف کند، نه routeهایی که در داکهای قدیمی یا پستمن قبلی دیده میشوند.
|
|
|
|
اگر لازم باشد، مرحله بعدی میتواند تولید یک نسخهی کوتاهتر مخصوص frontend devها باشد که فقط شامل endpoint matrix و نمونه request/response باشد.
|