# Kubiy Chat — Mwongozo wa Ku-install

Kubiy Chat ni **mlango rahisi (chat-mode)** wa mfumo wako mkubwa wa **Kubiy ERP**.
Mfanyabiashara anatuma picha/ujumbe kama WhatsApp; AI inasoma, inaainisha, na kurekodi —
**yote yanaingia kwenye database ile ile ya ERP yako.** Kwa hiyo ni rahisi kutumia,
lakini imeunganishwa kikamilifu na mfumo mkubwa.

---

## Wazo kuu: DATABASE MOJA

```
        ┌────────────────────────┐        ┌───────────────────────────┐
        │   KUBIY CHAT (mpya)    │        │   KUBIY ERP (uliopo)      │
        │  WhatsApp-style + AI   │        │  mauzo, stock, invoice,   │
        │  picha/paste -> data   │        │  ripoti, wateja           │
        └───────────┬────────────┘        └────────────┬──────────────┘
                    │                                   │
                    └───────────► MySQL MOJA ◄──────────┘
                       sales, sales_details, expences, product,
                       price, product_alias, purchases, stock_movements...
```

Chat inaandika kwenye jedwali zile zile za ERP. Kwa hiyo mauzo yaliyorekodiwa kwa **picha**
yanaonekana mara moja kwenye **ripoti za ERP** yako — hakuna "sync," ni database moja.

---

## Njia MBILI za ku-install (chagua)

### 🟢 NJIA A — Ya haraka (bolt-on kwenye ERP yako ya PHP)
Kama unataka kuanza LEO bila kujenga upya. Unatumia tool ya `whatsapp-import/`
moja kwa moja ndani ya ERP yako iliyopo. Inaandika kwenye `sales`, `expences` zako.

1. Nakili folda `whatsapp-import/` ndani ya mradi wako wa ERP (mfano `/htdocs/kubiy/ai/`).
2. Fungua `whatsapp_import_config.php`, weka:
   ```php
   define('GROQ_API_KEY', 'gsk_...');          // groq.com (bure)
   define('GEMINI_API_KEY', 'AIza...');        // aistudio.google.com (bure, bila kadi)
   define('GROQ_TEXT_MODEL',   'openai/gpt-oss-120b');
   define('GROQ_VISION_MODEL', 'qwen/qwen3.6-27b');
   ```
   (Angalia sehemu ya "AI Keys" chini.)
3. Hakikisha `$con` (muunganisho wa DB) unaelekeza database ya ERP yako.
4. Fungua kwenye browser: `https://tovuti-yako/kubiy/ai/index.php`. Tayari!

**Faida:** dakika chache, inatumia ERP yako iliyopo. **Kikomo:** ni tool ya import tu,
si gumzo kamili la wateja/wafanyakazi.

### 🔵 NJIA B — Platform kamili (Laravel chat-mode)
Mfumo mzima wa gumzo: kuchat na wateja/wafanyakazi/suppliers, kurekodi kwa picha,
madeni, manunuzi, stock reconciliation, invoice kwa AI. Inatumia **database ile ile ya ERP**.

Ona hatua kamili kwenye **`laravel/LARAVEL-SETUP.md`**. Kwa muhtasari:

```bash
composer create-project laravel/laravel kubiy-chat
cd kubiy-chat
php artisan install:api                    # Sanctum (auth ya API)

# nakili folda za laravel/app, laravel/routes, laravel/config,
# laravel/database/migrations juu ya mradi

# .env - elekeza database YA ERP yako (ili kushiriki data)
#   DB_DATABASE=kubiy      (database ile ile ya ERP)
#   GROQ_API_KEY=...   GEMINI_API_KEY=...

php artisan migrate                        # inaongeza jedwali za chat/documents/stock
php artisan queue:table && php artisan migrate
php artisan queue:work                     # kwa AI nyuma (background)
php artisan serve
```

> **Muhimu:** elekeza `DB_DATABASE` kwenye database ya ERP yako iliyopo. Migration za Kubiy Chat
> zinaONGEZA jedwali mpya (conversations, messages, documents, stock_movements) —
> **hazibomoi** `sales`, `product`, `invoice` zako zilizopo.

---

## 🔑 AI Keys (bure — hakuna kadi)

Mfumo unatumia **tabaka** ili usifungwe na provider mmoja:

| Provider | Gharama | Pata wapi | Matumizi |
|---|---|---|---|
| **Gemini** | Bure (bila kadi) | aistudio.google.com | Vision + text — bora kwa mwandiko wa mkono |
| **Groq** | Bure | console.groq.com | Vision + text — haraka |
| **Cerebras** | Bure | cloud.cerebras.ai | Fallback ya text |
| Google Vision | Kulipia (billing) | Google Cloud | Si lazima ukiwa na Gemini |

**Anza na Gemini:** aistudio.google.com → ingia na Google → *Create API key* → nakili `AIza...`.
**Hakuna kadi, hakuna billing.** (Free tier: Google anaweza kutumia data kuboresha model —
sawa kwa kuanza; kwa data nyeti ya wateja baadaye, hamia paid tier.)

---

## 🧾 Invoice kwa AI chat

Mfumo wako wa invoice (dynamic — unachukua bidhaa/bei/mteja kutoka DB) **haubadiliki.**
Kubiy Chat inakuwa tu **njia mpya ya kuingiza data:** badala ya kujaza fomu, mtumiaji
anasema *"tengeneza invoice ya Mama Aisha — gesi 15kg 2, regulator 1"*, AI inatoa data
iliyopangwa, kisha inaita **endpoint yako ya invoice iliyopo** (mfano `ajaxInvoice.php`)
kwa muundo unaotarajia. Mfumo wako wenyewe unahesabu VAT + jumla + PDF.
(Ona sampuli ya muonekano: `invoice-sample/kubiy-invoice-sample.html`.)

---

## Yaliyomo kwenye package

```
kubiy-pos/
├── INSTALL.md              (huu mwongozo)
├── README.md              (muhtasari + roadmap)
├── whatsapp-import/       NJIA A: tool ya PHP (drop-in kwenye ERP)
├── laravel/               NJIA B: platform kamili ya chat
│   ├── app/               Models, AiParser, Jobs, Actions, Controllers
│   ├── database/migrations/
│   ├── LARAVEL-SETUP.md
│   └── SCHEMA-README.md
├── preview/               UI (fungua kwenye browser)
│   ├── kubiy-full-preview.html      app kamili
│   └── kubiy-simbanking-ui.html     mtindo wa SimBanking + themes
├── invoice-sample/        muonekano wa invoice ya AI
├── test-tools/            test_google_vision.php (diagnostic)
└── test-images/           picha za kujaribu AI
```

---

## Mapendekezo (jinsi ya kuanza kwa busara)

1. **Leo:** Njia A — weka `whatsapp-import/` kwenye ERP yako + Gemini key. Anza kurekodi kwa picha.
2. **Wiki hii:** Fungua preview (`kubiy-full-preview.html`) — thibitisha muonekano na mtiririko.
3. **Baadaye:** Njia B — jenga platform kamili ya chat (Laravel), ikielekeza database ya ERP.
4. **Real-time:** ongeza Laravel Reverb kwa gumzo la papo hapo.
5. **Android:** funga kwa Capacitor kupata kamera + auto-save + notifications kama WhatsApp.

## Usalama (kabla ya kuwapa umma)

- Weka API keys kwenye `.env` / config isiyo kwenye GitHub ya wazi.
- HTTPS kila mahali.
- Rate limiting kwenye endpoint za AI (tayari: `throttle:20,1`).
- Tenant isolation: `BelongsToCompany` (tayari) — kila kampuni haioni data ya nyingine.
- Uploads: kagua mime + size (tayari kwenye DocumentController).