Eğitmen Asistanı (Instructor Copilot)

Achidemy Copilot — eğitmen panelinde AI destekli chatbot, Cloudflare Workers AI (Llama 3.1), çok dilli yanıtlar, tıklanabilir linkler ve platform yönlendirmeleri.

Eğitmen panelinde sağ alt köşede yer alan Achidemy Copilot, eğitmenlere platform kullanımı, kurs yönetimi, ödemeler ve iletişim konularında anında yardımcı olan yapay zeka destekli asistandır. Udemy benzeri destek botları gibi çalışır; ek sunucu veya harici API anahtarı gerektirmez, Cloudflare Workers AI (Meta Llama 3.1 8B Instruct) kullanır.

Genel Bakış

Özellik	Açıklama
Konum	Eğitmen layout’unun sağ alt köşesi; tüm eğitmen sayfalarında görünür.
Erişim	Sadece eğitmen ve admin rolleri. Öğrenciler bu API’yi çağıramaz.
Model	Cloudflare Workers AI: `@cf/meta/llama-3.1-8b-instruct`.
Çıktı	JSON: `reply` (metin + isteğe bağlı Markdown linkler), `action` (tek buton), `suggestions` (3 hızlı soru).
Diller	TR, EN, ES, DE, JA, FR — sistem prompt’u ve UI metinleri locale ile uyumlu.

Asistan, yanıt metninde doğal tıklanabilir linkler sunar (örn. “Yeni kursunuzu buraya tıklayarak oluşturabilirsiniz”); ayrıca tek bir aksiyon butonu ve önerilen sorular ile kullanıcıyı doğru sayfaya yönlendirir.

Mimari

┌─────────────────────────────────────────────────────────────────┐
│  Instructor Layout (app/routes/instructor.tsx)                   │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │  Sidebar + Outlet                                           │ │
│  │                                    ┌───────────────────────┐│ │
│  │                                    │ InstructorChatbot     ││ │
│  │                                    │ (floating, bottom-right)││ │
│  │                                    └───────────┬────────────┘│ │
│  └───────────────────────────────────────────────│─────────────┘ │
└──────────────────────────────────────────────────│──────────────┘
                                                   │
                                    POST /api/instructor-chat
                                    { messages, lang }
                                                   │
                                                   ▼
┌─────────────────────────────────────────────────────────────────┐
│  api.instructor-chat.ts (Remix action)                           │
│  • Auth: session (instructor | admin)                           │
│  • buildSystemPrompt(lang) → system message                      │
│  • env.AI.run('@cf/meta/llama-3.1-8b-instruct', { messages })   │
│  • JSON parse + fallback → { reply, action, suggestions }        │
└─────────────────────────────────────────────────────────────────┘

Frontend: app/components/instructor/InstructorChatbot.tsx — tek bileşen; mesaj listesi, giriş alanı, gönder, link parser, aksiyon butonu, öneriler.
Backend: app/routes/api.instructor-chat.ts — POST only; auth, system prompt üretimi, Cloudflare AI çağrısı, JSON yanıt.

Backend: API ve Sistem Yönergesi

Dosya ve Route

Dosya: app/routes/api.instructor-chat.ts
URL: POST /api/instructor-chat (dil öneki yok; routes.ts içinde tanımlı).

Kimlik Doğrulama

initAuth(dbUrl, env) ile oturum alınır.
session.user.role === "instructor" veya "admin" olmalıdır; aksi halde 401 Unauthorized.
Öğrenci veya giriş yapmamış kullanıcılar isteği gönderemez.

İstek Gövdesi

{
  "messages": [ { "role": "user" | "assistant", "content": "..." } ],
  "lang": "tr"
}

messages: Son birkaç mesaj (genelde son 5) bağlam için gönderilir.
lang: Hedef dil kodu (tr, en, es, de, ja, fr). Yanıttaki tüm metinler bu dilde üretilir.

Sistem Yönergesi (System Prompt)

buildSystemPrompt(targetLanguage) ile dinamik oluşturulur. Özet kurallar:

Çıktı: Sadece geçerli JSON; markdown kod bloğu yok.
Yapı: { "reply": "...", "action": { "label": "...", "url": "/path" } | null, "suggestions": ["...", "...", "..."] }.
Dil: Tüm kullanıcıya dönük metinler (reply, action.label, suggestions) hedef dilde.
URL’ler: Sadece aşağıdaki resmi route listesinden; çeviri veya uydurma yok. Uygulama dil önekini ekler.
reply içi linkler: Ham URL yazmak yasak; Markdown link sözdizimi zorunlu: [Tıklanacak metin](/url). Örnek: “Kursunuzu buraya tıklayarak oluşturabilirsiniz.”

Resmi Route Listesi (Bilgi Tabanı)

Asistan yalnızca aşağıdaki path’leri kullanır (hem action.url hem reply içi linkler için):

Amaç	URL
Eğitmen paneli ana sayfa / kurslarım	`/instructor`
Yeni kurs oluştur	`/instructor/create`
Kurs düzenle / müfredat / landing / fiyat	`/instructor` (listeden kurs seçilir)
Ödemeler / bakiye / kazanç	`/instructor/payouts`
Mesajlar (gelen kutusu)	`/instructor/messages`
İletişim / hoş geldin / Q&A	`/instructor/communication`
Performans özeti	`/instructor/performance`
Öğrenci istatistikleri	`/instructor/performance/students`
İncelemeler	`/instructor/performance/reviews`
Kuponlar	`/instructor/coupons`
Araçlar (AI: sosyal medya, pazar, quiz, müfredat)	`/instructor/tools`
Paketler (liste + yeni paket)	`/instructor/bundles`
Paket listesi	`/instructor`
Ödeme yöntemleri / KYC	`/account/payment-methods`
Profil / şifre / bildirimler	`/account` veya `/account/profile`
Öğrenci tarafı / kayıtlı kurslar	`/my-courses`

Platform Kuralları (Prompt İçinde)

Ödeme eşiği: 100$.
Komisyon: %5 (direkt satış), %55 (organik).
Videolar: Bunny.net ile güvenli teslimat.
Kurs yönetimi: Önce /instructor, sonra ilgili kursa girilir.

AI Çağrısı ve Yanıt İşleme

Model: @cf/meta/llama-3.1-8b-instruct.
Parametreler: messages (system + kullanıcı/asistan geçmişi), max_tokens: 800.
Yanıt metni markdown json kod bloklarından temizlenir, JSON.parse ile ayrıştırılır.
Parse hatasında: ham metin reply’a konur, action: null, varsayılan 3 öneri döner.

Frontend: InstructorChatbot Bileşeni

Dosya ve Entegrasyon

Dosya: app/components/instructor/InstructorChatbot.tsx
Kullanım: app/routes/instructor.tsx layout’unda render edilir; tüm eğitmen sayfalarında görünür.

UI Öğeleri

Öğe	Açıklama
Aç/Kapa	Sağ altta sabit buton (MessageCircle + Sparkles); tıklanınca sohbet paneli açılır/kapanır.
Header	“Achidemy Copilot”, “Online & Hazır” göstergesi, kapat butonu.
Mesaj listesi	Kullanıcı (sağ, primary) ve asistan (sol, beyaz kart) balonları; asistan balonunda linkler tıklanabilir.
Aksiyon butonu	API’den `action` gelirse, label ve ok ile tek buton; tıklanınca `getLocalizedPath(action.url)` ile yönlendirilir, panel kapanır.
Öneriler	Son asistan mesajında 3 chip; tıklanınca o metin gönderilir.
Giriş + Gönder	Metin kutusu ve gönder butonu; Enter ile gönderim.

Tıklanabilir Linkler: renderMessageWithLinks

Asistan yanıtındaki Markdown linkler [Metin](/url) parse edilip gerçek tıklanabilir öğelere dönüştürülür.

Regex: \[([^\]]+)\]$([^)]+)$/g
Davranış: Link metni bir <span role="button"> içinde render edilir; tıklanınca navigate(getLocalizedPath(url)) çağrılır ve sohbet penceresi kapanır.
Erişilebilirlik: tabIndex={0}, onKeyDown (Enter/Space), aria-label ile klavye ve ekran okuyucu desteklenir.
Stil: Asistan mesajında text-primary, kullanıcı mesajında açık renk; underline ve focus ring ortaktır.

Böylece “/instructor sayfasına gidin” yerine “Yeni kursunuzu buraya tıklayarak oluşturabilirsiniz” gibi doğal ve tıklanabilir bir deneyim sunulur.

Dil ve Çeviriler

API’ye gönderilen: lang (useLang’dan); system prompt hedef dili buna göre ayarlanır.
UI metinleri: useTranslation() ile chatbot.welcome, chatbot.sugg1–sugg3, chatbot.placeholder, chatbot.error (örn. app/locales/tr.json, en.json vb.) kullanılır.

Güvenlik ve Hata Durumları

Durum	HTTP	Açıklama
Yetkisiz (öğrenci / oturum yok)	401	Sadece instructor/admin.
Method not allowed	405	Sadece POST.
Geçersiz JSON gövde	400	Body parse hatası.
DB/Env yok	500	Sunucu yapılandırması.
AI binding yok	503	“Yapay zeka servisi şu anda kullanılamıyor.”
AI hata / timeout	500	“Sistem şu an meşgul.”

Frontend’de ağ veya sunucu hatalarında chatbot.error (veya “Bağlantı hatası oluştu.”) gösterilir.

Özet

Achidemy Copilot, eğitmen panelinde Cloudflare Workers AI (Llama 3.1) kullanan, çok dilli ve platformla entegre bir asistan chatbot’udur.
Backend’de system prompt ile resmi route listesi ve platform kuralları tanımlıdır; yanıtlar JSON ve reply içi Markdown linkler ile standartlaştırılmıştır.
Frontend’de renderMessageWithLinks ile [Metin](/url) tıklanabilir hale getirilir; action butonu ve suggestions ile yönlendirme ve hızlı soru deneyimi sağlanır.
Dokümantasyonu güncellerken bu sayfa, Eğitmen ve Kurs Yönetimi (Instructor Engine), Eğitmen AI Araçları (Instructor Tools) ve Kurs Keşfet ve Arama (Course Discovery) ile birlikte referans alınabilir.