Spaces:
Running
Running
Güncellenmiş flare-ui-2.0.md
# Flare Administration UI - Tasarım Dokümanı
## 📌 Amaç
Flare Administration UI (Flare Admin), kullanıcıların Flare platformunda proje tanımlayıp yönetebileceği bir web arayüzüdür. Angular ile geliştirilir, backend olarak Python ile geliştirilmiş olan Flare backend'i kullanır.
Flare Admin ekranlarında; proje tanımlama, mevcut projeyi düzenleme, projeye versiyon çıkarma, versiyonu publish etme, projeyi enable-disable etme, proje tanımını silme gibi işlemler yapılabilir.
Document database olarak Flare'in service_config.jsonc dosyasını kullanır. Tüm tanım, düzenleme, silme ve listeleme işlemlerini bu dosya üzerinde yapar.
Flare Admin, Flare backend servisi üzerinden Spark ile entegre çalışır.
## Genel Kurallar
Flare Admin, login ekranıyla başlar. Kullanıcı login olduktan sonra tanım ekranları görüntülenir.
Tanım ekranları, tab window'lar şeklinde gruplandırılmıştır. Her tab'da birbiriyle alakalı işlemler yapılır.
Tüm hatalı işlemler, işlemin yapıldığı ekranın alt kısmında kırmızı font ile uyarı şeklinde görüntülenir ve uyarı 5 sn sonra kaybolur.
Boolean alanlar ekranda (hem input olarak, hem de tablo üzerinde) checkbox olarak görüntülenir.
Silme işlemleri öncesinde, silinecek nesnenin diğer nesneler altında kullanımda olup olmadığı kontrol edilir. Eğer kullanımdaysa, silinmesine izin verilmez ve hangi nesneler tarafından kullanıldığını içeren bir mesaj ve hata kodu ile döndürülür. Kullanımda olmayan nesneyi silme öncesinde açılacak bir dialog'da kullanıcıdan onay alınır. Onayın ardından silme işlemi yapılır.
Nesnenin **deleted** alanı varsa silme işlemi fiziksel olarak yapılmaz, deleted=true olarak değiştirilir.
Ortam çok kullanıcılı olduğundan kayıt düzenleme işlemlerinde race condition kontrolü yapılır. Bunun için service_config.jsonc içinde config, project, version ve api nesnelerine **last_update_date** alanı eklenir.
Kullanıcı, düzenlemek için nesneyi ekrana yüklediğinde nesne içindeki bu değeri de yükler. Save butonuna bastığında backend'e bu değeri de gönderir ve backend kayıt öncesi bu değerin service_config.jsonc'deki ilgili nesnedeki değerle aynı olup olmadığını kontrol eder, aynı ise kaydı yapar ve kaydederken bu değeri o andaki tarih-saat-dakika-saniye-milisaniye değeri ile günceller.
Eğer bir başka kullanıcı aynı kaydı düzenliyorsa ve ilk kullanıcıdan sonra save'e bastıysa dosyadaki bu değer değişmiş olacağından backend kayda izin vermez ve "Kayıt başka kullanıcı tarafından düzenlendi. Lütfen tekrar yükleyin." tarzı bir uyarı ile birlikte bir hata kodu döndürür.
Bir diğer durum da, kullanıcı tarafından düzenlenen kaydın, bu kullanıcı kaydetmeden önce başka bir kullanıcı tarafından silinmiş olması durumudur. Backend kayıt öncesi dosyada bu nesneyi bulamazsa "Kayıt başka kullanıcı tarafından silindi." gibi bir uyarı ve bir hata kodu döndürür, kayda izin vermez.
## Auto-save ve Undo/Redo Mekanizması
- Published olmayan version'lar üzerinde çalışırken her 30 saniyede bir otomatik draft kayıt yapılır
- Son 10 işlem için undo/redo desteği (Ctrl+Z / Ctrl+Y)
- Draft kayıtlar drafts/ klasöründe tutulur ve UI açıldığında "Recover unsaved changes?" dialog'u gösterilir
## Klavye Kısayolları
- Ctrl+S: Save
- Ctrl+N: New (context'e göre project/version/intent)
- Ctrl+F: Search/Filter
- Ctrl+D: Duplicate
- Esc: Cancel/Close dialog
## Flare Backend Düzenlemeleri
Flare backend'de Flare Admin UI işleyişi için bazı eklemeler yapılması gerekiyor.
### Eklenecek endpoint'ler:
#### Temel CRUD Endpoint'leri
- POST /api/login - Kullanıcı girişi ve token üretimi
- GET /api/environment - Environment bilgileri alma
- PUT /api/environment - Environment bilgilerini kaydetme
- GET /api/projects - Proje listeleme (pagination, filter, sort destekli)
- POST /api/projects - Yeni proje oluşturma: Yeni proje oluşturulduğunda backend, version_id_counter alanını **1**'e ayarlar ve otomatik **Version 1** kaydını ekler. Frontend ekstra çağrı yapmaz.
- PUT /api/projects/{id} - Mevcut projeyi düzenleme
- DELETE /api/projects/{id} - Mevcut projeyi silme
- PATCH /api/projects/{id}/toggle - Proje enable/disable
- POST /api/projects/{id}/versions - Proje versiyonu oluşturma
- DELETE /api/projects/{id}/versions/{version_id} - Versiyon silme
- PUT /api/projects/{id}/versions/{version_id} - Versiyon düzenleme
- POST /api/projects/{id}/versions/{version_id}/publish - Versiyon yayınlama
- GET /api/apis - API listeleme
- POST /api/apis - Yeni API ekleme
- PUT /api/apis/{name} - Mevcut API'yi düzenleme
- DELETE /api/apis/{name} - Mevcut API'yi silme
#### Spark Integration Endpoint'leri (Yeni)
- POST /api/spark/startup - Projeyi Spark'a yükle
- GET /api/spark/projects - Spark proje listesi
- POST /api/spark/project/enable - Projeyi aktifleştir
- POST /api/spark/project/disable - Projeyi devre dışı bırak
- DELETE /api/spark/project/{name} - Projeyi Spark'tan sil
#### Chat Endpoint'leri (Yeni)
- GET /api/projects/names - Chat için enabled proje listesi
- POST /api/start_session - Chat session başlat
- POST /api/chat - Mesaj gönder/al (Header: X-Session-ID)
#### Ek Yardımcı Endpoint'ler
- POST /api/validate/regex - Regex pattern validasyonu
- POST /api/apis/test - API endpoint test etme
- GET /api/projects/{id}/versions/diff - Version karşılaştırma
- POST /api/projects/{id}/intents/bulk-delete - Toplu intent silme
- GET /api/activity-log - Aktivite logları
- POST /api/projects/import - Proje import
- GET /api/projects/{id}/export - Proje export
- POST /api/test/run-all - Tüm testleri çalıştır
- GET /api/test/status - Test durumu sorgula
### Service_config.jsonc düzenlemeleri:
```jsonc
{
"config": {
// Mevcut alanlar...
"internal_prompt": "⚠️ **NEVER output \"#DETECTED_INTENT:\"...", // Yeni
"project_id_counter": 1, // Yeni
"last_update_date": "2025-06-08T12:00:00.000Z", // Yeni
"last_update_user": "admin" // Yeni
},
"projects": [{
// Mevcut alanlar...
"icon": "folder", // Yeni
"description": "", // Yeni
"default_language": "tr", // Yeni
"supported_languages": ["tr"], // Yeni
"timezone": "Europe/Istanbul", // Yeni
"region": "tr-TR", // Yeni
"version_id_counter": 1, // Yeni
"last_update_date": "2025-06-08T12:00:00.000Z", // Yeni
"last_update_user": "admin", // Yeni
"deleted": false, // Yeni
"created_date": "2025-06-08T12:00:00.000Z", // Yeni
"created_by": "admin", // Yeni
"versions": [{
// Mevcut alanlar...
"last_update_date": "2025-06-08T12:00:00.000Z", // Yeni
"last_update_user": "admin", // Yeni
"deleted": false, // Yeni
"created_date": "2025-06-08T12:00:00.000Z", // Yeni
"created_by": "admin", // Yeni
"publish_date": null, // Yeni
"published_by": null // Yeni
}]
}],
"apis": [{
// Mevcut alanlar...
"response_mappings": [ // Yeni
{
"variable_name": "booking_id",
"type": "str",
"json_path": "confirmation.id"
}
],
"last_update_date": "2025-06-08T12:00:00.000Z", // Yeni
"last_update_user": "admin", // Yeni
"deleted": false, // Yeni
"created_date": "2025-06-08T12:00:00.000Z", // Yeni
"created_by": "admin" // Yeni
}],
// Yeni: Activity log
"activity_log": [{
"id": 1,
"timestamp": "2025-06-08T12:00:00.000Z",
"user": "admin",
"action": "CREATE_PROJECT",
"entity_type": "project",
"entity_id": 1,
"entity_name": "airline_agent",
"details": "Created new project"
}]
}
Tab Ekranları
1. User Info Tab'ı
Bu tab penceresinde login olan kullanıcı mevcut şifresini değiştirebilir. Ekrandaki alanlar:
Current Password (maskeli)
New Password (maskeli)
New Password (tekrar, maskeli)
Password Strength Indicator: Şifre girilirken güvenlik seviyesini gösterir (Weak/Medium/Strong)
Save butonu
Şifre değiştirebilmek için kullanıcı, maskeli alanlardan mevcut şifresini, yeni şifresini ve ikinci bir alanda teyit amaçlı olarak tekrar yeni şifresini girer ve kaydet butonuna basar. Şifre en az 8 karakter, büyük/küçük harf ve rakam içermelidir.
2. Environment Tab'ı
Bu tab'da aşağıdaki alanlar bulunur:
Work Mode: Seçenekleri hfcloud, cloud ve on-premise olan bir combo. Zorunlu.
Cloud Token (maskeli): Work Mode on-premise seçildiğinde disable olur.
Spark Endpoint: URL formatında. Zorunlu. Yanında "Test Connection" butonu.
Internal System Prompt (Yeni): Expansion panel içinde multi-line textarea. Spark'ın tüm projeler için kullanacağı temel kuralları içerir. Placeholder'lar:
<intent names>: Runtime'da intent listesiyle değiştirilir
<intent captions>: Intent caption'larıyla değiştirilir
<project language>: Proje diline göre değiştirilir
Save butonu
Reload from Spark butonu: Spark'tan güncel config'i çeker
3. APIs Tab'ı
Tab açıldığında, üstte bir toolbar bulunur:
Toolbar:
New API butonu
Import butonu: JSON dosyasından API tanımları yükler
Export butonu: Seçili API'leri JSON olarak export eder
Search alanı: API adı veya URL'de arama
Display Deleted checkbox
API Listesi Tablosu:
NameURLMethodTimeoutAuthDeletedActionsbook_flight_apihttps://api.example.com/bookPOST10s✓✗🖊️ 🧪 📋 🗑️
Action İkonları:
🖊️ Edit: Edit API dialog'unu açar
🧪 Test: API'yi test eder
📋 Duplicate: API'nin kopyasını oluşturur
🗑️ Delete: API'yi siler (kullanımda değilse)
4. Projects Tab'ı
Tab ekranına girildiğinde üstte toolbar bulunur:
Toolbar:
New Project butonu
Import Project butonu
Search alanı
Display Deleted checkbox
View: List/Card view toggle
Proje Listesi: Kart görünümünde her proje için:
┌─────────────────────────────────┐
│ 🛩️ airline_agent │
│ Havayolu Müşteri Temsilcisi │
│ Language: Turkish (tr) │
│ Versions: 3 (1 published) │
│ Status: ✓ Enabled │
│ Last update: 2 hours ago │
│ [Edit] [Versions] [Export] [⚙️] │
└─────────────────────────────────┘
5. Chat Tab'ı (Yeni)
Flare chat sistemini test etmek için kullanılır.
İşleyiş:
Project Selection: Enabled ve published version'u olan projeler listelenir
Start Chat: Session başlatır, session_id alır
Chat Interface:
Mesaj history'si
Input alanı
Send butonu
Session bilgileri (ID, project)
End Session: Chat'i sonlandırır
Özellikler:
Real-time mesajlaşma
Session takibi
Auto-scroll
Error handling
Loading states
6. Spark Integration Tab'ı (Yeni)
Bu tab'da Spark servisi ile doğrudan etkileşim sağlanır.
Üst Bölüm:
Project Selection: Dropdown ile proje seçimi
Proje seçildiğinde butonlar aktif olur
Butonlar ve İşlevleri:
Project Startup
Seçili projeyi Spark'a yükler
Backend üzerinden /spark/startup endpoint'ine istek atar
Response'u detaylı olarak gösterir
Get Project Status
Spark'taki tüm projelerin durumunu listeler
Tablo formatında: project_name, version, status, enabled, last_accessed
Status badge'leri: ready (yeşil), loading (turuncu), error (kırmızı), unloaded (gri)
Enable Project
Seçili projeyi Spark'ta aktif hale getirir
Disable Project
Seçili projeyi Spark'ta devre dışı bırakır
Delete Project
Seçili projeyi Spark'tan tamamen siler
Onay dialog'u gösterir
Response Panel:
Her işlemden sonra açılan expansion panel
Request ve response JSON'larını gösterir
Timestamp bilgisi
Success/error durumu
Son 10 işlem history'si
7. Test Tab'ı
Bu tab'da sistemin end-to-end testi yapılabilir:
Test Kategorileri:
UI Tests: Component render, navigation, form validation
Backend Tests: API endpoint'leri, data integrity
Integration Tests: UI-Backend entegrasyonu
Spark Tests: LLM bağlantısı ve response kalitesi
Ekran Düzeni:
┌─────────────────────────────────────────────┐
│ [Run All Tests] [Run Selected] [Stop] │
├─────────────────────────────────────────────┤
│ □ All Tests │
│ □ UI Tests (15 tests) │
│ □ Login Flow │
│ □ Project CRUD │
│ □ Version Management │
│ □ Backend Tests (22 tests) │
│ □ Authentication │
│ □ API Endpoints │
│ □ Race Conditions │
│ □ Integration Tests (18 tests) │
│ □ Spark Tests (8 tests) │
├─────────────────────────────────────────────┤
│ Test Results: │
│ ✓ Login with valid credentials - 120ms │
│ ✓ Create new project - 340ms │
│ ✗ Delete API in use - Expected behavior │
│ ⏳ Testing Spark connection... │
│ │
│ Progress: ████████░░ 80% (48/60) │
│ Passed: 45 | Failed: 3 | Running: 5 │
└─────────────────────────────────────────────┤
Test Detayları: Her test için:
Test adı ve açıklaması
Çalışma süresi
Hata durumunda detaylı log
"Re-run" butonu
8. Activity Log (Sağ üst notification icon'a tıklandığında açılır)
┌─────────────────────────────────────┐
│ 🔔 Recent Activities │
├─────────────────────────────────────┤
│ 2 min ago │
│ 👤 admin published version 2 │
│ of airline_agent │
├─────────────────────────────────────┤
│ 15 min ago │
│ 👤 user1 updated flight_info_api │
├─────────────────────────────────────┤
│ 1 hour ago │
│ 👤 admin created new project │
│ hotel_booking │
├─────────────────────────────────────┤
│ [View All Activities] │
└─────────────────────────────────────┘
Dialog Ekranları
Edit API Dialog (Güncelleme)
General Tab'a eklenenler:
Response Mappings Bölümü:
Variable Name: snake_case zorunlu
Type: str, int, float, bool, date seçenekleri
JSON Path: Dot notation ile path (örn: data.result.value)
Add/Remove mapping butonları
Validation: Variable name uniqueness
Template Variables (Geliştirilmiş):
Tüm intent parametrelerinden otomatik liste
Response mapping değişkenleri
Auth token değişkenleri
Config değişkenleri (work_mode, vb.)
Tıklanabilir chip'ler ile kolay ekleme
JSON Validation (Geliştirilmiş):
Numeric değişkenler için akıllı validation
Template variable type checking
Syntax highlighting
Test Tab (Geliştirilmiş):
Editable test request JSON
Placeholder değerlerle doldurma
Reset to template butonu
Response preview
Edit Project Dialog (Güncelleme)
Yeni alanlar eklendi:
Icon: Material icon seçimi (folder, work, shopping_cart, vb.)
Description: Proje açıklaması
Default Language: Varsayılan dil (tr, en, de, fr, es)
Supported Languages: Desteklenen diller (çoklu seçim)
Timezone: Saat dilimi (Europe/Istanbul, vb.)
Region: Bölge kodu (tr-TR, vb.)
Edit Version Dialog
[Mevcut içerik korunacak, değişiklik yok]
Edit Intent Dialog
[Mevcut içerik korunacak, değişiklik yok]
Edit Parameter Dialog
Date type desteği eklendi:
Type combo'suna "date" seçeneği
Date formatı: YYYY-MM-DD (ISO format)
Türkçe tarih ifadeleri için özel extraction prompt'lar
Version Comparison Dialog
[Mevcut içerik korunacak, değişiklik yok]
Flare Admin Test Planı
[Mevcut test planına ek olarak:]
Spark Integration Test Senaryoları:
Spark Startup Testi:
Proje seç
Startup butonuna bas
Response'u kontrol et
Get Status ile doğrula
Spark Project Lifecycle:
Enable → Disable → Delete akışı
Her adımda status kontrolü
Error handling testleri
Chat Test Senaryoları:
Full Chat Flow:
Session başlat
Intent detection testi
Parameter extraction testi
API call testi
Session sonlandır
Multi-turn Conversation:
Eksik parametre tamamlama
Context retention
Session state takibi
Response Mapping Testleri:
Mapping Validation:
Valid/invalid variable names
Type conversion testleri
Nested JSON path resolution
Runtime Mapping:
API response'tan değer extraction
Session variable update
Subsequent intent'lerde kullanım
Internal Prompt Testleri:
Placeholder Replacement:
<intent names> doğru değişiyor mu?
<intent captions> doğru değişiyor mu?
<project language> project default_language'den alınıyor mu?
Prompt Combination:
Internal prompt + general prompt birleşimi
Prompt öncelik sırası
Güvenlik ve Performans
Token Yönetimi:
SPARK_TOKEN environment variable'dan alınır
Tüm Spark isteklerinde Authorization header
Token rotation desteği
Race Condition Handling:
last_update_date kontrolü tüm CRUD işlemlerinde
Concurrent edit detection
Optimistic locking pattern
Session Management:
30 dakika inactivity timeout
Session cleanup thread
Memory-efficient storage
Teknoloji Stack
Frontend: Angular 17+ (standalone components)
UI Framework: Angular Material
State Management: RxJS
Backend: Python FastAPI
Authentication: JWT
Database: service_config.jsonc (document database pattern)
LLM Integration: Spark servisi
Bu güncellemelerle Flare Administration UI, tam fonksiyonel bir orchestration platform yönetim arayüzü haline gelmiştir.