First commit

2026-05-18 08:56:23 +08:00
commit fd3d3a4d2b
147 changed files with 22099 additions and 0 deletions
--- a/SETUP.md
+++ b/SETUP.md
@@ -0,0 +1,214 @@
+# 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)
+```