# Kubiy API (Laravel) — Mwongozo wa Kuanza

Backbone ya mfumo wa Kubiy (chat mode). Weka faili hizi kwenye Laravel mpya.

## 1. Anzisha Laravel + Sanctum

```bash
composer create-project laravel/laravel kubiy-api
cd kubiy-api
php artisan install:api          # Sanctum + routes/api.php
```

Nakili folda hizi juu ya zilizopo:
```
app/Models/            Company, Branch, User, Conversation, Message, Attachment, Document, StockMovement
app/Models/Concerns/   BelongsToCompany (tenant isolation)
app/Services/          AiParser  (Groq -> Gemini -> Google, na vision/text)
app/Jobs/              ProcessDocument
app/Actions/           PostDocument
app/Http/Controllers/Api/  Auth, Conversation, Message, Document
routes/api.php
config/services.php
database/migrations/   (zile tatu tulizotengeneza awali)
```

## 2. .env (secrets — SI ndani ya code)

```
DB_DATABASE=kubiy
DB_USERNAME=...
DB_PASSWORD=...

# AI providers (tabaka)
GROQ_API_KEY=gsk_...
GEMINI_API_KEY=AIza...        # <-- kutoka aistudio.google.com (BURE, bila kadi!)
CEREBRAS_API_KEY=csk-...
# GOOGLE_VISION_API_KEY=      # si lazima ukiwa na Gemini

# Storage (chagua moja)
FILESYSTEM_DISK=local          # au s3 / r2 / b2 (S3-compatible)

QUEUE_CONNECTION=database      # kwa ProcessDocument (background)
```

## 3. Migrate + queue

```bash
php artisan migrate
php artisan queue:table && php artisan migrate   # kama QUEUE_CONNECTION=database
php artisan queue:work                            # endesha job za AI nyuma
```

## 4. Pata Gemini key (BURE, dakika 2)

1. Nenda **aistudio.google.com** → ingia na Google account.
2. **Get API key** → **Create API key** → nakili (`AIza...`).
3. Weka kwenye `.env` kama `GEMINI_API_KEY`. **Hakuna kadi wala billing.**

## 5. Endpoints (API)

```
POST /api/register                         sajili biashara + mmiliki
POST /api/login                            ingia (phone + password) -> token
GET  /api/conversations                    orodha ya gumzo
GET  /api/conversations/{id}/messages      ujumbe
POST /api/conversations/{id}/messages      tuma ujumbe (mteja/mfanyakazi/supplier)
POST /api/documents                        pakia PICHA au maandishi (WhatsApp paste)
POST /api/documents/{id}/confirm           thibitisha -> post kwenye ledger + stock
POST /api/documents/{id}/reject            kataa
```

Kila request iliyolindwa inahitaji header:
```
Authorization: Bearer <token>
```

## 6. Mtiririko (jinsi kila kitu kinavyofanya kazi)

```
Mfanyakazi/supplier anatuma picha au ku-paste WhatsApp
   -> POST /api/documents
   -> Message (image/text) + Attachment + Document(pending)
   -> ProcessDocument Job (nyuma):
        AiParser: Groq -> Gemini -> Google
        inaainisha doc_type (sales/purchase/expense/...)
        inaweka parsed_json, inatuma "system_card" kwa bot kwenye gumzo
   -> Mmiliki anabofya Thibitisha -> POST /confirm
   -> PostDocument: inapost kwenye sales/purchases/expences + stock_movements
   -> Stock reconciliation: StockMovement::expectedQty() vs stock_counts
```

## Yanayofuata

- **Reverb** (real-time): `php artisan install:broadcasting` -> Reverb, kisha `broadcast(new MessagePosted($msg))` kwenye MessageController + ProcessDocument (nimeacha TODO).
- **resolveProduct()** kwenye PostDocument: unganisha na `product_alias` yako kwa fuzzy match.
- **Reports/auditing endpoint**: `GET /api/reports/today` (tumia StockMovement::expectedQty + stock_counts).
- **Tenant isolation** tayari ipo (BelongsToCompany) — hakikisha kila model mpya inaitumia.