# API Cập Nhật ODO Đổ Dầu Gần Nhất

## Thông tin Endpoint

**URL:** `POST /api/Truck/UpdateLastRefillOdo`

**Authorization:** Bearer Token - Role: `Truck.UpdateLastRefillOdo`

**Content-Type:** `application/json`

## Mô tả

API này dùng để **cập nhật giá trị ODO đổ dầu gần nhất** của xe tải. Giá trị này được sử dụng để tính số km đã chạy cho lần đổ dầu tiếp theo.

---

## Request

### Query Parameters

| Tên tham số | Kiểu dữ liệu | Bắt buộc | Mô tả |
|-------------|--------------|----------|-------|
| `truckId` | `int` | Có | ID xe tải cần cập nhật (phải > 0) |
| `odoValue` | `int` | Có | Giá trị ODO (km, phải >= 0) |

### Headers

```
Authorization: Bearer {access_token}
```

---

## Response

### Success Response

**Status Code:** `200 OK`

```json
{
  "Result": 0,
  "Message": "Đã cập nhật ODO đổ dầu gần nhất: 15000 km"
}
```

### Response Schema

| Tên trường | Kiểu dữ liệu | Mô tả |
|------------|--------------|-------|
| `Result` | `int` (enum) | `0` = Success, `2` = Failed, `3` = SystemError |
| `Message` | `string` | Thông báo kết quả |

---

## Error Responses

### ID xe tải không hợp lệ

```json
{
  "Result": 2,
  "Message": "ID xe tải không hợp lệ"
}
```

### Giá trị ODO không hợp lệ

```json
{
  "Result": 2,
  "Message": "Giá trị ODO không hợp lệ"
}
```

### Xe tải không tồn tại

```json
{
  "Result": 2,
  "Message": "Không tìm thấy xe tải"
}
```

### ODO mới nhỏ hơn ODO trước đó

```json
{
  "Result": 2,
  "Message": "Giá trị ODO mới (12000) không thể nhỏ hơn ODO đổ dầu trước đó (15000)"
}
```

### Lỗi hệ thống

```json
{
  "Result": 3,
  "Message": "Lỗi hệ thống: [Chi tiết lỗi]"
}
```

---

## Ví dụ

### Request - Cập nhật ODO lần đầu

```bash
curl -X POST "https://api.example.com/api/Truck/UpdateLastRefillOdo?truckId=1&odoValue=15000" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

**Response:**
```json
{
  "Result": 0,
  "Message": "Đã cập nhật ODO đổ dầu gần nhất: 15000 km"
}
```

### Request - Cập nhật ODO lần tiếp theo

```bash
curl -X POST "https://api.example.com/api/Truck/UpdateLastRefillOdo?truckId=1&odoValue=15300" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

**Response:**
```json
{
  "Result": 0,
  "Message": "Đã cập nhật ODO đổ dầu gần nhất: 15300 km"
}
```

### Request - Lỗi: ODO mới nhỏ hơn ODO cũ

```bash
curl -X POST "https://api.example.com/api/Truck/UpdateLastRefillOdo?truckId=1&odoValue=14000" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

**Response:**
```json
{
  "Result": 2,
  "Message": "Giá trị ODO mới (14000) không thể nhỏ hơn ODO đổ dầu trước đó (15300)"
}
```

---

## Frontend Integration Guide

### TypeScript Interface

```typescript
export interface UpdateOdoRequest {
  truckId: number;
  odoValue: number;
}

export interface UpdateOdoResponse {
  Result: ApiResult;
  Message: string;
}
```

### Example Usage

```typescript
async function updateLastRefillOdo(truckId: number, odoValue: number): Promise<void> {
  const response = await fetch(
    `/api/Truck/UpdateLastRefillOdo?truckId=${truckId}&odoValue=${odoValue}`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${getAccessToken()}`
      }
    }
  );

  const result: UpdateOdoResponse = await response.json();

  if (result.Result !== ApiResult.Success) {
    throw new Error(result.Message);
  }

  console.log(result.Message); // "Đã cập nhật ODO đổ dầu gần nhất: 15000 km"
}
```

### Validation

```typescript
function validateOdoUpdate(truckId: number, odoValue: number, currentOdo?: number): string | null {
  if (truckId <= 0) {
    return 'ID xe tải không hợp lệ';
  }

  if (odoValue < 0) {
    return 'Giá trị ODO phải >= 0';
  }

  if (currentOdo !== undefined && odoValue < currentOdo) {
    return `Giá trị ODO mới (${odoValue}) không thể nhỏ hơn ODO hiện tại (${currentOdo})`;
  }

  return null;
}
```

---

## Lưu ý quan trọng

> [!IMPORTANT]
> - Giá trị ODO mới phải **lớn hơn hoặc bằng** ODO đổ dầu trước đó
> - Giá trị ODO phải **>= 0**
> - API này chỉ cập nhật trường `LastRefillOdo`, không ảnh hưởng đến các trường khác

> [!TIP]
> - Sử dụng API này sau mỗi lần đổ dầu để cập nhật ODO gần nhất
> - Giá trị này sẽ được dùng để tính số km đã chạy cho lần đổ dầu tiếp theo
> - Công thức: `Số km đã chạy = ODO hiện tại - LastRefillOdo`

> [!WARNING]
> - API này yêu cầu role `Truck.UpdateLastRefillOdo`
> - Không thể cập nhật ODO nhỏ hơn giá trị trước đó (để tránh sai sót dữ liệu)

---

## Support

Nếu có vấn đề khi tích hợp, vui lòng liên hệ Backend team với thông tin:
- Request payload đã gửi
- Response nhận được
- Expected behavior vs Actual behavior
