# API Documentation - DriverTruck (Ứng dụng Lái xe - Quản lý Xe tải)

Tài liệu mô tả các API liên quan đến quản lý xe tải dành cho lái xe trên ứng dụng mobile.

## Mục lục
1. [Lấy danh sách xe tải tât cả xe](#1-lấy-danh-sách-tất-cả-xe-tải-theo-chi-nhánh)
2. [Lấy danh sách xe tải có thể nhận](#2-lấy-danh-sách-xe-tải-có-thể-nhận)
3. [Nhận xe (Check-in)](#3-nhận-xe-check-in)
4. [Trả xe (Check-out)](#4-trả-xe-check-out)
5. [Đổ dầu](#5-đổ-dầu-cho-xe-tải)
6. [Lấy xe tải hiện tại](#6-kiểm-tra-xe-hiện-tại-của-người-dùng)
7. [Tra cứu lịch sử đổ dầu](#7-tra-cứu-lịch-sử-đổ-dầu)

---

## Các Endpoints

### 1. Lấy danh sách tất cả xe tải theo chi nhánh
Lấy danh sách tất cả xe tải thuộc chi nhánh của người dùng hiện tại (bao gồm các xe đang có người phụ trách).

- **Endpoint**: `GET /api/DriverTruck/GetTrucksByAgency`
- **Authorization**: `DriverTruck.GetTrucksByAgency`

**Response:**
```json
{
  "Result": 1,
  "Message": "Success",
  "Items": [
    {
      "Id": 1,
      "LicensePlate": "29H-12345",
      "AgencyName": "Chi nhánh Hà Nội",
      "OperatingStatus": 1,
      "Status": 1,
      "CurrentDriverId": 5
    }
  ]
}
```

### 2. Lấy danh sách xe tải có thể nhận
Chỉ lấy các xe tải thuộc chi nhánh hiện tại mà chưa có người phụ trách (`CurrentDriverId == 0`).

- **Endpoint**: `GET /api/DriverTruck/GetAvailableTrucks`
- **Authorization**: `DriverTruck.GetAvailableTrucks`

**Response:**
```json
{
  "Result": 1,
  "Message": "Success",
  "Items": [
    {
      "Id": 2,
      "LicensePlate": "29H-67890",
      "AgencyName": "Chi nhánh Hà Nội",
      "OperatingStatus": 0,
      "Status": 1,
      "CurrentDriverId": 0
    }
  ]
}
```

### 3. Nhận xe (Check-in)
Lái xe nhận một chiếc xe để bắt đầu làm việc. Yêu cầu upload hình ảnh xác nhận.

- **Endpoint**: `POST /api/DriverTruck/CheckInTruck`
- **Authorization**: `DriverTruck.CheckInTruck`

**Request (Form-Data):**
- `TruckId` (int, required): ID xe tải muốn nhận.
- `CurrentOdo` (int, required): Số ODO hiện tại của xe (phải >= 0).
- `Note` (string, optional): Ghi chú (tối đa 1024 ký tự).
- `Files` (IFormFile[], optional): Danh sách file hình ảnh chụp nhận xe.

> [!IMPORTANT]
> **Quy tắc validate**
> - Lái xe chỉ có thể nhận xe nếu **chưa phụ trách xe nào khác** ở thời điểm hiện tại.
> - Xe tải muốn nhận phải đang **chưa có người phụ trách** (`CurrentDriverId == 0`).
> - Hệ thống sẽ tự động xác định `AgencyId` từ thông tin của người dùng đăng nhập.

**Response:**
```json
{
  "Result": 1,
  "Message": "Success",
  "Item": {
    "Id": 100,
    "TruckId": 1,
    "LicensePlate": "29H-67890",
    "ActionType": 1,
    "CurrentOdo": 15000,
    "MediaItems": [
      {
        "Id": 50,
        "MediaUrl": "https://media.lada.vn/images/...",
        "MediaType": 1,
        "DisplayOrder": 1
      }
    ]
  }
}
```

### 4. Trả xe (Check-out)
Lái xe trả lại chiếc xe đang phụ trách sau khi kết thúc công việc. Yêu cầu upload hình ảnh.

- **Endpoint**: `POST /api/DriverTruck/CheckOutTruck`
- **Authorization**: `DriverTruck.CheckOutTruck`

**Request (Form-Data):**
- `TruckId` (int, required): ID xe tải muốn trả.
- `CurrentOdo` (int, required): Số ODO hiện tại của xe lúc trả.
- `Note` (string, optional): Ghi chú.
- `Files` (IFormFile[], optional): Danh sách file hình ảnh chụp trả xe.

> [!IMPORTANT]
> **Quy tắc validate**
> Lái xe chỉ có thể trả xe mà mình **đang làm người phụ trách**. Sau khi trả thành công, `CurrentDriverId` của xe sẽ được gán về 0.

**Response:**
```json
{
  "Result": 1,
  "Message": "Success",
  "Item": {
    "Id": 101,
    "TruckId": 1,
    "ActionType": 2,
    "CurrentOdo": 15200
  }
}
```

### 5. Đổ dầu cho xe tải
Lái xe khai báo thông tin đổ dầu cho chiếc xe đang phụ trách trên app mobile.

- **Endpoint**: `POST /api/DriverTruck/DriverFuelRefill`
- **Authorization**: `DriverTruck.DriverFuelRefill`

**Request (Form-Data):**
- `CurrentOdo` (int, required): Số ODO hiện tại của xe lúc đổ dầu.
- `Amount` (decimal, required): Số tiền đổ dầu (> 0).
- `UnitPrice` (decimal, required): Đơn giá dầu (> 0).
- `PaymentMethod` (int, required): Phương thức thanh toán (1 = Card, 2 = Cash).
- `FuelCardId` (int, optional): ID thẻ xăng dầu (nếu `PaymentMethod` = 1).
- `RefillTime` (DateTimeOffset, required): Thời gian đổ dầu.
- `StationName` (string, optional): Tên trạm xăng dầu.
- `StationAddress` (string, optional): Địa chỉ trạm xăng dầu.
- `Notes` (string, optional): Ghi chú.
- `Files` (IFormFile[], optional): Danh sách file hình ảnh minh chứng.
- `MediaTypes` (int[], optional): Loại hình ảnh tương ứng với file (OdoBeforePhoto=10, OdoAfterPhoto=11, FuelPumpPhoto=12, FuelReceiptPhoto=13).

> [!NOTE]
> **Hệ thống tự nhận diện**
> Lái xe không cần cung cấp `TruckId` hay `AgencyId`, hệ thống tự động xác minh người dùng đang phụ trách xe nào và lập phiếu đổ dầu cho xe đó.

**Response:**
```json
{
  "Result": 1,
  "Message": "Success",
  "Item": {
    "Id": 200,
    "TruckId": 1,
    ...
  }
}
```

### 6. Kiểm tra xe hiện tại của người dùng
Lấy thông tin xe mà lái xe đang phụ trách. Giúp ứng dụng mobile hiển thị trạng thái hiện tại.

- **Endpoint**: `GET /api/DriverTruck/GetMyCurrentTruck`
- **Authorization**: `DriverTruck.GetMyCurrentTruck`

**Response:**
*(Nếu người dùng đang phụ trách 1 xe)*
```json
{
  "Result": 1,
  "Message": "Success",
  "Items": [
    {
      "Id": 1,
      "LicensePlate": "29H-12345",
      "AgencyName": "Chi nhánh Hà Nội",
      "OperatingStatus": 1,
      "Status": 1,
      "CurrentDriverId": 5
    }
  ]
}
```
*(Nếu người dùng không phụ trách xe nào)*
```json
{
  "Result": 1,
  "Message": "Success",
   "Items": null
}
```

### 7. Tra cứu lịch sử đổ dầu
Lái xe tra cứu lịch sử đổ dầu của mình. Hỗ trợ phân trang, lọc theo khoảng ngày và từ khóa (biển số xe hoặc tên cây xăng).

- **Endpoint**: `POST /api/DriverTruck/SearchRefillHistory`
- **Authorization**: `DriverTruck.SearchRefillHistory`

**Request (JSON):**
```json
{
  "Pagination": {
    "Start": 0,
    "Number": 10
  },
  "Search": {
    "PredicateObject": {
      "Keyword": "29H-123",
      "RefillStart": "2024-01-01T00:00:00Z",
      "RefillEnd": "2024-12-31T23:59:59Z"
    }
  },
  "Sort": {
    "Predicate": "RefillTime",
    "Reverse": true
  }
}
```

**Response:**
```json
{
  "Result": 1,
  "Message": "Success",
  "Items": [
    {
      "Id": 200,
      "TruckId": 1,
      "TruckLicensePlate": "29H-12345",
      "DriverId": 5,
      "DriverName": "driver_01",
      "Amount": 500000,
      "ActualLiters": 25,
      "UnitPrice": 20000,
      "RefillTime": "2024-03-08T10:00:00Z",
      "StationName": "Trạm xăng số 1",
      ...
    }
  ],
  "TotalCount": 50
}
```
