Readme index'ler eklendi.
This commit is contained in:
659
docs/API.md
Normal file
659
docs/API.md
Normal file
@@ -0,0 +1,659 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user