sajad-dev/Backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
arvin-dev
Backend/docs/sensor_frontend_api_reference.md
T

1063 lines
27 KiB
Markdown
Raw Permalink Normal View History

UPDATE
2026-04-29 01:27:16 +03:30
# مستند فرانت API سنسورها
این فایل برای تیم فرانت نوشته شده و رفتار کامل endpointهای زیر را توضیح می‌دهد:
- `GET /api/sensor-7-in-1/summary/`
- `GET /api/sensors/comparison-chart/`
- `GET /api/sensors/radar-chart/`
- `GET /api/sensors/values-list/`
- `GET /api/sensor-external-api/logs/`
---
## 1) نکات کلی
### Base URL
همه مسیرها نسبت به دامنه اصلی backend تعریف می‌شوند. مثال:
```txt
https://example.com/api/sensor-7-in-1/summary/
```
### نوع احراز هویت
این endpointها دو مدل احراز هویت دارند:
1. endpointهای سنسور 7-in-1:
- `GET /api/sensor-7-in-1/summary/`
- `GET /api/sensors/comparison-chart/`
- `GET /api/sensors/radar-chart/`
- `GET /api/sensors/values-list/`
- نیازمند کاربر لاگین‌شده هستند.
- اگر کاربر احراز هویت نشده باشد معمولاً پاسخ `401 Unauthorized` برمی‌گردد.
2. endpoint لاگ سنسور خارجی:
- `GET /api/sensor-external-api/logs/`
- نیازمند هدر `X-API-Key` است.
- اگر API key ارسال نشود یا اشتباه باشد پاسخ `401 Unauthorized` برمی‌گردد.
### نکته مهم درباره ساختار response
این 5 API یکدست نیستند:
- `summary` پاسخ را داخل ساختار استاندارد `code / msg / data` برمی‌گرداند.
- `comparison-chart`، `radar-chart` و `values-list` داده خام را مستقیم برمی‌گردانند.
- `sensor-external-api/logs` پاسخ را به‌صورت paginated و داخل `code / msg / data` برمی‌گرداند.
پس فرانت باید برای هر endpoint دقیقاً همان ساختار را هندل کند.
---
## 2) GET /api/sensor-7-in-1/summary/
### هدف
این endpoint یک summary کامل از سنسور 7-in-1 مزرعه برمی‌گرداند و چند ویجت آماده برای UI را یکجا در خروجی قرار می‌دهد:
- اطلاعات متای سنسور
- لیست مقادیر سنسور
- کارت میانگین رطوبت خاک
- نمودار رادار
- نمودار مقایسه‌ای
- کارت anomaly detection
- heatmap رطوبت خاک
### احراز هویت
- نیازمند احراز هویت کاربر
### Query Params
| نام | نوع | اجباری | توضیح |
|---|---|---:|---|
| `farm_uuid` | `uuid` | بله | شناسه مزرعه |
### نمونه درخواست
```http
GET /api/sensor-7-in-1/summary/?farm_uuid=11111111-1111-1111-1111-111111111111
Authorization: Bearer <access_token>
```
### ساختار پاسخ موفق
```json
{
"code": 200,
"msg": "OK",
"data": {
"sensor": {},
"sensorValuesList": {},
"avgSoilMoisture": {},
"sensorRadarChart": {},
"sensorComparisonChart": {},
"anomalyDetectionCard": {},
"soilMoistureHeatmap": {}
}
}
```
### فیلدهای `data`
#### `sensor`
متادیتای سنسور اصلی:
| فیلد | نوع | توضیح |
|---|---|---|
| `name` | `string` | نام سنسور |
| `physicalDeviceUuid` | `string \| null` | شناسه فیزیکی دستگاه |
| `sensorCatalogCode` | `string` | کد سنسور در catalog |
| `updatedAt` | `string \| null` | زمان آخرین لاگ به فرمت ISO |
نمونه:
```json
{
"name": "Soil Sensor 7-in-1",
"physicalDeviceUuid": "33333333-3333-3333-3333-333333333333",
"sensorCatalogCode": "sensor-7-in-1",
"updatedAt": "2025-01-10T08:30:00Z"
}
```
#### `sensorValuesList`
لیست مقادیر فعلی سنسور برای نمایش کارت‌ها یا stat itemها:
| فیلد | نوع | توضیح |
|---|---|---|
| `sensor` | `object` | همان متادیتای سنسور |
| `sensors` | `array` | لیست سنسورفیلدها |
ساختار هر آیتم `sensors`:
| فیلد | نوع | توضیح |
|---|---|---|
| `id` | `string` | کلید داخلی فیلد مثل `soil_moisture` |
| `title` | `string` | مقدار فرمت‌شده برای نمایش |
| `subtitle` | `string` | عنوان فارسی فیلد |
| `trendNumber` | `number` | مقدار تغییر نسبت به لاگ قبلی |
| `trend` | `positive \| negative` | جهت تغییر |
| `unit` | `string` | واحد |
نمونه:
```json
{
"sensor": {
"name": "Soil Sensor 7-in-1",
"physicalDeviceUuid": "33333333-3333-3333-3333-333333333333",
"sensorCatalogCode": "sensor-7-in-1",
"updatedAt": "2025-01-10T08:30:00Z"
},
"sensors": [
{
"id": "soil_moisture",
"title": "48.5%",
"subtitle": "رطوبت خاک",
"trendNumber": 7.5,
"trend": "positive",
"unit": "%"
},
{
"id": "soil_temperature",
"title": "23.2°C",
"subtitle": "دمای خاک",
"trendNumber": 2.2,
"trend": "positive",
"unit": "°C"
}
]
}
```
#### `avgSoilMoisture`
کارت KPI برای میانگین رطوبت خاک:
| فیلد | نوع | توضیح |
|---|---|---|
| `id` | `string` | شناسه کارت |
| `title` | `string` | عنوان کارت |
| `subtitle` | `string` | زیرعنوان |
| `stats` | `string` | مقدار اصلی برای نمایش |
| `avatarColor` | `string` | رنگ آیکن/اواتار |
| `avatarIcon` | `string` | نام آیکن |
| `chipText` | `string` | متن وضعیت |
| `chipColor` | `string` | رنگ وضعیت |
نمونه:
```json
{
"id": "avg_soil_moisture",
"title": "میانگین رطوبت خاک",
"subtitle": "سنسور 7 در 1 خاک",
"stats": "48.5%",
"avatarColor": "warning",
"avatarIcon": "tabler-droplet",
"chipText": "متوسط",
"chipColor": "warning"
}
```
#### `sensorRadarChart`
داده آماده برای radar chart:
| فیلد | نوع | توضیح |
|---|---|---|
| `labels` | `string[]` | نام محورها |
| `series` | `array` | سری‌های نمودار |
ساختار هر `series`:
| فیلد | نوع |
|---|---|
| `name` | `string` |
| `data` | `number[]` |
نمونه:
```json
{
"labels": ["رطوبت", "دما", "pH", "EC", "نیتروژن", "فسفر", "پتاسیم"],
"series": [
{
"name": "اکنون",
"data": [86.0, 96.0, 88.0, 84.0, 76.0, 88.0, 44.0]
},
{
"name": "هدف",
"data": [100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0]
}
]
}
```
#### `sensorComparisonChart`
خروجی آماده برای line/area chart:
| فیلد | نوع | توضیح |
|---|---|---|
| `currentValue` | `number` | مقدار آخر |
| `vsLastWeek` | `string` | درصد تغییر نسبت به اولین نقطه |
| `vsLastWeekValue` | `number` | نسخه عددی تغییر |
| `categories` | `string[]` | برچسب محور X |
| `series` | `array` | سری‌های نمودار |
نمونه:
```json
{
"currentValue": 48.5,
"vsLastWeek": "+18.3%",
"vsLastWeekValue": 18.3,
"categories": ["01/04 08:00", "01/10 08:30"],
"series": [
{
"name": "رطوبت خاک",
"data": [41.0, 48.5]
},
{
"name": "بازه هدف",
"data": [55.0, 55.0]
}
]
}
```
#### `anomalyDetectionCard`
لیست ناهنجاری‌های سنسور:
| فیلد | نوع | توضیح |
|---|---|---|
| `anomalies` | `array` | لیست anomaly |
ساختار هر anomaly:
| فیلد | نوع | توضیح |
|---|---|---|
| `sensor` | `string` | نام سنسور/پارامتر |
| `value` | `string` | مقدار فعلی |
| `expected` | `string` | بازه مورد انتظار |
| `deviation` | `string` | اختلاف با مقدار مورد انتظار |
| `severity` | `success \| warning \| error` | شدت |
نمونه:
```json
{
"anomalies": [
{
"sensor": "پتاسیم",
"value": "24 mg/kg",
"expected": "15-35 mg/kg",
"deviation": "0",
"severity": "success"
}
]
}
```
نکته:
- اگر ناهنجاری واقعی وجود نداشته باشد، backend یک آیتم success برمی‌گرداند تا UI حالت خالی نداشته باشد.
#### `soilMoistureHeatmap`
خروجی heatmap:
| فیلد | نوع | توضیح |
|---|---|---|
| `zones` | `string[]` | نام zoneها یا سنسورها |
| `hours` | `string[]` | محور زمان |
| `series` | `array` | داده heatmap |
نمونه:
```json
{
"zones": ["Soil Sensor 7-in-1"],
"hours": ["08:00", "10:00"],
"series": [
{
"name": "Soil Sensor 7-in-1",
"data": [
{ "x": "08:00", "y": 41.0 },
{ "x": "10:00", "y": 48.5 }
]
}
]
}
```
### نمونه پاسخ کامل موفق
```json
{
"code": 200,
"msg": "OK",
"data": {
"sensor": {
"name": "Soil Sensor 7-in-1",
"physicalDeviceUuid": "33333333-3333-3333-3333-333333333333",
"sensorCatalogCode": "sensor-7-in-1",
"updatedAt": "2025-01-10T08:30:00Z"
},
"sensorValuesList": {
"sensor": {
"name": "Soil Sensor 7-in-1",
"physicalDeviceUuid": "33333333-3333-3333-3333-333333333333",
"sensorCatalogCode": "sensor-7-in-1",
"updatedAt": "2025-01-10T08:30:00Z"
},
"sensors": [
{
"id": "soil_moisture",
"title": "48.5%",
"subtitle": "رطوبت خاک",
"trendNumber": 7.5,
"trend": "positive",
"unit": "%"
},
{
"id": "soil_temperature",
"title": "23.2°C",
"subtitle": "دمای خاک",
"trendNumber": 2.2,
"trend": "positive",
"unit": "°C"
},
{
"id": "soil_ph",
"title": "6.8",
"subtitle": "pH خاک",
"trendNumber": 0.3,
"trend": "positive",
"unit": "pH"
},
{
"id": "electrical_conductivity",
"title": "1.4 dS/m",
"subtitle": "هدایت الکتریکی",
"trendNumber": 0.4,
"trend": "positive",
"unit": "dS/m"
}
]
},
"avgSoilMoisture": {
"id": "avg_soil_moisture",
"title": "میانگین رطوبت خاک",
"subtitle": "سنسور 7 در 1 خاک",
"stats": "48.5%",
"avatarColor": "warning",
"avatarIcon": "tabler-droplet",
"chipText": "متوسط",
"chipColor": "warning"
},
"sensorRadarChart": {
"labels": ["رطوبت", "دما", "pH", "EC", "نیتروژن", "فسفر", "پتاسیم"],
"series": [
{
"name": "اکنون",
"data": [86.0, 96.0, 88.0, 84.0, 76.0, 88.0, 44.0]
},
{
"name": "هدف",
"data": [100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0]
}
]
},
"sensorComparisonChart": {
"currentValue": 48.5,
"vsLastWeek": "+18.3%",
"vsLastWeekValue": 18.3,
"categories": ["01/04 08:00", "01/10 08:30"],
"series": [
{
"name": "رطوبت خاک",
"data": [41.0, 48.5]
},
{
"name": "بازه هدف",
"data": [55.0, 55.0]
}
]
},
"anomalyDetectionCard": {
"anomalies": [
{
"sensor": "سنسور 7 در 1 خاک",
"value": "نرمال",
"expected": "تمام شاخص‌ها در بازه مجاز هستند",
"deviation": "0",
"severity": "success"
}
]
},
"soilMoistureHeatmap": {
"zones": ["Soil Sensor 7-in-1"],
"hours": ["08:00", "10:00"],
"series": [
{
"name": "Soil Sensor 7-in-1",
"data": [
{ "x": "08:00", "y": 41.0 },
{ "x": "10:00", "y": 48.5 }
]
}
]
}
}
}
```
### خطاهای ممکن
#### `400 Bad Request`
اگر `farm_uuid` ارسال نشود:
```json
{
"farm_uuid": ["This field is required."]
}
```
اگر مزرعه برای این کاربر پیدا نشود:
```json
{
"farm_uuid": ["Farm not found."]
}
```
اگر مزرعه سنسور نداشته باشد:
```json
{
"farm_uuid": ["No sensor found for this farm."]
}
```
#### `401 Unauthorized`
اگر کاربر لاگین نباشد.
### نکات فرانت
- این endpoint برای ساخت dashboard کامل مناسب است.
- `updatedAt` ممکن است `null` باشد.
- اگر داده واقعی هنوز وارد نشده باشد backend ممکن است fallback/mock structure برگرداند.
- برای UI بهتر است روی وجود نداشتن بعضی فیلدها defensive code داشته باشید.
---
## 3) GET /api/sensors/comparison-chart/
### هدف
این endpoint داده خام نمودار مقایسه‌ای را برمی‌گرداند. خروجی آن برای chart component مناسب است و wrapper `code/msg/data` ندارد.
### احراز هویت
- نیازمند احراز هویت کاربر
### Query Params
| نام | نوع | اجباری | پیش‌فرض | توضیح |
|---|---|---:|---|---|
| `farm_uuid` | `uuid` | بله | - | شناسه مزرعه |
| `range` | `string` | خیر | `7d` | فقط `7d` یا `30d` |
### نمونه درخواست
```http
GET /api/sensors/comparison-chart/?farm_uuid=11111111-1111-1111-1111-111111111111&range=7d
Authorization: Bearer <access_token>
```
### پاسخ موفق
```json
{
"series": [
{
"name": "moisture",
"data": [41.0, 48.5]
},
{
"name": "temperature",
"data": [21.0, 23.2]
},
{
"name": "ph",
"data": [6.5, 6.8]
}
],
"categories": ["شنبه", "یکشنبه"],
"currentValue": 48.5,
"vsLastWeek": "+18.3%"
}
```
### توضیح فیلدها
| فیلد | نوع | توضیح |
|---|---|---|
| `series` | `array` | تمام پارامترهای عددی موجود در payload |
| `series[].name` | `string` | نام normalized فیلد مثل `moisture`، `temperature`، `ph` |
| `series[].data` | `number[]` | نقاط سری |
| `categories` | `string[]` | برچسب‌های محور X |
| `currentValue` | `number` | آخرین مقدار سری اول |
| `vsLastWeek` | `string` | درصد تغییر آخرین مقدار نسبت به اولین مقدار سری اول |
### رفتار `range`
- `7d`: دسته‌بندی روی روزهای هفته فارسی انجام می‌شود.
- `30d`: برچسب‌ها به‌صورت `MM/DD` برمی‌گردند.
### نکات مهم فرانت
- نام سری‌ها انگلیسی و normalized هستند، نه label نمایشی.
- `currentValue` و `vsLastWeek` همیشه از سری اول محاسبه می‌شوند.
- اگر هیچ داده‌ای وجود نداشته باشد پاسخ این شکلی است:
```json
{
"series": [],
"categories": [],
"currentValue": 0.0,
"vsLastWeek": "+0.0%"
}
```
### خطاهای ممکن
#### `400 Bad Request`
اگر `range` نامعتبر باشد:
```json
{
"range": ["\"14d\" is not a valid choice."]
}
```
#### `401 Unauthorized`
اگر کاربر لاگین نباشد.
---
## 4) GET /api/sensors/radar-chart/
### هدف
این endpoint داده خام radar chart را برای سنسور مزرعه برمی‌گرداند.
### احراز هویت
- نیازمند احراز هویت کاربر
### Query Params
| نام | نوع | اجباری | پیش‌فرض | توضیح |
|---|---|---:|---|---|
| `farm_uuid` | `uuid` | بله | - | شناسه مزرعه |
| `range` | `string` | خیر | `7d` | فقط `today`، `7d` یا `30d` |
### نمونه درخواست
```http
GET /api/sensors/radar-chart/?farm_uuid=11111111-1111-1111-1111-111111111111&range=7d
Authorization: Bearer <access_token>
```
### پاسخ موفق
```json
{
"labels": ["Moisture", "Temperature", "PH", "EC", "Nitrogen", "Potassium"],
"series": [
{
"name": "وضعیت فعلی",
"data": [48.5, 23.2, 6.8, 1.4, 31.0, 24.0]
},
{
"name": "بازه ایده آل",
"data": [60.0, 26.0, 6.5, 1.3, 42.0, 38.0]
}
]
}
```
### توضیح فیلدها
| فیلد | نوع | توضیح |
|---|---|---|
| `labels` | `string[]` | محورهای radar chart |
| `series` | `array` | دو سری اصلی |
| `series[0]` | `object` | مقدار فعلی |
| `series[1]` | `object` | مقدار ایده‌آل |
### نکات مهم فرانت
- تعداد `labels` و طول `data` هر سری باید برابر باشد.
- فقط فیلدهایی در پاسخ می‌آیند که در آخرین payload وجود داشته باشند.
- اگر داده‌ای پیدا نشود:
```json
{
"labels": [],
"series": []
}
```
### خطاهای ممکن
#### `400 Bad Request`
اگر `range` نامعتبر باشد:
```json
{
"range": ["\"2d\" is not a valid choice."]
}
```
#### `401 Unauthorized`
اگر کاربر لاگین نباشد.
---
## 5) GET /api/sensors/values-list/
### هدف
این endpoint لیست مقادیر current sensor و trend آن‌ها را برمی‌گرداند. مناسب برای card list، table کوتاه یا stat widgets است.
### احراز هویت
- نیازمند احراز هویت کاربر
### Query Params
| نام | نوع | اجباری | پیش‌فرض | توضیح |
|---|---|---:|---|---|
| `farm_uuid` | `uuid` | بله | - | شناسه مزرعه |
| `range` | `string` | خیر | `7d` | فقط `1h`، `24h` یا `7d` |
### نمونه درخواست
```http
GET /api/sensors/values-list/?farm_uuid=11111111-1111-1111-1111-111111111111&range=24h
Authorization: Bearer <access_token>
```
### پاسخ موفق
```json
{
"sensors": [
{
"title": "Moisture",
"subtitle": "مقدار فعلی: 48.5%",
"trendNumber": 7.5,
"trend": "positive",
"unit": "%"
},
{
"title": "Temperature",
"subtitle": "مقدار فعلی: 23.2°C",
"trendNumber": 2.2,
"trend": "positive",
"unit": "°C"
},
{
"title": "PH",
"subtitle": "مقدار فعلی: 6.8",
"trendNumber": 0.3,
"trend": "positive",
"unit": "pH"
}
]
}
```
### توضیح فیلدهای هر آیتم
| فیلد | نوع | توضیح |
|---|---|---|
| `title` | `string` | نام فیلد |
| `subtitle` | `string` | متن آماده برای نمایش مقدار فعلی |
| `trendNumber` | `number` | اختلاف آخرین مقدار نسبت به اولین مقدار در بازه |
| `trend` | `positive \| negative` | جهت تغییر |
| `unit` | `string` | واحد |
### نکات مهم فرانت
- `subtitle` از backend به‌صورت آماده برمی‌گردد.
- اگر در بازه انتخاب‌شده داده‌ای نباشد، backend آخرین لاگ موجود را fallback می‌کند.
- اگر هیچ لاگی وجود نداشته باشد:
```json
{
"sensors": []
}
```
### خطاهای ممکن
#### `400 Bad Request`
اگر `range` نامعتبر باشد:
```json
{
"range": ["\"12h\" is not a valid choice."]
}
```
#### `401 Unauthorized`
اگر کاربر لاگین نباشد.
---
## 6) GET /api/sensor-external-api/logs/
### هدف
این endpoint تاریخچه لاگ‌های ورودی سنسور خارجی را برمی‌گرداند. این API بیشتر برای:
- history page
- debugging panel
- raw sensor log table
- trace داده‌های دریافتی از device
مناسب است.
### احراز هویت
- نیازمند هدر `X-API-Key`
نمونه:
```http
X-API-Key: 12345
```
### Query Params
| نام | نوع | اجباری | توضیح |
|---|---|---:|---|
| `farm_uuid` | `uuid` | بله | شناسه مزرعه |
| `page` | `int` | بله | شماره صفحه، حداقل `1` |
| `page_size` | `int` | بله | اندازه صفحه، بین `1` تا `100` |
| `physical_device_uuid` | `uuid` | خیر | فیلتر روی دستگاه خاص |
| `sensor_type` | `string` | خیر | فیلتر روی نوع سنسور |
| `date_from` | `date` | خیر | فیلتر از تاریخ |
| `date_to` | `date` | خیر | فیلتر تا تاریخ |
### نمونه درخواست
```http
GET /api/sensor-external-api/logs/?farm_uuid=11111111-1111-1111-1111-111111111111&page=1&page_size=20
X-API-Key: 12345
```
نمونه با فیلتر:
```http
GET /api/sensor-external-api/logs/?farm_uuid=11111111-1111-1111-1111-111111111111&physical_device_uuid=55555555-5555-5555-5555-555555555555&date_from=2025-05-01&date_to=2025-05-10&page=1&page_size=20
X-API-Key: 12345
```
### پاسخ موفق
```json
{
"code": 200,
"msg": "success",
"count": 2,
"next": "http://example.com/api/sensor-external-api/logs/?farm_uuid=11111111-1111-1111-1111-111111111111&page=2&page_size=1",
"previous": null,
"data": [
{
"id": 12,
"farm_uuid": "11111111-1111-1111-1111-111111111111",
"sensor_catalog_uuid": "22222222-2222-2222-2222-222222222222",
"physical_device_uuid": "55555555-5555-5555-5555-555555555555",
"farm_sensor": {
"uuid": "99999999-9999-9999-9999-999999999999",
"sensor_catalog_uuid": "22222222-2222-2222-2222-222222222222",
"physical_device_uuid": "55555555-5555-5555-5555-555555555555",
"name": "External device 2",
"sensor_type": "soil_sensor",
"is_active": true,
"specifications": {
"model": "FH-2"
},
"power_source": {
"type": "solar"
},
"created_at": "2024-01-01T10:00:00Z",
"updated_at": "2024-01-01T10:00:00Z"
},
"sensor_catalog": {
"uuid": "22222222-2222-2222-2222-222222222222",
"code": "ext-sensor-log-2",
"name": "External Sensor Log 2",
"description": "Sensor catalog for second log",
"customizable_fields": [],
"supported_power_sources": [],
"returned_data_fields": ["humidity"],
"sample_payload": {},
"is_active": true,
"created_at": "2024-01-01T10:00:00Z",
"updated_at": "2024-01-01T10:00:00Z"
},
"payload": {
"temp": 18
},
"created_at": "2025-05-02T11:00:00Z"
}
]
}
```
### توضیح فیلدهای ریشه پاسخ
| فیلد | نوع | توضیح |
|---|---|---|
| `code` | `number` | کد داخلی backend |
| `msg` | `string` | پیام |
| `count` | `number` | تعداد کل آیتم‌ها قبل از pagination |
| `next` | `string \| null` | لینک صفحه بعد |
| `previous` | `string \| null` | لینک صفحه قبل |
| `data` | `array` | داده‌های صفحه فعلی |
### توضیح هر آیتم داخل `data`
| فیلد | نوع | توضیح |
|---|---|---|
| `id` | `number` | شناسه لاگ |
| `farm_uuid` | `string` | UUID مزرعه |
| `sensor_catalog_uuid` | `string \| null` | UUID کاتالوگ سنسور |
| `physical_device_uuid` | `string` | UUID دستگاه |
| `farm_sensor` | `object \| null` | اطلاعات سنسور مزرعه |
| `sensor_catalog` | `object \| null` | اطلاعات catalog |
| `payload` | `object` | داده خام ارسالی از device |
| `created_at` | `string` | زمان ثبت لاگ |
### ساختار `farm_sensor`
| فیلد | نوع |
|---|---|
| `uuid` | `string` |
| `sensor_catalog_uuid` | `string \| null` |
| `physical_device_uuid` | `string` |
| `name` | `string` |
| `sensor_type` | `string` |
| `is_active` | `boolean` |
| `specifications` | `object` |
| `power_source` | `object` |
| `created_at` | `string` |
| `updated_at` | `string` |
### ساختار `sensor_catalog`
| فیلد | نوع |
|---|---|
| `uuid` | `string` |
| `code` | `string` |
| `name` | `string` |
| `description` | `string` |
| `customizable_fields` | `array` |
| `supported_power_sources` | `array` |
| `returned_data_fields` | `array` |
| `sample_payload` | `object` |
| `is_active` | `boolean` |
| `created_at` | `string` |
| `updated_at` | `string` |
### فیلترها
#### فیلتر با `physical_device_uuid`
فقط لاگ‌های مربوط به یک device خاص برمی‌گردد.
#### فیلتر با `sensor_type`
بر اساس `sensor_type` سنسور مزرعه فیلتر می‌کند.
#### فیلتر با `date_from` و `date_to`
بر اساس بازه تاریخ فیلتر می‌کند.
نکته:
- اگر هر دو ارسال شوند، `date_from` باید کوچک‌تر یا مساوی `date_to` باشد.
### خطاهای ممکن
#### `400 Bad Request`
اگر `page` یا `page_size` ارسال نشود:
```json
{
"page": ["This field is required."],
"page_size": ["This field is required."]
}
```
اگر `date_from > date_to` باشد:
```json
{
"date_to": ["date_to must be greater than or equal to date_from."]
}
```
اگر `page_size > 100` باشد:
```json
{
"page_size": ["Ensure this value is less than or equal to 100."]
}
```
#### `401 Unauthorized`
اگر API key وجود نداشته باشد:
```json
{
"detail": "API key is required."
}
```
اگر API key اشتباه باشد:
```json
{
"detail": "Invalid API key."
}
```
#### `503 Service Unavailable`
اگر migrationهای جدول‌های لازم اجرا نشده باشند:
```json
{
"code": 503,
"msg": "Required tables are not ready. Run migrations."
}
```
### نکات فرانت
- داده‌ها descending هستند؛ جدیدترین لاگ اول می‌آید.
- `farm_sensor` و `sensor_catalog` ممکن است `null` باشند.
- `payload` داینامیک است و ساختار ثابتی ندارد؛ UI باید generic باشد.
- برای table view بهتر است `payload` را stringify نکنید و فیلدهای مهم را extract کنید.
- برای pagination از `count`، `next` و `previous` استفاده کنید.
---
## 7) تفاوت مهم بین این APIها
| Endpoint | ساختار پاسخ | نیازمندی auth |
|---|---|---|
| `/api/sensor-7-in-1/summary/` | wrapped: `code/msg/data` | Bearer token / session |
| `/api/sensors/comparison-chart/` | raw json | Bearer token / session |
| `/api/sensors/radar-chart/` | raw json | Bearer token / session |
| `/api/sensors/values-list/` | raw json | Bearer token / session |
| `/api/sensor-external-api/logs/` | wrapped + paginated | `X-API-Key` |
---
## 8) پیشنهاد برای استفاده در فرانت
### برای dashboard اصلی
از `GET /api/sensor-7-in-1/summary/` استفاده کنید، چون بیشتر widgetها را یکجا می‌دهد.
### برای chartهای مستقل
- اگر chart جداگانه و lightweight می‌خواهید از:
- `GET /api/sensors/comparison-chart/`
- `GET /api/sensors/radar-chart/`
### برای stat card list
- از `GET /api/sensors/values-list/` استفاده کنید.
### برای page تاریخچه یا debug
- از `GET /api/sensor-external-api/logs/` استفاده کنید.
---
## 9) فایل‌های بک‌اند مرتبط
- `sensor_7_in_1/views.py`
- `sensor_7_in_1/serializers.py`
- `sensor_7_in_1/services.py`
- `sensor_7_in_1/tests.py`
- `sensor_external_api/views.py`
- `sensor_external_api/serializers.py`
- `sensor_external_api/tests.py`
- `sensor_external_api/authentication.py`
Reference in New Issue Copy Permalink