# Crop Zoning API Integration

## نحوه ارتباط با API

### 1. دریافت اطلاعات Area و Zones

```typescript
GET /api/crop-zoning/area/?sensor_uuid=<sensor_uuid>
```

این endpoint به صورت task-based کار می‌کند:

**مراحل:**
1. اولین بار که API را صدا می‌زنید، task ساخته می‌شود و `status: 'PENDING'` برمی‌گرداند
2. باید هر 2 ثانیه polling کنید تا `status` به `'SUCCESS'` برسد
3. در حین polling، از فیلدهای زیر برای نمایش progress استفاده کنید:
   - `task.progress_percent`: درصد پیشرفت (0-100)
   - `task.message`: پیام فارسی برای نمایش
   - `task.completed_zones` / `task.total_zones`: تعداد زون‌های پردازش شده

**مثال پاسخ در حال پردازش:**
```json
{
  "status": "success",
  "data": {
    "task": {
      "status": "PROCESSING",
      "stage_label": "در حال پردازش زون‌ها",
      "total_zones": 364,
      "completed_zones": 182,
      "progress_percent": 50,
      "message": "از مجموع 364 زون، 182 زون پردازش شده..."
    },
    "area": { ... },
    "zones": []
  }
}
```

**مثال پاسخ موفق:**
```json
{
  "status": "success",
  "data": {
    "task": {
      "status": "SUCCESS",
      "progress_percent": 100,
      "total_zones": 364,
      "completed_zones": 364
    },
    "area": {
      "type": "Feature",
      "geometry": { "type": "Polygon", "coordinates": [...] }
    },
    "zones": [
      {
        "zoneId": "zone-0",
        "geometry": { "type": "Polygon", "coordinates": [...] },
        "crop": "wheat",
        "matchPercent": 89,
        "waterNeed": "4820-5820 m³/ha"
      }
    ]
  }
}
```

### 2. نمایش Progress Bar در UI

```tsx
// وقتی task در حال پردازش است
{loading && progress && (
  <Box>
    <Typography>{progress.message}</Typography>
    <LinearProgress variant="determinate" value={progress.percent} />
    <Typography>{progress.percent}%</Typography>
  </Box>
)}
```

### 3. وضعیت‌های Task

- `IDLE`: هنوز task ساخته نشده
- `PENDING`: task ساخته شده، منتظر شروع
- `PROCESSING`: در حال پردازش زون‌ها
- `SUCCESS`: همه زون‌ها پردازش شدند
- `FAILURE`: خطا در پردازش

### 4. Flow کامل در کد

```typescript
const loadArea = async () => {
  let polls = 0;
  
  while (polls < MAX_POLLS) {
    const res = await cropZoningService.getArea(sensorUuid);
    const task = res.task;
    
    // نمایش progress
    if (task) {
      setProgress({
        message: task.message || task.stage_label,
        percent: task.progress_percent || 0
      });
    }
    
    // بررسی وضعیت
    if (task?.status === 'SUCCESS') {
      setAreaGeoJson(res.area);
      setZonesData(res.zones);
      break;
    }
    
    if (task?.status === 'FAILURE') {
      throw new Error(task.message);
    }
    
    // اگر در حال پردازش است، صبر کن و دوباره بررسی کن
    if (task?.status === 'PENDING' || task?.status === 'PROCESSING') {
      await sleep(2000);
      polls++;
    } else {
      break;
    }
  }
};
```

## نکات مهم

1. **Polling Interval**: 2 ثانیه (نه کمتر، نه بیشتر)
2. **Max Attempts**: حداکثر 100 بار تلاش (200 ثانیه = 3.3 دقیقه)
3. **Progress Bar**: حتما از `LinearProgress` با `variant="determinate"` استفاده کنید
4. **Sensor UUID**: باید از props یا context دریافت شود (فعلاً hardcode شده)
