78 lines
4.4 KiB
Markdown
78 lines
4.4 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
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`.
|