ytp/docs/API.md

# YTP API Dokümantasyonu

Yakıt Takip Sistemi REST API endpoints ve WebSocket olayları için kapsamlı dokümantasyon.

## 📋 İçerik

- [Genel Bakış](#genel-bakış)
- [Kimlik Doğrulama](#kimlik-doğrulama)
- [Admin API](#admin-api)
- [Yakıt Sorumlusu API](#yakıt-sorumlusu-api)
- [Mal Sorumlusu API](#mal-sorumlusu-api)
- [WebSocket Olayları](#websocket-olayları)
- [Hata Kodları](#hata-kodları)

## 🔧 Genel Bakış

### Base URL
```
http://localhost:5005/api
```

### İstek Formatı
- **Content-Type**: `application/json`
- **Authorization**: `X-Session-Token` header

### Yanıt Formatı
```json
{
  "message": "Başarılı mesaj",
  "data": { ... },
  "error": "Hata mesajı (varsa)"
}
```

## 🔐 Kimlik Doğrulama

### POST /auth/login
Kullanıcı girişi için endpoint.

**İstek:**
```json
{
  "username": "admin",
  "password": "Admin!123"
}
```

**Başarılı Yanıt (200):**
```json
{
  "token": "a1b2c3d4e5f6...",
  "user": {
    "id": 1,
    "username": "admin",
    "role": "admin",
    "displayName": "Istasyon Admini"
  }
}
```

**Hata Yanıtları:**
- `400` - Kullanıcı adı veya şifre eksik
- `401` - Kullanıcı adı veya şifre hatalı
- `500` - Sunucu hatası

### POST /auth/logout
Oturumu kapatma.

**Headers:**
```
X-Session-Token: <token>
```

**Yanıt (200):**
```json
{
  "message": "Oturum kapatildi."
}
```

### GET /session
Mevcut oturum bilgilerini getirme.

**Headers:**
```
X-Session-Token: <token>
```

**Yanıt (200):**
```json
{
  "user": {
    "id": 1,
    "username": "admin",
    "role": "admin",
    "displayName": "Istasyon Admini"
  }
}
```

## 👑 Admin API

### Mal Sorumluları Yönetimi

#### GET /inventory-managers
Tüm mal sorumlularını listeler.

**Yetki:** Admin

**Yanıt (200):**
```json
{
  "managers": [
    {
      "id": 3,
      "username": "malsorum1",
      "displayName": "Mal Sorumlusu 1",
      "createdAt": "2024-01-01T10:00:00Z"
    }
  ]
}
```

#### POST /inventory-managers
Yeni mal sorumlusu oluşturur.

**Yetki:** Admin

**İstek:**
```json
{
  "username": "malsorum2",
  "password": "Mal@123",
  "displayName": "Mal Sorumlusu 2"
}
```

**Yanıt (201):**
```json
{
  "manager": {
    "id": 4,
    "username": "malsorum2",
    "displayName": "Mal Sorumlusu 2",
    "role": "inventory_manager"
  }
}
```

#### PUT /inventory-managers/:id
Mal sorumlusunu günceller.

**Yetki:** Admin

**İstek:**
```json
{
  "displayName": "Güncellenmiş İsim",
  "password": "YeniŞifre123"
}
```

#### DELETE /inventory-managers/:id
Mal sorumlusunu siler.

**Yetki:** Admin

**Yanıt (204)** - No Content

### Araç Yönetimi

#### GET /vehicles
Tüm araçları listeler.

**Yetki:** Admin

**Yanıt (200):**
```json
{
  "vehicles": [
    {
      "id": 1,
      "brand": "Ford",
      "model": "Transit",
      "year": 2021,
      "plate": "34 AYT 312",
      "createdAt": "2024-01-01T10:00:00Z"
    }
  ]
}
```

#### POST /vehicles
Yeni araç oluşturur.

**Yetki:** Admin

**İstek:**
```json
{
  "brand": "Ford",
  "model": "Transit",
  "year": 2021,
  "plate": "34 AYT 312"
}
```

**Yanıt (201):**
```json
{
  "vehicle": {
    "id": 2,
    "brand": "Ford",
    "model": "Transit",
    "year": 2021,
    "plate": "34 AYT 312"
  }
}
```

#### PUT /vehicles/:id
Araç bilgilerini günceller.

**Yetki:** Admin

#### DELETE /vehicles/:id
Araç kaydını siler.

**Yetki:** Admin

### Birlik Yönetimi

#### GET /units
Tüm birlikleri listeler.

**Yetki:** Admin

**Yanıt (200):**
```json
{
  "units": [
    {
      "id": 1,
      "name": "Merkez Birlik",
      "address": "Cumhuriyet Mah. İstasyon Cad. No:12/1 İstanbul",
      "stk": "STK-4589",
      "btk": "BTK-9021",
      "contactName": "Yzb. Murat Kaya",
      "contactRank": "Yuzbasi",
      "contactRegistry": "MK4587",
      "contactIdentity": "25478963210",
      "contactPhone": "+90 532 456 78 12",
      "createdAt": "2024-01-01T10:00:00Z"
    }
  ]
}
```

#### POST /units
Yeni birlik oluşturur.

**Yetki:** Admin

**İstek:**
```json
{
  "name": "Doğu Lojistik Birimi",
  "address": "Sanayi Mah. Depo Sok. No:8 Erzurum",
  "stk": "STK-7865",
  "btk": "BTK-6674",
  "contactName": "Uzm. Cav. Esra Yilmaz",
  "contactRank": "Uzman Cavus",
  "contactRegistry": "EY3345",
  "contactIdentity": "19876543219",
  "contactPhone": "+90 532 998 11 44"
}
```

#### PUT /units/:id
Birim bilgilerini günceller.

**Yetki:** Admin

#### DELETE /units/:id
Birim kaydını siler.

**Yetki:** Admin

### Personel Yönetimi

#### GET /fuel-personnel
Tüm yakıt personelini listeler.

**Yetki:** Admin

**Yanıt (200):**
```json
{
  "personnel": [
    {
      "id": 1,
      "fullName": "Astsb. Cahit Demir",
      "rank": "Astsubay",
      "registryNumber": "CD5561",
      "identityNumber": "14523698741",
      "phone": "+90 532 223 45 67",
      "createdAt": "2024-01-01T10:00:00Z"
    }
  ]
}
```

#### POST /fuel-personnel
Yeni personel oluşturur.

**Yetki:** Admin

**İstek:**
```json
{
  "fullName": "Sv. Uzm. Er Ali Korkmaz",
  "rank": "Sozlesmeli Er",
  "registryNumber": "AK7812",
  "identityNumber": "32987456100",
  "phone": "+90 555 893 22 10"
}
```

#### PUT /fuel-personnel/:id
Personel bilgilerini günceller.

**Yetki:** Admin

#### DELETE /fuel-personnel/:id
Personel kaydını siler.

**Yetki:** Admin

## ⚡ Yakıt Sorumlusu API

### GET /fuel/resources
Yakıt fişi oluşturmak için gerekli kaynakları getirir.

**Yetki:** Yakıt Sorumlusu

**Yanıt (200):**
```json
{
  "forces": ["MSB", "K.K.K.", "Dz.K.K.", "Hv.K.K.", "SGK", "Gnkur. Bşk.", "Hrt.Gn.K."],
  "vehicles": [
    {
      "id": 1,
      "brand": "Ford",
      "model": "Transit",
      "year": 2021,
      "plate": "34 AYT 312"
    }
  ],
  "units": [
    {
      "id": 1,
      "name": "Merkez Birlik",
      "address": "Cumhuriyet Mah. İstasyon Cad. No:12/1 İstanbul"
    }
  ],
  "personnel": [
    {
      "id": 1,
      "fullName": "Astsb. Cahit Demir",
      "rank": "Astsubay",
      "registryNumber": "CD5561",
      "phone": "+90 532 223 45 67"
    }
  ],
  "inventoryManagers": [
    {
      "id": 3,
      "displayName": "Mal Sorumlusu 1"
    }
  ]
}
```

### GET /fuel-slips
Tüm yakıt fişlerini listeler.

**Yetki:** Yakıt Sorumlusu

**Yanıt (200):**
```json
{
  "slips": [
    {
      "id": 1,
      "slipNumber": 1,
      "createdAt": "2024-01-01T10:00:00Z",
      "slipDate": "2024-01-01",
      "force": "MSB",
      "unitId": 1,
      "unitName": "Merkez Birlik",
      "vehicleId": 1,
      "vehicleDescription": "Ford Transit",
      "plate": "34 AYT 312",
      "fuelAmountNumber": 50,
      "fuelAmountText": "Elli",
      "fuelType": "Benzin",
      "receiverId": 1,
      "receiverName": "Astsb. Cahit Demir",
      "receiverRank": "Astsubay",
      "receiverRegistry": "CD5561",
      "receiverPhone": "+90 532 223 45 67",
      "giverId": 2,
      "giverName": "Sv. Uzm. Er Ali Korkmaz",
      "giverRank": "Sozlesmeli Er",
      "giverRegistry": "AK7812",
      "giverPhone": "+90 555 893 22 10",
      "notes": "Normal ikmal",
      "inventoryManagerId": 3,
      "inventoryManagerName": "Mal Sorumlusu 1",
      "fuelManagerId": 2,
      "status": "pending",
      "rejectionReason": null
    }
  ]
}
```

### POST /fuel-slips
Yeni yakıt fişi oluşturur.

**Yetki:** Yakıt Sorumlusu

**İstek:**
```json
{
  "date": "2024-01-01",
  "force": "MSB",
  "unitId": 1,
  "vehicleId": 1,
  "fuelAmountNumber": 50,
  "fuelAmountText": "Elli",
  "fuelType": "Benzin",
  "receiverId": 1,
  "giverId": 2,
  "receiverPhone": "+90 532 223 45 67",
  "giverPhone": "+90 555 893 22 10",
  "notes": "Normal ikmal",
  "inventoryManagerId": 3
}
```

**Yanıt (201):**
```json
{
  "slip": {
    "id": 2,
    "slipNumber": 2,
    // ... diğer fiş bilgileri
  }
}
```

### GET /fuel-slips/:id/pdf
Yakıt fişini PDF formatında indirir.

**Yetki:** Yakıt Sorumlusu

**Yanıt (200)** - PDF dosyası
**Content-Type:** `application/pdf`
**Content-Disposition:** `inline; filename=akaryakit-senedi-0002.pdf`

## 📋 Mal Sorumlusu API

### GET /fuel-slips/assigned
Kullanıcıya atanan yakıt fişlerini listeler.

**Yetki:** Mal Sorumlusu

**Yanıt (200):**
```json
{
  "slips": [
    {
      "id": 1,
      "slipNumber": 1,
      "status": "pending",
      // ... diğer fiş bilgileri
    }
  ]
}
```

### PATCH /fuel-slips/:id/status
Yakıt fişini onaylar veya reddeder.

**Yetki:** Mal Sorumlusu

**İstek (Onay):**
```json
{
  "status": "approved"
}
```

**İstek (Red):**
```json
{
  "status": "rejected",
  "reason": "Araç bakımda olduğu için ikmal yapılamaz"
}
```

**Yanıt (200):**
```json
{
  "slip": {
    "id": 1,
    "status": "approved",
    "rejectionReason": null
  }
}
```

## 🔌 WebSocket Olayları

### Bağlantı
```javascript
const socket = io('http://localhost:5005', {
  auth: {
    token: '<session-token>'
  }
});
```

### Mal Sorumlusu Olayları

#### fuelSlip:new
Yeni yakıt fişi atandığında tetiklenir.

```javascript
socket.on('fuelSlip:new', (slip) => {
  console.log('Yeni fiş:', slip);
});
```

#### fuelSlip:status
Fiş durumu güncellendiğinde tetiklenir.

```javascript
socket.on('fuelSlip:status', (slip) => {
  console.log('Fiş durumu güncellendi:', slip.status);
});
```

### Yakıt Sorumlusu Olayları

#### fuelSlip:status
Fiş durumu güncellendiğinde tetiklenir.

```javascript
socket.on('fuelSlip:status', (slip) => {
  console.log('Fiş durumu:', slip.status, 'Sebep:', slip.rejectionReason);
});
```

## ⚠️ Hata Kodları

### HTTP Durum Kodları
- `200` - Başarılı
- `201` - Oluşturuldu
- `204` - İçerik Yok
- `400` - Geçersiz İstek
- `401` - Yetkisiz
- `403` - Yasak
- `404` - Bulunamadı
- `409` - Çakışma
- `500` - Sunucu Hatası

### Hata Mesajları
```json
{
  "message": "Kullanici adi ve sifre zorunlu.",
  "error": "Validation error"
}
```

### Yaygın Hata Senaryoları
- **Session expired**: Token geçersiz veya süresi dolmuş
- **Insufficient permissions**: İstek için yetki yok
- **Resource not found**: İstenen kaynak bulunamadı
- **Validation failed**: Gerekli alanlar eksik veya geçersiz
- **Database constraint**: Veritabanı kısıtlaması ihlali

## 📝 Örnek Kod

### JavaScript/Node.js
```javascript
const axios = require('axios');

class YTPClient {
  constructor(baseURL) {
    this.client = axios.create({
      baseURL,
      headers: {
        'Content-Type': 'application/json'
      }
    });
  }

  async login(username, password) {
    const response = await this.client.post('/auth/login', {
      username,
      password
    });

    this.token = response.data.token;
    this.client.defaults.headers['X-Session-Token'] = this.token;

    return response.data.user;
  }

  async createFuelSlip(slipData) {
    const response = await this.client.post('/fuel-slips', slipData);
    return response.data.slip;
  }

  async getFuelSlips() {
    const response = await this.client.get('/fuel-slips');
    return response.data.slips;
  }
}

// Kullanım
const client = new YTPClient('http://localhost:5005/api');
await client.login('yakitsorum', 'Yakit@123');
const slips = await client.getFuelSlips();
```

### curl Örnekleri
```bash
# Giriş
curl -X POST http://localhost:5005/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"Admin!123"}'

# Yeni araç ekleme
curl -X POST http://localhost:5005/api/vehicles \
  -H "Content-Type: application/json" \
  -H "X-Session-Token: YOUR_TOKEN" \
  -d '{"brand":"Ford","model":"Transit","year":2021,"plate":"34 AYT 312"}'

# Yakıt fişlerini listeleme
curl -X GET http://localhost:5005/api/fuel-slips \
  -H "X-Session-Token: YOUR_TOKEN"
```

---

**Not**: Bu API dokümantasyonu geliştirme sürecinde güncellenebilir. Değişiklikler için release notlarını kontrol edin.