wisecolt/ytp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Readme index'ler eklendi.

Browse Source
This commit is contained in:
szbk
2025-11-03 23:12:45 +03:00
parent 7edbab2689
commit 63abf6eaff
10 changed files with 3867 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

605
docs/KNOWLEDGE_BASE.md Normal file
View File

@@ -0,0 +1,605 @@
# YTP Bilgi Bankası
Yakıt Takip Sistemi kapsamlı bilgi bankası - hızlı referans, kılavuzlar ve sorun giderme rehberi.
## 📋 İçerik
- [Hızlı Başlangıç](#hızlı-başlangıç)
- [Sistem Mimarisi](#sistem-mimarisi)
- [Kullanıcı Rolleri ve Yetkileri](#kullanıcı-rolleri-ve-yetkileri)
- [İş Akışları](#iş-akışları)
- [Yaygın Sorunlar ve Çözümleri](#yaygın-sorunlar-ve-çözümleri)
- [Best Practices](#best-practices)
- [Kaynaklar ve Referanslar](#kaynaklar-ve-referanslar)
## 🚀 Hızlı Başlangıç
### Sistemi 5 Dakikada Çalıştırma
```bash
# 1. Projeyi klonlayın
git clone <repository-url>
cd ytp
# 2. Bağımlılıkları yükleyin
npm install && cd client && npm install && cd ..
# 3. Veritabanını başlatın
npm run prepare:db
# 4. Sistemi çalıştırın
npm run dev
# 5. Tarayıcıda açın
# Frontend: http://localhost:5173
# Backend API: http://localhost:5005/api
```
### Varsayılan Giriş Bilgileri
| Rol | Kullanıcı Adı | Şifre | Panel |
|-----|--------------|-------|-------|
| Admin | `admin` | `Admin!123` | [Admin Paneli](#admin-paneli) |
| Yakıt Sorumlusu | `yakitsorum` | `Yakit@123` | [Yakıt Sorumlusu Paneli](#yakıt-sorumlusu-paneli) |
| Mal Sorumlusu | `malsorum1` | `Mal@123` | [Mal Sorumlusu Paneli](#mal-sorumlusu-paneli) |
### İlk Yakıt Fişi Oluşturma
1. **Giriş Yap**: Yakıt sorumlusu ile giriş yapın
2. **Kaynak Kontrolü**: Araç, birlik ve personel kayıtlarını kontrol edin
3. **Fiş Oluştur**: "Yeni Fiş" butonuna tıklayın
4. **Form Doldur**: Tüm zorunlu alanları doldurun
5. **Onay Gönder**: Mal sorumlusuna gönder
6. **Bildirim Takibi**: Real-time bildirimleri izleyin
## 🏗️ Sistem Mimarisi
### Mimari Diyagram
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Frontend │ │ Backend │ │ Database │
│ (Svelte) │◄──►│ (Express) │◄──►│ (SQLite) │
│ │ │ │ │ │
│ - UI Components │ │ - REST API │ │ - users │
│ - State Mgmt │ │ - Socket.IO │ │ - vehicles │
│ - Routing │ │ - Auth/Authz │ │ - units │
│ - API Client │ │ - PDF Generation│ │ - fuel_personnel│
└─────────────────┘ └─────────────────┘ │ - fuel_slips │
└─────────────────┘
```
### Teknoloji Stack Karşılaştırması
| Katman | Teknoloji | Neden? | Alternatifler |
|--------|-----------|--------|---------------|
| Frontend | Svelte + Vite | Hızlı, küçük bundle, reaktif | React, Vue, Angular |
| Backend | Node.js + Express | Hızlı development, JavaScript ekosistemi | Python, PHP, Java |
| Database | SQLite3 | Hafif, kurulum gerektirmeyen, taşınabilir | PostgreSQL, MySQL |
| Real-time | Socket.IO | WebSocket wrapper, fallback mekanizmaları | Raw WebSocket, SSE |
| PDF | PDFKit | Node.js uyumlu, esnek | Puppeteer, jsPDF |
## 👥 Kullanıcı Rolleri ve Yetkileri
### Admin (Sistem Yöneticisi)
**Yetkiler:**
- ✅ Tüm kullanıcıları yönetme
- ✅ Mal sorumluları ekleme/güncelleme/silme
- ✅ Araç kayıtlarını yönetme
- ✅ Birlik bilgilerini yönetme
- ✅ Personel kayıtlarını yönetme
- ✅ Sistem ayarlarını yapılandırma
- ❌ Yakıt fişi oluşturma
- ❌ Fiş onaylama/reddetme
**Kullanım Alanları:**
- Sistem kurulum ve bakım
- Kullanıcı yönetimi
- Temel veri girişi
- Raporlama ve analiz
### Yakıt Sorumlusu
**Yetkiler:**
- ✅ Yakıt fişi oluşturma
- ✅ Fiş durumlarını takip etme
- ✅ PDF fiş indirme
- ✅ Kaynak bilgilerini görme
- ❌ Kullanıcı yönetimi
- ❌ Fiş onaylama
- ❌ Temel veri düzenleme
**Kullanım Alanları:**
- Günlük yakıt ikmal işlemleri
- Fiş oluşturma ve takip
- Raporlama
### Mal Sorumlusu
**Yetkiler:**
- ✅ Atanan fişleri görme
- ✅ Fiş onaylama/reddetme
- ✅ Onay/reddetme gerekçesi ekleme
- ✅ Atanan fişleri arşivleme
- ❌ Fiş oluşturma
- ❌ Kullanıcı yönetimi
- ❌ Temel veri düzenleme
**Kullanım Alanları:**
- Yakıt ikmal onay süreçleri
- Stok takibi
- Raporlama
## 🔄 İş Akışları
### 1. Kullanıcı Yönetimi Akışı (Admin)
```
Başlangıç
↓
Admin Girişi
↓
"Kullanıcı Yönetimi" → "Mal Sorumluları"
↓
"Ekle" butonu → Form doldur → Kaydet
↓
Kullanıcı oluşturuldu → Bilgilendirme
↓
Bitiş
```
### 2. Yakıt Fişi Oluşturma Akışı
```
Başlangıç
↓
Yakıt Sorumlusu Girişi
↓
"Yeni Fiş" butonu
↓
Form doldurma:
├─ Tarih seçimi
├─ Kuvvet seçimi
├─ Birlik seçimi
├─ Araç seçimi
├─ Yakıt bilgileri
├─ Personel seçimi
└─ Mal sorumlusu atama
↓
"Oluştur" butonu
↓
Validasyon → Veritabanı kayıt
↓
Mal sorumlusuna bildirim
↓
PDF fiş oluştur (opsiyonel)
↓
Bitiş
```
### 3. Fiş Onay Akışı
```
Başlangıç
↓
Mal Sorumlusu Girişi
↓
"Atanan Fişler" listesi
↓
Fiş seçimi → Detay görüntüle
↓
Karar verme:
├─ "Onayla" → Durum: approved
└─ "Reddet" → Gerekçe gir → Durum: rejected
↓
Yakıt sorumlusuna bildirim
↓
Bitiş
```
### 4. Real-time Bildirim Akışı
```
Olay Tetiklenir
↓
Server Event Oluştur
↓
Socket.IO Emit
↓
İlgili Client'a Gönder
↓
UI Güncellenir
↓
Kullanıcı Bilgilendirilir
```
## 🔧 Yaygın Sorunlar ve Çözümleri
### Giriş ve Oturum Sorunları
#### Sorun: "Kullanıcı adı veya şifre hatalı"
**Nedenler:**
- Yanlış kullanıcı adı/şifre
- Büyük/küçük harf duyarlılığı
- Boşluk karakterleri
**Çözümler:**
```bash
# Varsayılan kullanıcıları kontrol et
sqlite3 data/app.db "SELECT username, role FROM users;"
# Şifre sıfırlama (admin için)
sqlite3 data/app.db "UPDATE users SET password = 'Admin!123' WHERE username = 'admin';"
```
#### Sorun: "Oturum bulunamadı"
**Nedenler:**
- Token süresi dolmuş
- Browser storage temizlenmiş
- Sunucu yeniden başlatılmış
**Çözümler:**
```javascript
// Browser console'dan kontrol et
localStorage.getItem('sessionToken');
// Manuel temizleme
localStorage.removeItem('sessionToken');
location.reload();
```
### Veritabanı Sorunları
#### Sorun: "Veritabanı okunamadı"
**Nedenler:**
- Veritabanı dosyası yok
- İzin sorunları
- Dosya kilitli
**Çözümler:**
```bash
# Veritabanını yeniden oluştur
rm data/app.db
npm run prepare:db
# İzinleri kontrol et
ls -la data/app.db
chmod 664 data/app.db
```
#### Sorun: "Bu kullanici adi zaten mevcut"
**Nedenler:**
- Unique constraint ihlali
- Önceki kayıt silinmemiş
**Çözümler:**
```sql
-- Mevcut kullanıcıları listele
SELECT id, username, role FROM users;
-- Kullanıcıyı sil (ID'ye göre)
DELETE FROM users WHERE id = 3;
```
### API ve Bağlantı Sorunları
#### Sorun: "Network Error"
**Nedenler:**
- Backend çalışmıyor
- Port çakışması
- Firewall engeli
**Çözümler:**
```bash
# Port durumunu kontrol et
lsof -i :5005
# Backend'i yeniden başlat
npm run start:server
# Port değiştir
PORT=3000 npm run start:server
```
#### Sorun: "CORS hatası"
**Nedenler:**
- Origin mismatch
- CORS ayarları eksik
**Çözümler:**
```javascript
// server/index.js CORS ayarları
app.use(cors({
origin: ['http://localhost:5173', 'http://localhost:3000'],
credentials: true
}));
```
### Frontend Sorunları
#### Sorun: Component yüklenmiyor
**Nedenler:**
- JavaScript error
- Import hataları
- Build sorunları
**Çözümler:**
```bash
# Frontend'i yeniden build et
cd client
npm run build
# Development modunda kontrol et
npm run dev
```
#### Sorun: Socket.IO bağlantı kurulamıyor
**Nedenler:**
- Token geçersiz
- Server kapalı
- WebSocket engellendi
**Çözümler:**
```javascript
// Browser console'da test
const socket = io('http://localhost:5005');
socket.on('connect', () => console.log('Connected'));
```
## 📚 Best Practices
### Development Best Practices
#### 1. Code Organization
```javascript
// ✅ İyi pratik - Component based structure
src/
├── components/
│ ├── auth/
│ ├── admin/
│ └── shared/
├── lib/
├── api/
└── styles/
// ❌ Kötü pratik - Tüm dosyaları tek dizinde
src/
├── LoginView.svelte
├── AdminPanel.svelte
├── api.js
└── styles.css
```
#### 2. Error Handling
```javascript
// ✅ İyi pratik - Spesifik error handling
async function createFuelSlip(data) {
try {
const response = await api.post('/fuel-slips', data);
return response.slip;
} catch (error) {
if (error.status === 409) {
throw new Error('Bu fiş zaten mevcut');
} else if (error.status === 400) {
throw new Error('Form verileri geçersiz');
}
throw new Error('Fiş oluşturulamadı');
}
}
// ❌ Kötü pratik - Generic error handling
async function createFuelSlip(data) {
try {
return await api.post('/fuel-slips', data);
} catch (error) {
console.log(error); // Silent fail
}
}
```
#### 3. State Management
```javascript
// ✅ İyi pratik - Minimal reactivity
let search = '';
let items = [];
$: filteredItems = items.filter(item =>
item.name.toLowerCase().includes(search.toLowerCase())
);
// ❌ Kötü pratik - Unnecessary reactivity
$: searchLower = search.toLowerCase();
$: filteredItems = items.filter(item =>
item.name.toLowerCase().includes(searchLower)
);
```
### Security Best Practices
#### 1. Input Validation
```javascript
// ✅ İyi pratik - Server-side validation
app.post('/api/vehicles', (req, res) => {
const { brand, model, year, plate } = req.body;
// Server-side validation
if (!brand || !model || !year || !plate) {
return res.status(400).json({ message: 'All fields required' });
}
if (year < 1990 || year > new Date().getFullYear() + 1) {
return res.status(400).json({ message: 'Invalid year' });
}
// Process valid data
});
// ❌ Kötü pratik - Sadece client-side validation
// Frontend validation bypass edilebilir
```
#### 2. Session Management
```javascript
// ✅ İyi pratik - Secure session handling
function createSession(user) {
const token = crypto.randomBytes(32).toString('hex');
const session = {
id: user.id,
role: user.role,
createdAt: Date.now(),
expiresAt: Date.now() + (24 * 60 * 60 * 1000) // 24 hours
};
sessions.set(token, session);
return { token, session };
}
// ❌ Kötü pratik - Predictable tokens
function createSession(user) {
const token = `${user.id}-${Date.now()}`; // Predictable!
// ...
}
```
### Performance Best Practices
#### 1. Database Queries
```javascript
// ✅ İyi pratik - Efficient queries
async function getFuelSlipsByStatus(status) {
return db.all(`
SELECT fs.*, u.display_name as inventoryManagerName
FROM fuel_slips fs
LEFT JOIN users u ON u.id = fs.inventory_manager_id
WHERE fs.status = ?
ORDER BY fs.created_at DESC
`, [status]);
}
// ❌ Kötü pratik - N+1 query problem
async function getFuelSlipsByStatus(status) {
const slips = await db.all(`
SELECT * FROM fuel_slips WHERE status = ?
`, [status]);
// N+1 queries!
for (const slip of slips) {
const user = await db.get(`
SELECT display_name FROM users WHERE id = ?
`, [slip.inventory_manager_id]);
slip.inventoryManagerName = user.display_name;
}
return slips;
}
```
#### 2. Component Optimization
```javascript
// ✅ İyi pratik - Lazy loading
const AdminPanel = lazy(() => import('./components/AdminPanel.svelte'));
// Usage
{#if user.role === 'admin'}
<Suspense fallback={<div>Loading...</div>}>
<AdminPanel {token} />
</Suspense>
{/if}
// ❌ Kötü pratik - Her zaman tüm component'leri yüklemek
import AdminPanel from './components/AdminPanel.svelte';
import FuelManagerPanel from './components/FuelManagerPanel.svelte';
// ... tüm component'ler import edildi
```
## 🔗 Kaynaklar ve Referanslar
### Dokümantasyon Linkleri
- [README.md](../README.md) - Proje genel bakış
- [API.md](API.md) - API dokümantasyonu
- [DATABASE.md](DATABASE.md) - Veritabanı şeması
- [STRUCTURE.md](STRUCTURE.md) - Proje yapısı
- [DEPLOYMENT.md](DEPLOYMENT.md) - Dağıtım kılavuzu
- [FRONTEND.md](FRONTEND.md) - Frontend mimarisi
### External Resources
#### Teknoloji Dokümantasyonları
- [Svelte Documentation](https://svelte.dev/docs)
- [Express.js Guide](https://expressjs.com/en/guide/)
- [Socket.IO Documentation](https://socket.io/docs/)
- [SQLite Documentation](https://www.sqlite.org/docs.html)
- [Vite Documentation](https://vitejs.dev/guide/)
#### Development Tools
- [VS Code](https://code.visualstudio.com/) + [Svelte Extension](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode)
- [SQLite Browser](https://sqlitebrowser.org/) - Veritabanı yönetimi
- [Postman](https://www.postman.com/) - API testing
- [Git](https://git-scm.com/) - Versiyon kontrolü
#### Learning Resources
- [MDN Web Docs](https://developer.mozilla.org/) - Web teknolojileri
- [JavaScript Info](https://javascript.info/) - JavaScript öğrenme
- [CSS Tricks](https://css-tricks.com/) - CSS teknikleri
- [Node.js Best Practices](https://github.com/goldbergyoni/nodebestpractices) - Node.js pratikleri
### Komut Referansı
#### Geliştirme Komutları
```bash
npm run dev # Geliştirme sunucusu
npm run start:server # Sadece backend
cd client && npm run dev # Sadece frontend
npm run prepare:db # Veritabanı başlangıç
```
#### Production Komutları
```bash
npm run build # Frontend build
npm start # Production sunucusu
pm2 start ecosystem.config.js # PM2 ile başlat
docker-compose up -d # Docker ile başlat
```
#### Veritabanı Komutları
```bash
sqlite3 data/app.db # Veritabanına bağlan
sqlite3 data/app.db ".tables" # Tabloları listele
sqlite3 data/app.db ".schema" # Şemayı göster
sqlite3 data/app.db ".backup backup.db" # Yedek al
```
### Hızlı Referans Kartları
#### API Endpoint'leri
```
Authentication:
POST /api/auth/login
POST /api/auth/logout
GET /api/session
Admin Operations:
GET/POST/PUT/DELETE /api/inventory-managers
GET/POST/PUT/DELETE /api/vehicles
GET/POST/PUT/DELETE /api/units
GET/POST/PUT/DELETE /api/fuel-personnel
Fuel Operations:
GET /api/fuel/resources
GET /api/fuel-slips
POST /api/fuel-slips
GET /api/fuel-slips/:id/pdf
PATCH /api/fuel-slips/:id/status
```
#### Varsayılan Veriler
```
Users:
- admin/Admin!123 (admin)
- yakitsorum/Yakit@123 (fuel_manager)
- malsorum1/Mal@123 (inventory_manager)
Vehicles:
- Ford Transit 2021 (34 AYT 312)
- Isuzu NPR 2019 (34 FZT 908)
Forces:
- MSB, K.K.K., Dz.K.K., Hv.K.K., SGK, Gnkur. Bşk., Hrt.Gn.K.
```
---
**Not**: Bu bilgi bankesi sürekli güncellenmektedir. Yeni sorunlar ve çözümler eklenecektir.