Porje dökümanları oluşturuldu
This commit is contained in:
559
docs/PROJE_DOKUMANTASYONU.md
Normal file
559
docs/PROJE_DOKUMANTASYONU.md
Normal file
@@ -0,0 +1,559 @@
|
||||
# Wisecolt-CI Proje Dökümantasyonu
|
||||
|
||||
## 📋 İçindekiler
|
||||
- [Proje Genel Bakış](#-proje-genel-bakış)
|
||||
- [Backend Dökümantasyonu](#-backend-dökümantasyonu)
|
||||
- [Frontend Dökümantasyonu](#-frontend-dökümantasyonu)
|
||||
- [API Referansı](#-api-referansı)
|
||||
- [Kurulum](#-kurulum)
|
||||
- [Kullanım](#-kullanım)
|
||||
- [Geliştirme](#-geliştirme)
|
||||
|
||||
## 🎯 Proje Genel Bakış
|
||||
|
||||
Wisecolt-CI, modern web teknolojileriyle geliştirilmiş tam teşekküllü bir CI/CD (Sürekli Entegrasyon/Sürekli Dağıtım) platformudur. Proje, repository otomasyonu ve test süreçlerini yönetmek için tasarlanmıştır.
|
||||
|
||||
### ✨ Temel Özellikler
|
||||
- **🔐 Kimlik Doğrulama**: JWT tabanlı güvenli kimlik yönetimi
|
||||
- **📊 Job Yönetimi**: Repository'lar için otomatik test süreçleri
|
||||
- **⚡ Gerçek Zamanlı**: Socket.io ile canlı durum güncellemeleri
|
||||
- **🎨 Modern UI**: React + shadcn/ui ile responsive arayüz
|
||||
- **🌙 Tema Desteği**: Dark/Light moda geçiş imkanı
|
||||
- **🐳 Konteynerizasyon**: Docker ile tam izole geliştirme ortamı
|
||||
|
||||
### 🛠 Teknoloji Yığını
|
||||
|
||||
#### Backend
|
||||
- **Node.js** + **TypeScript** - Güçlü sunucu tarafı geliştirme
|
||||
- **Express.js** - Minimal ve esnek web framework'ü
|
||||
- **MongoDB** - NoSQL veritabanı
|
||||
- **Socket.io** - Gerçek zamanlı çift yönlü iletişim
|
||||
- **JWT** - Güvenli kimlik doğrulama
|
||||
- **Mongoose** - MongoDB modelleme ve validasyon
|
||||
|
||||
#### Frontend
|
||||
- **React 18** - Modern bileşen tabanlı UI kütüphanesi
|
||||
- **TypeScript** - Tip güvenli geliştirme
|
||||
- **Vite** - Hızlı build tool ve geliştirme sunucusu
|
||||
- **Tailwind CSS** - Utility-first CSS framework'ü
|
||||
- **shadcn/ui** - Modern React UI bileşen kütüphanesi
|
||||
- **React Router** - Client tarafı rotalama
|
||||
- **Axios** - HTTP istemci kütüphanesi
|
||||
|
||||
#### DevOps
|
||||
- **Docker** + **Docker Compose** - Konteyner orkestrasyon
|
||||
- **Hot Reload** - Geliştirme anında canlı güncellemeler
|
||||
|
||||
## 📊 Backend Dökümantasyonu
|
||||
|
||||
### 🏗 Mimari
|
||||
|
||||
Backend, RESTful API prensiplerine göre tasarlanmış modüler bir yapıya sahiptir.
|
||||
|
||||
#### Ana Bileşenler
|
||||
1. **Express Sunucusu** (`src/index.ts`)
|
||||
2. **Router'lar** (`src/routes/`)
|
||||
3. **Middleware** (`src/middleware/`)
|
||||
4. **Servisler** (`src/services/`)
|
||||
5. **Modeller** (`src/models/`)
|
||||
6. **Konfigürasyon** (`src/config/`)
|
||||
|
||||
### 🔐 Authentication Sistemi
|
||||
|
||||
#### Endpoint'ler
|
||||
- `POST /auth/login` - Kullanıcı girişi
|
||||
- `GET /auth/me` - Token doğrulama ve kullanıcı bilgileri
|
||||
|
||||
#### Güvenlik Özellikleri
|
||||
- JWT tabanlı kimlik doğrulama
|
||||
- Bearer token authentication
|
||||
- CORS yapılandırması
|
||||
- .env tabanlı hassas bilgi yönetimi
|
||||
|
||||
#### Kullanım
|
||||
```typescript
|
||||
// Giriş işlemi
|
||||
const response = await fetch('/auth/login', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({ username, password })
|
||||
});
|
||||
|
||||
// Token ile korumalı istek
|
||||
const response = await fetch('/protected-endpoint', {
|
||||
headers: {
|
||||
'Authorization': `Bearer ${token}`,
|
||||
'Content-Type': 'application/json'
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### 📋 Job Yönetim Sistemi
|
||||
|
||||
#### Model Yapısı
|
||||
```typescript
|
||||
interface JobDocument {
|
||||
name: string; // Job adı
|
||||
repoUrl: string; // Repository URL'si
|
||||
testCommand: string; // Çalıştırılacak test komutu
|
||||
checkValue: number; // Kontrol değeri (dakika/saat/gün)
|
||||
checkUnit: TimeUnit; // Kontrol birimi
|
||||
status: JobStatus; // Job durumu
|
||||
lastRunAt?: Date; // Son çalışma zamanı
|
||||
lastDurationMs?: number; // Son çalışma süresi (ms)
|
||||
lastMessage?: string; // Son mesaj
|
||||
}
|
||||
```
|
||||
|
||||
#### Endpoint'ler
|
||||
- `GET /jobs` - Tüm job'ları listele
|
||||
- `GET /jobs/:id` - Job detaylarını getir
|
||||
- `POST /jobs` - Yeni job oluştur
|
||||
- `PUT /jobs/:id` - Job güncelle
|
||||
- `DELETE /jobs/:id` - Job sil
|
||||
- `POST /jobs/:id/run` - Job'ı manuel çalıştır
|
||||
|
||||
#### Job Süreç Yönetimi
|
||||
- **Otomatik Çalıştırma**: Belirlenen aralıklarla otomatik çalışma
|
||||
- **Git Operasyonları**: Clone/pull işlemleri
|
||||
- **NPM Kurulum**: Bağımlılıkların otomatik kurulumu
|
||||
- **Test Çalıştırma**: Belirlenen komutların çalıştırılması
|
||||
- **Sonuç Kaydı**: Test sonuçlarının veritabanına kaydedilmesi
|
||||
|
||||
### ⚡ Socket.io Real-time İletişim
|
||||
|
||||
#### Olaylar
|
||||
- `connection` - Yeni bağlantı kurulduğunda
|
||||
- `hello` - Bağlantı kurulduğunda hoş geldik mesajı
|
||||
- `ping/pong` - Bağlantı kontrolü
|
||||
- `counter:update` - Sayaç güncellemesi
|
||||
- `counter:start/stop` - Sayaç başlatma/durdurma
|
||||
- `job:subscribe` - Job durum takibi
|
||||
- `job:status` - Job durum güncellemesi
|
||||
- `job:log` - Job log akışı
|
||||
|
||||
#### Kullanım Örneği
|
||||
```typescript
|
||||
// Client tarafı
|
||||
socket.on('job:status', (data) => {
|
||||
console.log('Job durumu güncellendi:', data);
|
||||
});
|
||||
|
||||
// Server tarafı
|
||||
io.to(`job:${jobId}`).emit('job:status', {
|
||||
jobId,
|
||||
status: 'running',
|
||||
lastMessage: 'Test çalıştırılıyor...'
|
||||
});
|
||||
```
|
||||
|
||||
### 🔧 Konfigürasyon Yönetimi
|
||||
|
||||
#### Environment Değişkenleri
|
||||
```bash
|
||||
PORT=4000 # Backend sunucu portu
|
||||
MONGO_URI=mongodb://mongo:27017/wisecoltci # MongoDB bağlantı adresi
|
||||
ADMIN_USERNAME=admin # Admin kullanıcı adı
|
||||
ADMIN_PASSWORD=supersecret # Admin şifresi
|
||||
JWT_SECRET=your-secret-key # JWT imzalama anahtarı
|
||||
CLIENT_ORIGIN=http://localhost:5173 # Frontend adresi (CORS için)
|
||||
```
|
||||
|
||||
## 🎨 Frontend Dökümantasyonu
|
||||
|
||||
### 🏗 Mimari
|
||||
|
||||
Frontend, modern React prensiplerine göre tasarlanmış bileşen tabanlı bir yapıya sahiptir.
|
||||
|
||||
#### Ana Bileşenler
|
||||
1. **App Component** - Ana rotalama ve yapılandırma
|
||||
2. **Pages** - Sayfa bileşenleri (HomePage, JobsPage, vb.)
|
||||
3. **Components** - Yeniden kullanılabilir UI bileşenleri
|
||||
4. **Providers** - React Context Provider'lar
|
||||
5. **API Layer** - Backend ile iletişim katmanı
|
||||
|
||||
### 🔐 Authentication Provider
|
||||
|
||||
#### AuthProvider Özellikleri
|
||||
- Kullanıcı durum yönetimi
|
||||
- Token saklama (localStorage)
|
||||
- Otomatik kimlik doğrulama
|
||||
- Login/logout işlemleri
|
||||
|
||||
#### Kullanım
|
||||
```typescript
|
||||
const { user, token, login, logout, loading } = useAuth();
|
||||
|
||||
// Giriş yapma
|
||||
await login('admin', 'password');
|
||||
|
||||
// Çıkış yapma
|
||||
logout();
|
||||
|
||||
// Korumalı bileşen
|
||||
if (!user) {
|
||||
return <Navigate to="/login" />;
|
||||
}
|
||||
```
|
||||
|
||||
### 📱 Sayfa Bileşenleri
|
||||
|
||||
#### HomePage
|
||||
- Proje genel bakış ve istatistikler
|
||||
- Hızlı erişim linkleri
|
||||
|
||||
#### JobsPage
|
||||
- Job listesi
|
||||
- Job oluşturma/düzenleme/silme işlemleri
|
||||
- Real-time durum güncellemeleri
|
||||
|
||||
#### JobDetailPage
|
||||
- Job detayları
|
||||
- Manuel çalıştırma
|
||||
- Log akışı izleme
|
||||
|
||||
### 🎨 UI Bileşen Kütüphanesi (shadcn/ui)
|
||||
|
||||
#### Temel Bileşenler
|
||||
- **Button** - Özelleştirilebilir düğmeler
|
||||
- **Input** - Form giriş alanları
|
||||
- **Select** - Seçim kutuları
|
||||
- **Card** - Kart bileşenleri
|
||||
- **Label** - Etiket bileşenleri
|
||||
- **Switch** - Toggle switch'ler
|
||||
- **Toaster** - Bildirim sistemi
|
||||
|
||||
#### Stil Sistemi
|
||||
- **Tailwind CSS** - Utility-first stil yaklaşımı
|
||||
- **Responsive Design** - Mobil uyumlu tasarım
|
||||
- **Tema Desteği** - Dark/Light moda geçiş
|
||||
|
||||
### 📱 Responsive Tasarım
|
||||
|
||||
#### Breakpoint'ler
|
||||
- `sm:` - 640px ve üzeri
|
||||
- `md:` - 768px ve üzeri
|
||||
- `lg:` - 1024px ve üzeri
|
||||
- `xl:` - 1280px ve üzeri
|
||||
|
||||
#### Örnek Kullanım
|
||||
```typescript
|
||||
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
|
||||
{/* Responsive grid layout */}
|
||||
</div>
|
||||
```
|
||||
|
||||
## 🔌 API Referansı
|
||||
|
||||
### Authentication API
|
||||
|
||||
#### POST /auth/login
|
||||
Kullanıcı girişi için endpoint.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"username": "admin",
|
||||
"password": "supersecret"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"username": "admin"
|
||||
}
|
||||
```
|
||||
|
||||
#### GET /auth/me
|
||||
Token doğrulama ve kullanıcı bilgileri.
|
||||
|
||||
**Headers:**
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"username": "admin"
|
||||
}
|
||||
```
|
||||
|
||||
### Jobs API
|
||||
|
||||
#### GET /jobs
|
||||
Tüm job'ları listeler.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"_id": "64a1b2c3d4e5f6789012345",
|
||||
"name": "Frontend Tests",
|
||||
"repoUrl": "https://github.com/user/frontend-repo",
|
||||
"testCommand": "npm test",
|
||||
"checkValue": 5,
|
||||
"checkUnit": "dakika",
|
||||
"status": "idle",
|
||||
"lastRunAt": "2023-07-01T10:30:00.000Z",
|
||||
"lastDurationMs": 45000,
|
||||
"lastMessage": "Başarılı",
|
||||
"createdAt": "2023-07-01T08:00:00.000Z",
|
||||
"updatedAt": "2023-07-01T10:30:00.000Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### POST /jobs
|
||||
Yeni job oluşturur.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"name": "Backend Tests",
|
||||
"repoUrl": "https://github.com/user/backend-repo",
|
||||
"testCommand": "npm run test",
|
||||
"checkValue": 10,
|
||||
"checkUnit": "dakika"
|
||||
}
|
||||
```
|
||||
|
||||
#### GET /jobs/:id
|
||||
Belirtilen job'ın detaylarını getirir.
|
||||
|
||||
#### PUT /jobs/:id
|
||||
Mevcut job'ı günceller.
|
||||
|
||||
**Request Body:** POST ile aynı formatta
|
||||
|
||||
#### DELETE /jobs/:id
|
||||
Job'ı siler.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
#### POST /jobs/:id/run
|
||||
Job'ı manuel olarak çalıştırır.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"queued": true
|
||||
}
|
||||
```
|
||||
|
||||
### WebSocket Olayları
|
||||
|
||||
#### client → server
|
||||
- `ping` - Bağlantı kontrolü
|
||||
- `counter:start` - Sayaç başlatma
|
||||
- `counter:stop` - Sayaç durdurma
|
||||
- `counter:status` - Sayaç durumu sorgula
|
||||
- `job:subscribe` - Job durum takibi
|
||||
- `job:unsubscribe` - Job durum takibi bırakma
|
||||
|
||||
#### server → client
|
||||
- `hello` - Bağlantı kurulduğunda
|
||||
- `pong` - Ping yanıtı
|
||||
- `counter:update` - Sayaç değeri güncellemesi
|
||||
- `counter:stopped` - Sayaç durduğunda
|
||||
- `job:status` - Job durumu güncellemesi
|
||||
- `job:log` - Job log mesajı
|
||||
|
||||
## 🚀 Kurulum
|
||||
|
||||
### Gereksinimler
|
||||
- Docker ve Docker Compose
|
||||
- Git
|
||||
|
||||
### Adım Adım Kurulum
|
||||
|
||||
1. **Repo'yu klonla:**
|
||||
```bash
|
||||
git clone https://github.com/your-repo/wisecolt-ci.git
|
||||
cd wisecolt-ci
|
||||
```
|
||||
|
||||
2. **Ortam dosyalarını yapılandır:**
|
||||
```bash
|
||||
cp backend/.env.example backend/.env
|
||||
cp frontend/.env.example frontend/.env
|
||||
```
|
||||
|
||||
3. **Admin bilgilerini gir:**
|
||||
```bash
|
||||
# backend/.env
|
||||
ADMIN_USERNAME=your-admin-username
|
||||
ADMIN_PASSWORD=your-secure-password
|
||||
JWT_SECRET=your-jwt-secret-key
|
||||
CLIENT_ORIGIN=http://localhost:5173
|
||||
|
||||
# frontend/.env
|
||||
VITE_API_URL=http://localhost:4000
|
||||
```
|
||||
|
||||
4. **Servisleri başlat:**
|
||||
```bash
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
5. **Uygulamaya eriş:**
|
||||
- Frontend: http://localhost:5173
|
||||
- Backend API: http://localhost:4000
|
||||
- MongoDB: mongodb://localhost:27017
|
||||
|
||||
## 💻 Kullanım
|
||||
|
||||
### Giriş İşlemi
|
||||
1. Tarayıcıda http://localhost:5173 adresine gidin
|
||||
2. Varsayılan giriş bilgileri:
|
||||
- Kullanıcı adı: `admin`
|
||||
- Şifre: `supersecret`
|
||||
3. Giriş yap butonuna tıklayın
|
||||
|
||||
### Job Oluşturma
|
||||
1. Sol menüden "Jobs" sayfasına gidin
|
||||
2. "Yeni Job" butonuna tıklayın
|
||||
3. Job bilgilerini girin:
|
||||
- **Job Adı**: Test için anlaşılır bir ad
|
||||
- **Repository URL**: GitHub repository adresi
|
||||
- **Test Komutu**: Çalıştırılacak komut (örn: `npm test`)
|
||||
- **Kontrol Değeri**: Kaç dakikada/saat/günde bir çalışacağı
|
||||
- **Kontrol Birimi**: Zaman birimi seçimi
|
||||
4. Kaydet butonuna tıklayın
|
||||
|
||||
### Job İzleme
|
||||
1. Jobs sayfasından oluşturduğunuz job'a tıklayın
|
||||
2. Job detay sayfasında:
|
||||
- **Durum**: Job'un mevcut durumu (idle/running/success/failed)
|
||||
- **Sonuçlar**: Son çalıştırma sonuçları ve süreleri
|
||||
- **Loglar**: Gerçek zamanlı log akışı
|
||||
- **Manuel Çalıştırma**: Job'u anında çalıştırma
|
||||
|
||||
## 🛠 Geliştirme
|
||||
|
||||
### Backend Geliştirme
|
||||
|
||||
#### Yeni Route Ekleme
|
||||
```typescript
|
||||
// src/routes/yeniRoute.ts
|
||||
import { Router } from "express";
|
||||
import { authMiddleware } from "../middleware/authMiddleware.js";
|
||||
|
||||
const router = Router();
|
||||
router.use(authMiddleware);
|
||||
|
||||
router.get("/", (req, res) => {
|
||||
res.json({ message: "Yeni endpoint çalışıyor" });
|
||||
});
|
||||
|
||||
export default router;
|
||||
```
|
||||
|
||||
#### Ana Dosyada Route Ekleme
|
||||
```typescript
|
||||
// src/index.ts
|
||||
import yeniRoute from "./routes/yeniRoute.js";
|
||||
|
||||
app.use("/yeni", yeniRoute);
|
||||
```
|
||||
|
||||
### Frontend Geliştirme
|
||||
|
||||
#### Yeni Sayfa Ekleme
|
||||
```typescript
|
||||
// src/pages/YeniSayfa.tsx
|
||||
import React from "react";
|
||||
|
||||
export const YeniSayfa = () => {
|
||||
return (
|
||||
<div>
|
||||
<h1>Yeni Sayfa</h1>
|
||||
{/* Sayfa içeriği */}
|
||||
</div>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
#### Rotalama Ekleme
|
||||
```typescript
|
||||
// src/App.tsx
|
||||
import { YeniSayfa } from "./pages/YeniSayfa";
|
||||
|
||||
<Route path="/yeni" element={<YeniSayfa />} />
|
||||
```
|
||||
|
||||
#### API İsteği Ekleme
|
||||
```typescript
|
||||
// src/api/client.ts
|
||||
export async function yeniEndpoint() {
|
||||
const { data } = await apiClient.get("/yeni");
|
||||
return data;
|
||||
}
|
||||
```
|
||||
|
||||
### 🐳 Docker Yapılandırması
|
||||
|
||||
#### Backend Dockerfile
|
||||
```dockerfile
|
||||
FROM node:18-alpine
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm ci --only=production
|
||||
COPY . .
|
||||
EXPOSE 4000
|
||||
CMD ["npm", "run", "start"]
|
||||
```
|
||||
|
||||
#### Frontend Dockerfile
|
||||
```dockerfile
|
||||
FROM node:18-alpine as build
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm ci
|
||||
COPY . .
|
||||
RUN npm run build
|
||||
|
||||
FROM nginx:alpine
|
||||
COPY --from=build /app/dist /usr/share/nginx/html
|
||||
COPY nginx.conf /etc/nginx/nginx.conf
|
||||
EXPOSE 80
|
||||
CMD ["nginx", "-g", "daemon off;"]
|
||||
```
|
||||
|
||||
### 🔄 Otomatik Test Süreci
|
||||
|
||||
JobService, belirlenen aralıklarla otomatik test çalıştırır:
|
||||
|
||||
1. **Repository Clone**: İlk çalıştırmada repo klonlanır
|
||||
2. **Bağımlılık Kurulum**: `npm install` çalıştırılır
|
||||
3. **Test Çalıştırma**: Belirlenen komut çalıştırılır
|
||||
4. **Sonuç Kayıt**: Sonuçlar veritabanına kaydedilir
|
||||
5. **Real-time Güncelleme**: Socket.io ile client bilgilendirilir
|
||||
|
||||
### 📝 Notlar
|
||||
|
||||
#### Güvenlik
|
||||
- JWT token'ları güvenli saklayın
|
||||
- Environment değişkenlerini .env dosyasında tutun
|
||||
- Production ortamında varsayılan şifreleri değiştirin
|
||||
|
||||
#### Performans
|
||||
- MongoDB index'leri kullanın
|
||||
- Büyük repository'ler için caching stratejileri uygulayın
|
||||
- Frontend build optimizasyonu yapın
|
||||
|
||||
#### İzleme
|
||||
- MongoDB log'larını izleyin
|
||||
- Docker container log'larını kontrol edin
|
||||
- Application metriklerini toplayın
|
||||
|
||||
---
|
||||
|
||||
*Bu dökümantasyon Wisecolt-CI projesinin tüm özelliklerini ve kullanımını kapsamaktadır. Geliştirme sürecinde güncel tutulmalıdır.*
|
||||
Reference in New Issue
Block a user