# Kubiy POS — Muundo wa Data (Laravel)

Migration tatu za kuanzia. Weka kwenye `database/migrations/`, kisha `php artisan migrate`.

## Faili

1. **...000001_create_tenancy_and_chat_tables.php** — makampuni, matawi, watumiaji (roles), na gumzo (conversations, members, messages, attachments).
2. **...000002_create_documents_table.php** — pipeline moja ya nyaraka zote (classification + status).
3. **...000003_create_inventory_and_ledger_tables.php** — stock ledger, physical counts, na ledger za purchases/payments/banking.

> **Muhimu:** `sales`, `sales_details`, `expences`, `product`, `price`, `product_alias` zako zilizopo **hazibomolewi**. Hizi ni za kuongeza. Ukiwa na `users` tayari, tumia migration ndogo ya "add columns" badala ya kutengeneza upya.

## Mtiririko (picha → ledger)

```
Mfanyakazi anatuma picha kwenye gumzo
        │
        ▼
  messages (type=image) + attachments (faili S3/R2/local)
        │
        ▼
  documents (status=pending, doc_type=unknown)
        │   ← Job ya background: AI inasoma + inaainisha
        ▼
  documents (status=parsed, doc_type=sales|purchase|expense|…, parsed_json)
        │   ← bot anajibu kwenye gumzo (messages type=system_card, meta=receipt+buttons)
        ▼
  Mtumiaji anabofya "Thibitisha"
        │
        ▼
  documents (status=confirmed) ──► inapost kwenye ledger husika:
        sales/sales_details   (doc_type=sales)
        purchases/items       (doc_type=purchase)
        expences              (doc_type=expense)
        payments              (customer_payment | supplier_payment)
        bank_transactions     (banking)
        stock_counts          (stock_count)
        │
        └──► stock_movements (in/out)  ← MOYO wa auditing
```

## Auditing (silaha ya kweli)

`stock_movements` ni ledger ya kila mwendo wa bidhaa. Stock inayopaswa kwa bidhaa:

```
inayopaswa = opening + Σ(IN) − Σ(OUT)
tofauti     = counted_qty (stock_counts) − inayopaswa
```

Tofauti ikiwa si sifuri → onyo (kama ile "Gesi 15kg −1" kwenye preview). Hapo ndipo unagundua mauzo yasiyorekodiwa, upotevu, au makosa.

## Eloquent relationships (muhtasari)

```php
// Conversation
public function members()  { return $this->belongsToMany(User::class, 'conversation_user')->withPivot('last_read_at'); }
public function messages()  { return $this->hasMany(Message::class); }

// Message
public function sender()     { return $this->belongsTo(User::class, 'sender_id'); } // null = Mfumo
public function attachments(){ return $this->hasMany(Attachment::class); }
public function document()   { return $this->hasOne(Document::class); }

// Document
public function branch()   { return $this->belongsTo(Branch::class); }
public function message()  { return $this->belongsTo(Message::class); }
public function movements(){ return $this->hasMany(StockMovement::class); }

// Multi-tenant: weka global scope ikimchuja kila query kwa company_id
// ya mtumiaji aliyeingia (Eloquent Global Scope) — hii ndiyo tenant isolation.
```

## Hatua zinazofuata

1. Models + relationships (kama hapo juu).
2. `ProcessDocument` Job — inayoita AI (Groq→Cerebras→Google fallback), inaweka `documents.parsed_json`, inatuma `system_card` kwenye gumzo.
3. `PostDocument` action — inayohamisha document iliyothibitishwa kwenda ledger + stock_movements.
4. Broadcasting (Reverb) kwa gumzo la real-time.
5. Global Scope ya company_id kwa tenant isolation (usisahau — usalama).