# 📊 FUEL REPORTS API DOCUMENTATION

## 🎯 NEW ENDPOINTS ADDED

Dua endpoint baru telah ditambahkan ke CRUD Fuel API untuk mendukung laporan fuel yang lebih detail dan terstruktur.

## 📋 ENDPOINTS

### 1. 📈 Summary Report
**Ringkasan fuel per nopol dengan filter bulan dan tahun**

```
GET /fuel?action=summary&bulan={month}&tahun={year}&user_group_id={group_id}
```

#### Parameters:
- `action=summary` (required) - Menentukan jenis report
- `bulan` (optional) - Bulan (1-12), default: bulan saat ini
- `tahun` (optional) - Tahun (2000-2100), default: tahun saat ini  
- `user_group_id` (optional) - Filter berdasarkan user group ID

#### Response Format:
```json
{
  "success": true,
  "report_type": "summary",
  "data": [
    {
      "Nopol": "B1234AB",
      "Nama_Supir": "John Doe, Jane Smith",
      "Bulan": 1,
      "Tahun": 2026,
      "Nama_Bulan": "Januari",
      "Total_Liter": 500,
      "Total_Harga": 7500000,
      "Odometer_Terakhir": 125000
    }
  ],
  "filters": {
    "bulan": 1,
    "tahun": 2026,
    "nama_bulan": "Januari",
    "user_group_id": 123
  },
  "summary": {
    "total_kendaraan": 10,
    "total_liter": 5000,
    "total_harga": 75000000,
    "rata_rata_liter_per_kendaraan": 500.0,
    "rata_rata_harga_per_kendaraan": 7500000.0
  }
}
```

### 2. 📋 Detail Report
**Detail transaksi fuel per nopol dengan filter bulan dan tahun**

```
GET /fuel?action=detail&nopol={nopol}&bulan={month}&tahun={year}&user_group_id={group_id}
```

#### Parameters:
- `action=detail` (required) - Menentukan jenis report
- `nopol` (required) - Nomor polisi kendaraan
- `bulan` (optional) - Bulan (1-12), default: bulan saat ini
- `tahun` (optional) - Tahun (2000-2100), default: tahun saat ini
- `user_group_id` (optional) - Filter berdasarkan user group ID

#### Response Format:
```json
{
  "success": true,
  "report_type": "detail",
  "data": [
    {
      "id": 1,
      "Nopol": "B1234AB",
      "Nama_Supir": "John Doe",
      "Tgl": "2026-01-15",
      "Jumlah_Liter": 50,
      "Harga": 750000,
      "Odometer": 125000,
      "Catatan": "Isi bensin rutin"
    }
  ],
  "filters": {
    "nopol": "B1234AB",
    "bulan": 1,
    "tahun": 2026,
    "nama_bulan": "Januari",
    "user_group_id": 123
  },
  "summary": {
    "nopol": "B1234AB",
    "nama_supir": "John Doe, Jane Smith",
    "bulan": 1,
    "tahun": 2026,
    "nama_bulan": "Januari",
    "total_liter": 500,
    "total_harga": 7500000,
    "odometer_terakhir": 125000,
    "jumlah_transaksi": 10,
    "rata_rata_liter_per_transaksi": 50.0,
    "rata_rata_harga_per_transaksi": 750000.0
  }
}
```

## 🔐 AUTHENTICATION

Kedua endpoint memerlukan authentication Bearer token:

```javascript
headers: {
  'Authorization': 'Bearer your_token_here'
}
```

## 🎨 FRONTEND INTEGRATION

### JavaScript/Vue.js Usage:

```javascript
import { fuelAPI } from '@/services/api'

// Get summary report
const summaryData = await fuelAPI.getFuelSummary({
  bulan: 1,
  tahun: 2026,
  user_group_id: 123
})

// Get detail report
const detailData = await fuelAPI.getFuelDetail({
  nopol: 'B1234AB',
  bulan: 1,
  tahun: 2026,
  user_group_id: 123
})
```

## 📊 SQL QUERIES IMPLEMENTED

### Summary Report Query:
```sql
SELECT 
    f.Nopol,
    STUFF((
        SELECT DISTINCT ', ' + f2.Nama_Supir
        FROM fuel f2
        WHERE f2.Nopol = f.Nopol
        AND MONTH(f2.Tgl) = MONTH(f.Tgl)
        AND YEAR(f2.Tgl) = YEAR(f.Tgl)
        AND f2.Edit_By_ID = f.Edit_By_ID
        FOR XML PATH(''), TYPE
    ).value('.', 'NVARCHAR(MAX)'), 1, 2, '') AS Nama_Supir,
    MONTH(f.Tgl) AS Bulan,
    YEAR(f.Tgl) AS Tahun,
    SUM(f.Jumlah_Liter) AS Total_Liter,
    SUM(f.Harga) AS Total_Harga,
    MAX(f.Odometer) AS Odometer_Terakhir
FROM fuel f
WHERE MONTH(Tgl) = ? AND YEAR(Tgl) = ? AND Edit_By_ID = ?
GROUP BY f.Nopol, MONTH(f.Tgl), YEAR(f.Tgl), f.Edit_By_ID
ORDER BY f.Nopol
```

### Detail Report Query:
```sql
SELECT *
FROM fuel
WHERE Nopol = ?
AND MONTH(Tgl) = ?
AND YEAR(Tgl) = ?
AND Edit_By_ID = ?
ORDER BY Tgl ASC
```

## 🧪 TESTING

### Test Summary Report:
```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "http://localhost:8000/fuel?action=summary&bulan=1&tahun=2026"
```

### Test Detail Report:
```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "http://localhost:8000/fuel?action=detail&nopol=B1234AB&bulan=1&tahun=2026"
```

## ⚠️ ERROR HANDLING

### Common Errors:

#### 400 Bad Request - Invalid Month:
```json
{
  "error": "Invalid month",
  "details": "Month must be between 1 and 12",
  "received": 13
}
```

#### 400 Bad Request - Missing Nopol:
```json
{
  "error": "Missing required parameter",
  "details": "nopol parameter is required for detail report"
}
```

#### 401 Unauthorized:
```json
{
  "error": "Authentication required",
  "details": "Bearer token is required"
}
```

## 🎯 USE CASES

### 1. **Monthly Fuel Summary Dashboard**
- Tampilkan ringkasan fuel semua kendaraan per bulan
- Grafik total liter dan harga per kendaraan
- Ranking kendaraan berdasarkan konsumsi fuel

### 2. **Vehicle Fuel Detail Analysis**
- Detail transaksi fuel per kendaraan
- Analisis pola pengisian fuel
- Tracking odometer dan efisiensi fuel

### 3. **Management Reporting**
- Laporan bulanan untuk management
- Analisis biaya fuel per periode
- Perbandingan konsumsi antar kendaraan

## 📈 PERFORMANCE

- **Optimized Queries**: Menggunakan SQL Server functions untuk performa optimal
- **Memory Management**: Built-in memory monitoring dan cleanup
- **Big Data Ready**: Mendukung dataset besar dengan pagination
- **Caching Ready**: Response dapat di-cache untuk performa lebih baik

## 🔄 INTEGRATION NOTES

### Database Compatibility:
- ✅ SQL Server (Primary)
- ✅ SQL Server Express
- ✅ Azure SQL Database

### PHP Compatibility:
- ✅ PHP 5.6+
- ✅ PHP 7.x
- ✅ PHP 8.x

### Frontend Integration:
- ✅ Vue.js/Quasar (Implemented)
- ✅ React (Compatible)
- ✅ Angular (Compatible)
- ✅ Vanilla JavaScript (Compatible)

---

**AUTHOR**: Rodhi  
**DATE**: 2026-01-19  
**VERSION**: 1.0

🎉 **FUEL REPORTS API READY FOR PRODUCTION!**