karczma-aplikacja-stoliki/README.md

Karczma-Stoliki 🍻

System podglądu zamówień (KDS) oraz interaktywny panel dla gości restauracji, oparty na integracji z bazą MS SQL programu Gastro.

Aplikacja rozwiązuje problem sprawdzania statusu przygotowania zamówienia przez gości przy stoliku oraz udostępnia widok produkcyjny (Kitchen Display System) dla personelu na kuchni.

---

🏗 Struktura Katalogów

Projekt jest podzielony wg poniższej struktury:

karczma-stoliki/
├── api/                        # Endpointy Backendowe (PHP)
│   ├── bills.php               # Zwraca pozycje na rachunkach wg stolika (używane przez klientów)
│   ├── kds.php                 # Zwraca status zamówień na kuchni (odfiltrowane)
│   ├── get_table_name.php      # Helper: Mapuje bezpieczny Hash (GUID) na nazwę stolika
│   └── cache/                  # Zapis lokalnego pliku JSON (tables_cache.json) z listą stolików
├── config/                     # Konfiguracja
│   └── database.php            # WSPÓLNA konfiguracja połączenia z MS SQL (Zmień hasło tylko tu!)
├── public/                     # Pliki serwowane użytkownikom
│   ├── stolik2_api.html        # Główny interfejs dla klienta (czyta Hash z URL)
│   ├── assets/                 # Style CSS i skrypty JS klienta (stolik2_api.js)
│   └── staff/                  # Narzędzia wewnętrzne dla obsługi
│       ├── kds.php             # Główny widok ekranu kuchennego (odpytuje api/kds.php)
│       └── generator.php       # Generator bezpiecznych kodów QR/linków do stolików
├── docs/                       # Dokumentacja i pliki dla AI
│   └── ai.txt                  # Główne zrzuty struktury tabel z Gastro
├── scripts/                    # Skrypty narzędziowe / deweloperskie (wyciąganie schematów)
└── legacy/                     # Stare pliki (Node.js/WebSockety - nie używane na produkcji)

🔒 Bezpieczeństwo URL (Hash)

Z powodów bezpieczeństwa, aby klienci w restauracji nie podglądali zamówień z innych stolików (zgadując adres np. ?table=1), aplikacja używa natywnych identyfikatorów z bazy MS SQL (tj. GUID, np. 5D1BF524-F8B3-4D34-BEF5-9BA1A25E0475).

• Link do stolika dla klienta: http://<IP>/karczma-stoliki/public/stolik2_api.html?h=GUID
• Kelner generuje te linki / kody QR w zakładce public/staff/generator.php.
• Gdy klient wchodzi pod link, get_table_name.php błyskawicznie "tłumaczy" Hash na nazwę stolika (np. "C-57") korzystając z pamięci podręcznej JSON wbudowanej w podkatalog api/cache/, odciążając w ten sposób bazę MS SQL.

(Uwaga: widok kuchni public/staff/kds.php posiada ukryty parametr kds_secret=karczma_kuchnia po to, by omijać filtrowanie hashem i wyświetlać wszystkie zlecenia naraz)

🛠 Wdrożenie (Setup)

1. Sklonuj lub wgraj repozytorium do katalogu htdocs serwera XAMPP.
2. Zaktualizuj IP serwera SQL, użytkownika i hasło (sa / karczma!@#26) w pliku config/database.php.
3. Upewnij się, że włączone i załadowane są sterowniki sqlsrv dla PHP.
4. Upewnij się, że folder api/cache posiada prawa zapisu (chmod 777 na Linuksie / Pełna kontrola na Windowsie) by skrypt mógł wygenerować tables_cache.json.
5. Dla ułatwienia pracy, na roocie znajduje się index.php (Dev Portal), z którego możesz klikać we wszystkie moduły (do usunięcia na produkcji).

📊 Analityka (MVP)

W projekcie działa eventowa analityka oparta o MySQL:

• Endpoint zapisu eventów: api/analytics.php (POST JSON).
• Endpoint raportowy pod panel: api/analytics_reports.php (GET, parametr days).
• Skrypt agregacji dziennej: scripts/analytics_aggregate_daily.php.

Przykładowe uruchomienie agregacji:

php scripts/analytics_aggregate_daily.php
php scripts/analytics_aggregate_daily.php 2026-05-28

Przykładowe raporty JSON:

• api/analytics_reports.php?days=7
• api/analytics_reports.php?days=30

💡 Jak działa mapowanie zamówień?

• Aplikacja KDS wyciąga dane łącząc tabele dbo.NGastroDTRachunek i dbo.NGastroDTRachunekPozycja.
• Filtruje ona zamówienia, używając StatusRealizacji.
• Pozycje wydzielane łączone są sprytnym zapytaniem regex sprawdzającym pole Opis na wypadek, gdyby POS utracił przypisanie fizycznego ID stolika przy podziale rachunku.
• Składniki zestawów (np. dodatki do Pizzy) sprytnie grupują się pod wspólnym węzłem wykorzystując klucz GrupaZestawuID.