# Panduan Setup — Sistem Pangkalan Pengetahuan

## Keperluan Sistem

- PHP 8.3+ (PHP 8.5 disokong)
- MySQL 8.0+
- Composer 2.x
- Ollama (berjalan pada localhost:11434)
- Qdrant (berjalan pada localhost:6333)
- Node.js (optional, untuk Vite)

---

## Langkah 1: Konfigurasi .env

```bash
# Salin contoh .env
cp .env.example .env

# Jana app key
php artisan key:generate
```

Edit `.env` dengan tetapan anda:

```env
# Database MySQL
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=knowledge_base
DB_USERNAME=root
DB_PASSWORD=your_password_here

# Ollama (tukar model ikut yang anda ada)
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_CHAT_MODEL=llama3
OLLAMA_EMBEDDING_MODEL=nomic-embed-text

# Qdrant
QDRANT_BASE_URL=http://localhost:6333
QDRANT_VECTOR_SIZE=768
```

---

## Langkah 2: Setup Database

```bash
# Buat database (dalam MySQL)
mysql -u root -p -e "CREATE DATABASE knowledge_base CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# Jalankan migrasi
php artisan migrate

# Seed data awal (kategori + user admin + sample FAQ)
php artisan db:seed
```

---

## Langkah 3: Pull Model Ollama

```bash
# Model embedding (wajib)
ollama pull nomic-embed-text

# Model chat (pilih satu)
ollama pull llama3       # atau
ollama pull mistral      # atau
ollama pull qwen2        # (lebih ringan)
```

---

## Langkah 4: Setup Qdrant

```bash
# Jalankan Qdrant dengan Docker
docker run -p 6333:6333 -p 6334:6334 \
  -v $(pwd)/qdrant_storage:/qdrant/storage:z \
  qdrant/qdrant

# Collection akan dibuat secara automatik semasa pertama embed
```

---

## Langkah 5: Semak Kesihatan Sistem

```bash
php artisan kb:health-check
```

Output yang dijangka:
```
════════════════════════════════════════
  PEMERIKSAAN KESIHATAN SISTEM
════════════════════════════════════════

📦 MySQL
   ✅ Berjaya sambung ke: knowledge_base

🤖 Ollama
   ✅ Online
   ✅ Model Chat:    llama3
   ✅ Model Embed:   nomic-embed-text

🗄️  Qdrant
   ✅ Online
   ✅ Collection:    knowledge_base
   📊 Vectors:      0

⏳ Queue
   ✅ Driver konfigurasi untuk async.

════════════════════════════════════════
  ✅ SEMUA PERKHIDMATAN OK
════════════════════════════════════════
```

---

## Langkah 6: Setup Storage

```bash
# Link public storage
php artisan storage:link
```

---

## Langkah 7: Jalankan Queue Worker

```bash
# Development
php artisan queue:work --timeout=600 --tries=2

# Production (gunakan Supervisor)
php artisan queue:work --queue=default --sleep=3 --tries=2 --timeout=600
```

---

## Langkah 8: Jalankan Aplikasi

```bash
php artisan serve
```

Akses:
- **Chatbot:** http://localhost:8000/chatbot
- **Admin:** http://localhost:8000/admin
- **Login:** admin@example.com / password

---

## Arahan Artisan Berguna

```bash
# Semak kesihatan sistem
php artisan kb:health-check

# Reindex satu dokumen
php artisan kb:reindex-document --document_id=1

# Reindex semua dokumen yang gagal
php artisan kb:reindex-document --all-failed

# Reindex semua dalam kategori pelesenan
php artisan kb:reindex-category --slug=pelesenan

# Preview tanpa jalankan (dry run)
php artisan kb:reindex-category --slug=pelesenan --dry-run

# Monitor queue
php artisan queue:monitor default
```

---

## Nota Production

1. **Tukar kata laluan admin** di admin panel atau melalui tinker
2. **Set QUEUE_CONNECTION=redis** dan gunakan Supervisor untuk queue worker
3. **Set APP_DEBUG=false** dalam .env
4. **Setup backup** untuk storage/app/documents/ (fail PDF asal)
5. **Rate limiting** chatbot sudah dikonfigurasi (20 req/min per IP) — laraskan `KB_CHAT_RATE_LIMIT`
6. **Qdrant** — tambah API key untuk keselamatan (`QDRANT_API_KEY=xxx`)

---

## Struktur Direktori Penting

```
app/
├── Actions/           ← Single-purpose business logic
├── Console/Commands/  ← Artisan commands (kb:*)
├── Http/Controllers/  ← Admin & Chatbot controllers
├── Jobs/              ← Queue jobs
├── Models/            ← Eloquent models
└── Services/
    ├── Document/      ← PDF extraction & chunking
    ├── KnowledgeBase/ ← Ingestion, RAG, Audit
    ├── Ollama/        ← Ollama HTTP client
    └── Qdrant/        ← Qdrant HTTP client

config/
├── knowledgebase.php  ← Konfigurasi umum KB
├── ollama.php         ← Konfigurasi Ollama
└── qdrant.php         ← Konfigurasi Qdrant

storage/app/documents/ ← Fail PDF asal (JANGAN padam)
```