# API Documentation - Fuel Refill Report By Driver

## Mục lục
1. [Báo cáo đổ dầu theo lái xe](#1-báo-cáo-đổ-dầu-theo-lái-xe)

---

## 1. Báo cáo đổ dầu theo lái xe

### Endpoint
`POST /api/FuelRefillReport/GetByDriver`

### Authorization
- **Role**: `FuelRefillReport.GetByDriver`
- **Header**: `Authorization: Bearer {token}`

### Request Body

```json
{
  "Pagination": {
    "PageIndex": 1,
    "PageSize": 100
  },
  "Sort": {
    "Predicate": "DriverFullName",
    "Reverse": false
  },
  "Search": {
    "PredicateObject": {
      "StartDate": "2026-01-01T00:00:00+07:00",
      "EndDate": "2026-01-31T23:59:59+07:00",
      "DriverIds": [1, 2, 3],
      "TruckIds": [10, 20]
    }
  }
}
```

### Request Parameters

| Tên | Kiểu | Bắt buộc | Mô tả |
|-----|------|----------|-------|
| `StartDate` | DateTimeOffset | Không | Thời gian bắt đầu lọc (mặc định: 30 ngày trước) |
| `EndDate` | DateTimeOffset | Không | Thời gian kết thúc lọc (mặc định: hôm nay) |
| `DriverIds` | int[] | Không | Danh sách ID lái xe cần lọc |
| `TruckIds` | int[] | Không | Danh sách ID xe cần lọc |

> [!NOTE]
> **Mặc định**
> - Nếu không truyền `StartDate` và `EndDate`, hệ thống sẽ lấy dữ liệu 30 ngày gần nhất.
> - Nếu không truyền `DriverIds` hoặc `TruckIds`, sẽ lấy tất cả lái xe/xe.

---

### Response

```json
{
  "Result": 1,
  "Message": null,
  "Items": [
    {
      "DriverId": 5,
      "DriverUserName": "driver01",
      "DriverFullName": "Nguyễn Văn A",
      "TotalDistanceKm": 1500,
      "TotalActualLiters": 180.5,
      "TotalActualAmount": 3610000,
      "TotalQuotaLiters": 200.0,
      "TotalQuotaAmount": 4000000,
      "TotalFuelIncome": 390000,
      "TruckDetails": [
        {
          "TruckId": 10,
          "TruckPlate": "51C-12345",
          "TruckName": "Xe tải 5 tấn",
          "TotalDistanceKm": 1000,
          "TotalActualLiters": 120.5,
          "TotalActualAmount": 2410000,
          "TotalQuotaLiters": 130.0,
          "TotalQuotaAmount": 2600000,
          "TotalFuelIncome": 190000
        },
        {
          "TruckId": 11,
          "TruckPlate": "51C-67890",
          "TruckName": "Xe tải 8 tấn",
          "TotalDistanceKm": 500,
          "TotalActualLiters": 60.0,
          "TotalActualAmount": 1200000,
          "TotalQuotaLiters": 70.0,
          "TotalQuotaAmount": 1400000,
          "TotalFuelIncome": 200000
        }
      ]
    }
  ],
  "TotalItem": {
    "DriverId": 0,
    "DriverUserName": "",
    "DriverFullName": "TỔNG CỘNG",
    "TotalDistanceKm": 1500,
    "TotalActualLiters": 180.5,
    "TotalActualAmount": 3610000,
    "TotalQuotaLiters": 200.0,
    "TotalQuotaAmount": 4000000,
    "TotalFuelIncome": 390000,
    "TruckDetails": []
  },
  "TotalRecord": 1
}
```

### Response Fields

#### Driver Item

| Tên | Kiểu | Mô tả |
|-----|------|-------|
| `DriverId` | int | ID lái xe |
| `DriverUserName` | string | Tên đăng nhập lái xe |
| `DriverFullName` | string | Họ và tên lái xe |
| `TotalDistanceKm` | int | Số km chạy trong khoảng thời gian (tổng DistanceKm) |
| `TotalActualLiters` | decimal | Số lít đổ dầu thực tế (tổng ActualLiters) |
| `TotalActualAmount` | decimal | Số tiền đổ dầu thực tế (tổng Amount) |
| `TotalQuotaLiters` | decimal | Số lít dầu khoán (tổng QuotaLiters) |
| `TotalQuotaAmount` | decimal | Số tiền đổ dầu khoán (tổng QuotaLiters × UnitPrice) |
| `TotalFuelIncome` | decimal | Số tiền thu nhập dầu (tổng (QuotaLiters - ActualLiters) × UnitPrice) |
| `TruckDetails` | array | Chi tiết số liệu theo từng xe mà lái xe đã chạy |

#### Truck Detail Item (trong TruckDetails)

| Tên | Kiểu | Mô tả |
|-----|------|-------|
| `TruckId` | int | ID xe |
| `TruckPlate` | string | Biển số xe |
| `TruckName` | string | Tên xe |
| `TotalDistanceKm` | int | Số km chạy với xe này |
| `TotalActualLiters` | decimal | Số lít đổ dầu thực tế với xe này |
| `TotalActualAmount` | decimal | Số tiền đổ dầu thực tế với xe này |
| `TotalQuotaLiters` | decimal | Số lít dầu khoán với xe này |
| `TotalQuotaAmount` | decimal | Số tiền đổ dầu khoán với xe này |
| `TotalFuelIncome` | decimal | Số tiền thu nhập dầu với xe này |

> [!IMPORTANT]
> **Logic tính toán TotalFuelIncome**
> - **Giá trị dương (+)**: Lái xe được hưởng (đổ ít hơn định mức khoán)
> - **Giá trị âm (-)**: Lái xe phải bù (đổ nhiều hơn định mức khoán)

> [!NOTE]
> **TruckDetails**
> Mỗi lái xe có thể chạy nhiều xe trong khoảng thời gian báo cáo. Array `TruckDetails` chứa số liệu chi tiết của từng xe mà lái xe đó đã sử dụng.

---

### Error Response

```json
{
  "Result": 0,
  "Message": "Lỗi khi gọi stored procedure: [Chi tiết lỗi]"
}
```

---

## Stored Procedures

| Tên | Mô tả |
|-----|-------|
| `sp_GetFuelRefillReportByDriver` | Lấy dữ liệu tổng hợp theo lái xe |
| `sp_GetFuelRefillReportByDriverAndTruck` | Lấy chi tiết theo lái xe và xe |

**Vị trí**:
- [sp_GetFuelRefillReportByDriver.sql](file:///e:/Projects/LADA/SourceCode/V23/Ladaer.BackEnd/Ladaer.BackEnd/Scripts/sp_GetFuelRefillReportByDriver.sql)
- [sp_GetFuelRefillReportByDriverAndTruck.sql](file:///e:/Projects/LADA/SourceCode/V23/Ladaer.BackEnd/Ladaer.BackEnd/Scripts/sp_GetFuelRefillReportByDriverAndTruck.sql)

---

## 2. Xuất Excel báo cáo đổ dầu theo lái xe

### Endpoint
`POST /api/FuelRefillReport/ExportByDriver`

### Authorization
- **Role**: `FuelRefillReport.ExportByDriver`
- **Header**: `Authorization: Bearer {token}`

### Request Body

> [!NOTE]
> **Request Body giống hệt với API GetByDriver**. Điều kiện lọc được sử dụng chung để đảm bảo tính nhất quán.

```json
{
  "Pagination": {
    "PageIndex": 1,
    "PageSize": 100
  },
  "Sort": {
    "Predicate": "DriverFullName",
    "Reverse": false
  },
  "Search": {
    "PredicateObject": {
      "StartDate": "2026-01-01T00:00:00+07:00",
      "EndDate": "2026-01-31T23:59:59+07:00",
      "DriverIds": [1, 2, 3],
      "TruckIds": [10, 20]
    }
  }
}
```

---

### Response (Success)

```json
{
  "Result": 1,
  "Message": "Xuất file Excel thành công",
  "FilePath": "/exports/fuel-refill-reports/BaoCaoDoDau_TheoLaiXe_20260208_171500.xlsx",
  "FileName": "BaoCaoDoDau_TheoLaiXe_20260208_171500.xlsx",
  "FileSize": 12345,
  "TotalRecords": 15,
  "DownloadUrl": "/files/exports/fuel-refill-reports/BaoCaoDoDau_TheoLaiXe_20260208_171500.xlsx",
  "ProcessStartTime": "2026-02-08T17:15:00+07:00",
  "ProcessEndTime": "2026-02-08T17:15:02+07:00",
  "ProcessingTimeMs": 2000
}
```

### Response Fields

| Tên | Kiểu | Mô tả |
|-----|------|-------|
| `FilePath` | string | Đường dẫn file trên server |
| `FileName` | string | Tên file Excel |
| `FileSize` | long | Kích thước file (bytes) |
| `TotalRecords` | int | Số bản ghi đã xuất |
| `DownloadUrl` | string | URL để download file |
| `ProcessStartTime` | DateTimeOffset | Thời gian bắt đầu xử lý |
| `ProcessEndTime` | DateTimeOffset | Thời gian kết thúc xử lý |
| `ProcessingTimeMs` | long | Thời gian xử lý (milliseconds) |

---

### Error Response

```json
{
  "Result": 0,
  "Message": "Lỗi khi xuất file Excel: [Chi tiết lỗi]"
}
```

---

### Excel File Structure

| Cột | Tên | Mô tả |
|-----|-----|-------|
| A | STT | Số thứ tự |
| B | Lái xe | Họ và tên lái xe |
| C | Biển số xe | Biển số xe |
| D | Tên xe | Tên xe |
| E | Số km chạy | Tổng số km chạy |
| F | Số lít thực tế | Tổng số lít đổ thực tế |
| G | Số tiền thực tế | Tổng số tiền đổ thực tế |
| H | Số lít khoán | Tổng số lít khoán |
| I | Số tiền khoán | Tổng số tiền khoán |
| J | Thu nhập dầu | Số tiền thu nhập dầu (xanh: dương, đỏ: âm) |

> [!TIP]
> File Excel bao gồm dòng **TỔNG CỘNG** ở cuối với các số liệu tổng hợp.

