# ARCHITEKTURA SYSTEMU — MAPA KATALOGÓW

> Oficjalna mapa drogowa projektu **SliceHub Enterprise** dla Agentów AI.
> Nie zgaduj — sprawdzaj strukturę tutaj.

---

## 1. FRONTEND — Moduły UI

### A. STUDIO — Silnik Zarządzania Menu
`/modules/studio/`

| Plik | Rola |
|------|------|
| `index.html` | Szkielet i interfejs Studio |
| `js/studio_core.js` | Core API + logika współdzielona |
| `js/studio_ui.js` | Drzewo menu, kategorie, zaznaczanie masowe |
| `js/studio_item.js` | Edytor dania + Macierz Cenowa (Omnichannel) |
| `js/studio_modifiers.js` | Bliźniak Cyfrowy, zużycie surowców, akcje ADD/REMOVE |
| `js/studio_recipe.js` | Edytor receptur (surowce → dania) |
| `js/studio_bulk.js` | Edycja Masowa (ceny, publikacja temporalna) |
| `js/studio_margin.js` | Kalkulator marży |

### B. POS — Strefa Operacyjna
`/modules/pos/`

| Plik | Rola |
|------|------|
| `index.html` | Szkielet POS (kafelki + koszyk + checkout) |
| `js/pos_app.js` | Kontroler główny: auth, menu, koszyk, checkout |
| `js/pos_api.js` | API Wrapper → backend |
| `js/pos_cart.js` | Logika koszyka |
| `js/pos_ui.js` | Rendering UI |
| `css/style.css` | Dark theme POS |

### C. DISPATCHER — Centrum Logistyki (Kursy)
`/modules/courses/`

| Plik | Rola |
|------|------|
| `index.html` | 3 zakładki: Zamówienia / Mapa / Aktywne Kursy |
| `js/courses_app.js` | Auth PIN, polling 8s, dispatch workflow, modals (cash/reconcile) |
| `js/courses_api.js` | API Wrapper → `api/courses/engine.php` |
| `js/courses_map.js` | Leaflet.js: markery zamówień + kierowców (Carto Dark) |
| `js/courses_ui.js` | Karty zamówień, kierowców, kursów, SLA badges, wallet, toast |
| `css/style.css` | Dark Glass theme |

Workflow: `ready` + `available` → Select driver + orders → Dispatch → Kurs `Kn` z przystankami `L1..Ln`

Features:
- Intuitive driver selection → multi-order dispatch (click driver, click orders, send)
- Leaflet map with Carto Dark tiles (order + driver markers)
- Active courses view with per-course financial breakdown (cash/card/prepaid)
- Initial cash (pogotowie kasowe) modal per driver
- End-of-shift reconciliation modal (counted vs expected, variance flag)
- Emergency Recall button (flashes driver app red)
- SLA color coding: green (>5min) / yellow (≤5min) / red (overdue, pulsing)

### D. DRIVER APP — Aplikacja Mobilna PWA
`/modules/driver_app/`

| Plik | Rola |
|------|------|
| `index.html` | PIN login + bottom tab bar (Kursy / Portfel) |
| `js/driver_app.js` | Auth, polling 10s, GPS 15s, payment lock, emergency recall |
| `js/driver_api.js` | API Wrapper → `api/courses/engine.php` |
| `css/style.css` | High-contrast dark, touch 56px+, safe-area-inset, PWA |
| `manifest.json` | PWA manifest (standalone, portrait) |

Critical Features:
- **Payment Lock:** Driver CANNOT mark "Delivered" if order is unpaid. Must first tap "Gotówka" or "Karta" to collect payment. Pre-paid online orders show massive green "OPŁACONE" badge with one-click deliver.
- **Driver Wallet tab:** Real-time cash-in-hand, breakdown (start/collected/card), delivery history.
- **Emergency Alert:** Polls for dispatcher recall signal, flashes entire screen red with vibration.
- **Mobile UX:** 56px touch targets, `tel:` links for one-tap dialing, Google Maps navigation links.
- **GPS tracking:** Sends position every 15s to `sh_driver_locations`.

### E. WAREHOUSE — Moduł Magazynowy
`/modules/warehouse/`

| Plik | Rola |
|------|------|
| `index.html` | Dashboard (stany, dokumenty, alerty) |
| `js/warehouse_core.js` | Logika współdzielona |
| `manager_pz.html` | Przyjęcie towaru (PZ) |
| `manager_rw.html` | Rozchód wewnętrzny (RW) |
| `manager_in.html` | Inwentaryzacja (INW) |
| `manager_kor.html` | Korekta (KOR) |
| `manager_mm.html` | Przesunięcie międzymagazynowe (MM) |

---

## 2. BACKEND — API & Core

### Endpointy `/api/`

| Ścieżka | Opis |
|----------|------|
| `auth/login.php` | Auth (mode: `system` / `kiosk`) |
| `backoffice/api_menu_studio.php` | Router Studio (CRUD menu, ceny, modyfikatory, receptury) |
| `courses/engine.php` | Router logistyki (dispatch, status, GPS, reconcile, payment lock, recall) |
| `cart/CartEngine.php` | Silnik koszyka (ceny, grosze, half/half) |
| `cart/calculate.php` | Endpoint kalkulacji koszyka |
| `orders/checkout.php` | Finalizacja zamówienia |
| `orders/edit.php` | Edycja zamówienia po wybiciu |
| `warehouse/*.php` | Magazyn (receipt, stock_list, correction, transfer, inventory...) |
| `delivery/dispatch.php` | Standalone dispatch (kompatybilny; engine.php reimplementuje) |
| `delivery/reconcile.php` | Standalone reconciliation (j.w.) |

### Core `/core/`

| Plik | Rola |
|------|------|
| `db_config.php` | Połączenie PDO → `$pdo` |
| `AuthEngine.php` | loginSystem, loginKiosk, getTargetModule |
| `AuthGuard.php` | Stateless JWT guard (V2) |
| `JwtProvider.php` | Generowanie / walidacja JWT (HS256) |
| `auth_guard.php` | Session-based guard (legacy) |
| `js/api_client.js` | Bazowy `ApiClient` class (fetch wrapper) |

---

## 3. BAZA DANYCH & SKRYPTY

### Migracje `/database/migrations/`

| Nr | Plik | Co dodaje |
|----|------|-----------|
| 001 | `001_init_slicehub_pro_v2.sql` | Grand schema (wszystkie tabele, widoki, FK, indeksy) |
| 004 | `004_expand_search_aliases.sql` | sys_items: `search_aliases`, `is_active`, `is_deleted` + polskie deklinacje |
| 006 | `006_studio_mission_control.sql` | sh_categories: VAT / sh_menu_items: PLU, dostępność |
| 007 | `007_pos_engine_columns.sql` | sh_orders: druk paragonu, cart_json, NIP |
| 008 | `008_delivery_ecosystem.sql` | Nowa tabela `sh_driver_locations` (GPS) |
| 009–015 | `009–015_*.sql` | Delivery state machine, driver actions, integration logs, visual layers, companions, global assets, normalize drivers |
| 016 | `016_visual_compositor_upgrade.sql` | `sh_visual_layers`: +hero photo +kalibracja; `sh_board_companions`: +hero photo; tenant settings: +surface bg |

> Luki 002/003/005 — dawne seedy przeniesione do `seed_demo_all.php`.
> Szczegóły schematu → [`_docs/04_BAZA_DANYCH.md`](04_BAZA_DANYCH.md)

### Skrypty `/scripts/`

| Plik | Co robi | Uruchomienie |
|------|---------|--------------|
| `setup_database.php` | Migracje 006/007/008 (bez danych, idempotentny) | Przeglądarka |
| `seed_demo_all.php` | Unified Demo Seed — kompletne dane testowe dla CAŁEGO systemu | Przeglądarka / CLI |
| `seed_ultimate_delivery.php` | Delivery Ecosystem Seed — kierowcy, zamówienia delivery (paid/unpaid), GPS | Przeglądarka |

### Procedura czystej instalacji

```
1.  phpMyAdmin → CREATE DATABASE slicehub_pro_v2 (utf8mb4_unicode_ci)
2.  phpMyAdmin → Import → database/migrations/001_init_slicehub_pro_v2.sql
3.  Przeglądarka → http://localhost/slicehub/scripts/seed_demo_all.php
```

---

## 4. LEGACY — Strefa kwarantanny

`/_KOPALNIA_WIEDZY_LEGACY/` — Stary kod (60+ plików PHP/HTML)

**ZASADY DLA AI:**
1. Folder = **STRICTLY READ-ONLY**
2. Zakaz edycji, zakaz linkowania do nowego UI
3. Służy wyłącznie jako encyklopedia biznesowa — czytaj, zrozum logikę, napisz NOWY kod w folderze produkcyjnym

---

## 5. DOKUMENTACJA

| Plik | Zawartość |
|------|-----------|
| `_docs/02_ARCHITEKTURA.md` | Ten plik — mapa systemu |
| `_docs/04_BAZA_DANYCH.md` | Schemat bazy — tabele, relacje, konwencje, dane testowe |
| `_docs/05_INSTRUKCJA_FOTO_UPLOAD.md` | Limity uploadu, walidacja, instrukcja fotograficzna, brief dla managera/fotografa |
| `_docs/ustalenia.md` | Ustalenia projektowe — Online Ordering + Studio (bieżący dokument roboczy) |
| `database/README.md` | Quick start — instalacja / reset / aktualizacja bazy |