# Specyfikacja aplikacji EMG POS dla programisty

Wersja 1.0 • 13 października 2026 r. • Zakres funkcjonalny i plan integracji

Aplikacja ma służyć właścicielowi i pracownikom sieci restauracji do kontroli sprzedaży, menu, receptur, zużycia surowców, stanów oraz zamówień. Zadaniem wdrożenia jest połączenie istniejącego interfejsu z rzeczywistymi danymi z KSeF, systemu magazynowego i Gastro POS, przy zachowaniu prostoty obsługi.

**Obecna aplikacja jest prototypem z lokalną bazą i danymi testowymi. Nie ma uruchomionego połączenia produkcyjnego z KSeF, magazynem ani Gastro POS.** Zatwierdzenie zamówienia zapisuje je w aplikacji; wysyłka do dostawców nie jest podłączona. Poniższe wymagania opisują zarówno istniejące funkcje, jak i docelowe działanie. Propozycje techniczne oraz kwestie wymagające decyzji wskazano osobno.

## 1 Lokale i podstawowe zasady

Obsługiwane lokale: Popularna, Dirty Joe, Halka, Pyzata Chata, Św. Jan, Madonna, Św. Michał i Queen Mama. Każdy ma własne menu, podział Kuchnia / Bar, kategorie, stany, receptury i przypisania dostawców. Właściciel widzi także całą sieć.

Identyfikator lokalu w aplikacji musi mieć jawne powiązanie z identyfikatorem w Gastro, magazynem lub magazynami oraz podmiotem prawnym i NIP-em. Nie należy zakładać, że osiem restauracji oznacza osiem NIP-ów. Tego przypisania jeszcze nie ustalono.

W interfejsie ceny mają być zawsze **brutto**. Baza powinna zachowywać również źródłowe kwoty netto, VAT, walutę i reguły zaokrąglenia, aby można było odtworzyć dokument. Nie wolno zamieniać ceny netto w brutto wyłącznie przez zmianę etykiety.

Waluta podstawowa to PLN, strefa raportowania Europe/Warsaw. Import przechowuje również oryginalny czas, strefę i dzień operacyjny POS, jeżeli różni się od dnia kalendarzowego.

## 2 Funkcje poszczególnych działów

### Przegląd sieci

- Filtry lokalu i dat od–do oraz szybki wybór okresu.
- Sprzedaż brutto, liczba rachunków, średni rachunek i liczba sprzedanych sztuk, z porównaniem okresów.
- Sprzedaż godzinowa i podział płatności. Należy obsłużyć również płatności mieszane, vouchery i inne formy obecne w Gastro.
- Ranking towarów oraz tabela wyników restauracji.
- Wykres lunchów od poniedziałku do piątku, niebieskie słupki, wielkość jak wykres powyżej. Nad słupkiem kwota i liczba porcji. Kliknięcie pokazuje nazwy lunchów, ilości i kwoty.

Docelowo lunche należy oznaczać w kartotece lub mapowaniu kategorii. Obecne demonstracyjne rozpoznawanie po nazwie nie wystarcza jako reguła produkcyjna. Wszystkie wskaźniki muszą pochodzić z tego samego zestawu rozliczonych transakcji.

### Sprzedaż towarów

Lista produktów sprzedanych w wybranym lokalu i okresie: ilość, rzeczywista wartość sprzedaży brutto, udział w sprzedaży, wyszukiwanie, sortowanie i podział Kuchnia / Bar. Zwroty, rabaty i storna mają wynikać ze statusów oraz wartości źródłowych, a nie z mnożenia aktualnej ceny katalogowej przez liczbę sztuk.

### Magazyn vs sprzedaż

Porównanie ilości przyjętych lub wydanych do lokalu ze sprzedażą i zużyciem według receptur. Widok zachowuje kategorie i duży przełącznik Kuchnia / Bar po prawej. Kolumny porównania dań: danie, cena sprzedaży / koszt porcji, ilość dostarczona / sprzedana oraz różnica / wartość. Bez kolumny Receptura.

Trzeba rozdzielić pojęcia „zamówiono”, „dostarczono” i „zużyto”. Złożone zamówienie nie zwiększa stanu. Samo dostarczenie większej ilości niż sprzedana nie oznacza straty, ponieważ zapas może pozostać w lokalu.

Dla gotowego produktu, np. zupy w pojemniku, można przeliczyć dostawę na porcje. Przy daniach wieloskładnikowych oraz składnikach wspólnych dla wielu dań rozliczenie prowadzi się na poziomie surowca. Nie wolno przypisywać całej dostawy jednego surowca niezależnie do kilku potraw.

### Menu lokalu

Nagłówek „Menu” z nazwą lub wyborem restauracji. Filtry nazwy dania i kategorii, duży przełącznik Kuchnia / Bar po prawej. Tabela: danie, cena brutto, receptura oraz akcje edycji i usuwania. Przy każdej kategorii „Dodaj danie”, na dole „Dodaj kategorię”. Kategorie można przeciągać myszką, a kolejność jest zapisywana dla lokalu i sekcji.

Usuwanie pozycji użytej w historii oznacza archiwizację. Nie może usunąć historycznej sprzedaży ani receptur użytych do jej rozliczenia. Zmiana menu w panelu nie może automatycznie zmieniać konfiguracji kas. Publikacja do Gastro POS, jeśli zostanie zamówiona, wymaga osobnego uzgodnienia i obsługi konfliktów.

### Receptury

Na górze tylko tytuł i wybór lokalu. Po lewej „MENU”, przełącznik Kuchnia / Bar, wyszukiwanie i dania pogrupowane w kategorie. Po prawej nazwa dania i tabela składników na jedną porcję.

„Dodaj artykuł” otwiera prosty wiersz: nazwa z podpowiedzią z katalogu zakupowego, ilość i jednostka g / ml / szt. Można dodawać kolejne składniki, zmieniać ilości oraz je usuwać. Katalog jest wspólnym źródłem dla receptur i listy zakupów.

AI ma proponować wstępne receptury i brakujące artykuły na podstawie menu. Propozycje wymagają sprawdzenia i zatwierdzenia. AI nie ustala wiarygodnie faktycznej gramatury kuchni, ceny zakupu, stanów ani dostawcy na podstawie samej nazwy dania. Nie może zastępować zatwierdzonych receptur bez zgody użytkownika. Obecnie przygotowano mechanizm propozycji, lecz usługa AI wymaga konfiguracji.

### Zamówienia

**Lista zamówień dla pracownika:** wybór lokalu, liczby dni lub zakresu dat, Kuchnia / Bar i kategoria. Lista zajmuje możliwie całą dostępną szerokość. Kolumny: artykuł, stan, sprzedano oraz zamów. Stan i sprzedano są tylko do odczytu. Ilość zamawiana ma czytelny licznik „− 0 +” oraz możliwość wpisania liczby. Bez dostawców i przycisków administracyjnych w wierszach. Na dole jeden główny przycisk „Zamów”.

W tej liście „sprzedano” dla surowca oznacza zużycie wyliczone ze sprzedaży dań i receptur, przeliczone na jednostki zakupowe. Nie jest to liczba sprzedanych opakowań surowca. Rozróżnienie powinno być dostępne w krótkiej podpowiedzi.

**Zarządzanie:** stan wpisywany przez managera, zapis automatyczny z informacją o błędzie lub powodzeniu, przypisanie dostawcy i edycja artykułu. Brak kolumn sprzedaży i zamawianej ilości oraz zakresu dat w górnym pasku. „Dodaj artykuł” przy każdej kategorii, zielone akcje dodawania, czerwony kosz i trzy kropki do edycji. Kategorie można dodawać, edytować, usuwać i zmieniać ich kolejność. Po usunięciu kategorii artykuły pozostają dostępne w kategorii zastępczej.

Wpisanie stanu musi tworzyć datowany pomiar inwentaryzacyjny, z autorem i czasem. Nie jest korektą ilości na fakturze. Rozróżnić pustą wartość, zero i brak aktualnego pomiaru.

**Potwierdzenie:** „Zamów” otwiera podsumowanie niezerowych pozycji. Użytkownik wraca do edycji albo wybiera „Potwierdź”. Docelowo dopiero potwierdzenie uruchamia wysyłkę, grupując pozycje według dostawców. Należy przechowywać stany robocze, potwierdzone, oczekujące na wysyłkę, wysłane i błąd wysyłki. Status dostarczenia wiadomości tylko po wiarygodnym potwierdzeniu od dostawcy usługi.

Podłączenie skrzynki i ewentualnej bramki SMS zostało odłożone. Obecnie aplikacja nie może oznaczać potwierdzonego zamówienia jako wysłanego. Przed wysyłką produkcyjną wymagane są prawdziwe kontakty, przypisania dostawców i ochrona przed powtórnym wysłaniem tego samego zamówienia.

### FV

Na górze lokal, daty od–do oraz miesiąc. Poniżej lista faktur z wyszukiwaniem kontrahenta i filtrem daty dostawy. Widoczne: data faktury, data dostawy, kontrahent, numer, lokal, kwota brutto i dostęp do dokumentu.

Głównym źródłem są faktury zakupowe pobierane z KSeF. Dokumenty spoza tego źródła wymagają kontrolowanego importu lub dodania przez uprawnioną osobę. Nie wolno obiecywać, że KSeF obejmie każdy dokument zakupowy.

Nie dodawać ponownie osobnych pozycji Koszty, Magazyn i Połączenia do głównego menu. Konfiguracja integracji powinna być dostępna administratorowi poza codziennym widokiem pracownika.

## 3 Źródła danych i odpowiedzialność

| Dane | Docelowe źródło | Reguła |
|---|---|---|
| Rachunki i rzeczywista sprzedaż | Gastro POS lub autoryzowany interfejs Gastro agregujący POS | Kwoty z pozycji transakcji po rabatach i korektach |
| Aktualna cena sprzedaży i menu POS | Kartoteka Gastro | Osobne od historycznej ceny na rachunku |
| Faktury i ich korekty | KSeF oraz oznaczone dokumenty spoza KSeF | Faktura nie jest samodzielnym dowodem fizycznego przyjęcia towaru |
| Przyjęcia, wydania, przesunięcia, stany | Uzgodniony system magazynowy | Jeden autorytatywny rejestr ruchów dla danego magazynu |
| Receptury | Zatwierdzona kartoteka panelu albo Gastro | Wybrać jedno miejsce nadrzędne i wersjonować zmiany |
| Stan policzony przez managera | Pomiar w panelu | Data, czas, autor, lokal i jednostka |
| Zużycie teoretyczne | Sprzedaż × wersja receptury | Wyliczenie, a nie dodatkowy dokument magazynowy |
| Zamówienia | Panel | Wpływ na zapas dopiero po przyjęciu dostawy |

## 4 Integracja z KSeF

Należy wdrożyć serwerowy konektor do KSeF 2.0, korzystający z aktualnej dokumentacji MF, struktury faktury właściwej dla dokumentu i oddzielnych konfiguracji środowisk testowych oraz produkcyjnych. Oficjalny przewodnik zawiera procesy uwierzytelnienia, uprawnienia, pobieranie faktur oraz limity API. [Dokumentacja MF](https://github.com/CIRFMF/ksef-api/blob/main/README.md).

Wymagany przebieg:

1. Administrator przypisuje podmiot i NIP do lokali oraz nadaje integracji uprawnienia do odbioru faktur. Metoda uwierzytelniania ma być zgodna z aktualnym API; preferować certyfikat dla integracji serwerowej i przewidzieć jego wymianę.
2. Konektor pobiera dokumenty przyrostowo. Przechowuje punkt wznowienia dla podmiotu i środowiska, obsługuje limity, ponowienia oraz przerwanie importu. Nie opiera kompletności wyłącznie na dacie wystawienia faktury. [Przyrostowe pobieranie według MF](https://github.com/CIRFMF/ksef-api/blob/main/pobieranie-faktur/przyrostowe-pobieranie-faktur.md).
3. Zapisuje oryginalny XML, numer KSeF, numer faktury, typ, strony transakcji, daty, walutę, kwoty, pozycje i powiązania korekt. Powtórny import nie tworzy duplikatu. Numer KSeF jest podstawą identyfikacji dokumentu w kontekście podmiotu i środowiska.
4. Przypisuje fakturę do lokalu według zatwierdzonej reguły. Przy wspólnym NIP-ie nie zgaduje restauracji na podstawie samego nabywcy. Wykorzystuje dostępne oznaczenie odbiorcy, dokument magazynowy, zamówienie lub ręczny podział pozycji. Niejasne dokumenty trafiają do przypisania.
5. Mapuje pozycje dostawcy do wewnętrznych artykułów i przelicza jednostki. Zapamiętuje zatwierdzone mapowanie, obejmujące dostawcę, jego kod produktu oraz wariant opakowania. Sama podobna nazwa nie wystarcza.
6. Powiązuje fakturę z istniejącym przyjęciem magazynowym. Aktualizuje koszt, zachowując ślad źródłowy, bez ponownego zwiększenia stanu.

Data wystawienia, data otrzymania w KSeF, data sprzedaży i data fizycznej dostawy to odrębne pola. Jeśli brak potwierdzonej daty dostawy, wyświetlać brak danych; nie podstawiać automatycznie daty faktury.

Korekty ilości i ceny należy rozróżniać. Korekta ceny bez zwrotu towaru nie zmienia stanu. Rabaty zbiorcze, transport, kaucje i inne koszty wymagają uzgodnionej polityki rozdziału; nie należy przypisywać ich do surowców przypadkowo. Brak możliwości poprawnego wyliczenia ceny brutto pozycji powinien uruchamiać weryfikację, a nie przyjęcie stawki domyślnej.

Klucze prywatne i inne dane uwierzytelniające przechowywać po stronie serwera, poza kodem, przeglądarką i logami. Zapewnić uprawnienia minimalne, odnowienie dostępu, monitoring wygaśnięcia oraz rozdzielenie środowisk. [Uwierzytelnianie KSeF](https://github.com/CIRFMF/ksef-api/blob/main/uwierzytelnianie.md).

Zakres pierwszego wdrożenia obejmuje odbiór faktur zakupowych. Wystawianie faktur do KSeF nie jest wymaganiem tej aplikacji.

## 5 Integracja z naszym magazynem

Przed implementacją trzeba potwierdzić nazwę i wersję faktycznie używanego oprogramowania, topologię magazynu centralnego i lokali oraz dostępny sposób eksportu. W prototypie występują nazwy Gastro Centrala i Gastro Szef, ale nie potwierdzono technicznego dostępu do instalacji. Producent opisuje gospodarkę magazynową, receptury, inwentaryzację i synchronizację Gastro Szef z POS; nie określa to automatycznie interfejsu dostępnego dla naszej instalacji. [Gastro Szef](https://gastro.pl/gastro-szef/).

Preferowany jest interfejs wspierany przez dostawcę. Jeśli instalacja go nie udostępnia, uzgodnić eksport plikowy albo dedykowany dostęp tylko do odczytu. Nie zapisywać bezpośrednio do tabel systemu Gastro bez oficjalnego kontraktu integracyjnego.

Minimalny zakres odczytu:

- kartoteki surowców, towarów, półproduktów i gotowych dań, jednostki i opakowania;
- identyfikatory magazynów, lokali i dokumentów oraz daty i statusy;
- przyjęcia zewnętrzne, wydania, przesunięcia między magazynami, zwroty i korekty;
- inwentaryzacje i stany z dokładnym momentem, na który zostały policzone;
- ilości, wartości i ceny źródłowe, informacja netto lub brutto;
- dokumenty produkcji i rozchodu składników, jeżeli magazyn obsługuje produkcję gastronomiczną;
- powiązania z dostawcą, fakturą i zamówieniem, jeśli dostępne.

Przesunięcie z magazynu centralnego do restauracji powoduje jedno wydanie i jedno przyjęcie w odpowiednich magazynach. W sumie sieci nie jest kolejnym zakupem. Półprodukt wyprodukowany z surowców nie może jednocześnie zwiększać zapasu bez rozchodu składników.

**Ochrona przed podwójnym rozchodem:** jeżeli Gastro już rozchodowuje surowce na podstawie sprzedaży, panel nie może drugi raz odejmować tego samego zużycia od importowanego stanu. Do uzgodnienia jeden z modeli: import autorytatywnych stanów i ruchów Gastro albo własny bilans panelu. Teoretyczne zużycie recepturowe w obu modelach pozostaje osobną miarą kontrolną.

## 6 Integracja z Gastro POS

Programista powinien uzyskać od administratora lub serwisu Gastro dokumentację interfejsu dla zainstalowanej wersji, warunki licencyjne oraz przykładowy eksport. Nie zakładać istnienia publicznego REST API o samodzielnie wymyślonych adresach. Gastro POS i Gastro Szef są produktami powiązanymi, ale sposób udostępnienia danych panelowi wymaga uzgodnienia. [Informacja producenta o Gastro POS](https://gastro.pl/gastro-pos/).

Zakres danych do pobrania:

- lokale, stanowiska, identyfikatory kartotek, nazwy, kategorie, warianty i aktualne ceny;
- rachunki: stabilny identyfikator, lokal, czas, dzień operacyjny, status i wartość;
- pozycje: własny identyfikator, produkt, ilość, cena rzeczywista brutto, rabat, VAT i wartość po korektach;
- formy płatności z podziałem kwot, także przy rachunkach opłaconych na kilka sposobów;
- storna, anulowania, zwroty, zmiany zamkniętych rachunków i sprzedaż po ponownej synchronizacji;
- skład zestawów, dodatki i modyfikatory wpływające na recepturę, jeśli występują.

Klucz identyfikacyjny musi uwzględniać instalację i lokal, a w razie potrzeby także stanowisko. Sam numer rachunku może powtarzać się między kasami. Ponowna synchronizacja aktualizuje właściwy rekord, zamiast dopisywać drugą sprzedaż.

Aktualna cena w menu pochodzi z kartoteki. Cena historyczna pochodzi z konkretnej pozycji rachunku. Zmiana cennika nie może zmieniać raportu zeszłego miesiąca. Nazwa lub cena z publicznego menu internetowego może służyć jako pomoc przy uruchomieniu, ale nie zastępuje identyfikatora i transakcji POS.

Otwarte rachunki nie wchodzą do rozliczonej sprzedaży. Reguły anulowania pozycji należy rozdzielić od faktycznego zużycia kuchni: anulowane danie mogło zostać już przygotowane i wymagać osobnego odpisu.

## 7 Przeliczenia i kontrola strat

Wewnętrzne jednostki bazowe: gramy, mililitry i sztuki. Kartoteka musi rozróżniać jednostkę zakupu, zawartość opakowania oraz ilość na porcję. Opakowania różnych dostawców mogą mieć różną pojemność dla tego samego surowca.

Przykłady odbiorowe:

- Beczka 30 l zawiera 30 000 ml; porcja 500 ml daje teoretycznie 60 porcji przed uwzględnieniem strat.
- Butelka 700 ml przy porcji 40 ml daje 17,5 porcji teoretycznych, czyli 17 pełnych i 20 ml pozostałości. Nie zaokrąglać zapasu do 17 porcji i nie gubić pozostałości.
- Karton 24 butelek po 200 ml oznacza 24 sztuki albo 4800 ml, zależnie od uzgodnionej kartoteki. Przeliczenie musi zachować obie informacje.
- Krążki cebulowe 2,5 kg, porcja 500 g: pięć porcji. Sprzedaż sześciu porcji zużywa 3000 g, czyli 1,2 opakowania.

Faktura może dostarczyć ilość i cenę, ale nie zawsze zawartość opakowania ani gramaturę porcji. Brakujący przelicznik zatwierdza człowiek. Nie przeliczać ml na g bez ustalonej masy lub gęstości produktu.

Zużycie teoretyczne surowca to suma sprzedaży wszystkich dań używających tego surowca pomnożona przez ilość na porcję, z ewentualnym uzyskiem. Receptury muszą mieć wersje z datą obowiązywania; zmiana receptury dzisiaj nie może samoczynnie zmienić dawnych rozliczeń.

Bilans kontrolny:

`Stan oczekiwany = stan początkowy + przyjęcia + przesunięcia przychodzące − wydania niezwiązane ze sprzedażą − przesunięcia wychodzące − zużycie teoretyczne − zatwierdzone odpisy`

`Niedobór niewyjaśniony = stan oczekiwany − stan rzeczywiście policzony`

Wzór należy stosować wyłącznie bez podwójnego ujęcia ruchów opisanych w rozdziale o magazynie. Dodatni wynik to niedobór, ujemny nadwyżka. Bez pomiaru stanu końcowego można pokazać bilans teoretyczny, lecz nie potwierdzoną stratę. Aktualny uproszczony raport porównuje dostawy i zużycie; przed produkcją wymaga tego rozróżnienia.

Koszt porcji jest sumą kosztów jej składników. Obecny prototyp korzysta z ważonego kosztu dostępnych dostaw w okresie, ostatnich dostaw albo zatwierdzonej ceny kartotekowej. Docelowo uzgodnić z magazynem jedną metodę wyceny i odtwarzalność historii. Kwoty operacyjne brutto nie są automatycznie księgowym wynikiem restauracji.

Podpowiedź zakupowa może stosować:

`Opakowania do zakupu = max(0, zaokrąglenie w górę((zużycie dzienne × horyzont × (1 + bufor) − dostępny stan − potwierdzone dostawy w horyzoncie) / zawartość opakowania))`

Obecny kalkulator przewiduje horyzont siedmiu dni i bufor, ale nie pełną obsługę dostaw w drodze. Pracownik zatwierdza własną ilość w liście. Brak danych sprzedaży nie może być interpretowany jak potwierdzona zerowa sprzedaż. Dla lunchów uwzględnić dni faktycznego serwowania.

## 8 Model danych i synchronizacja

Docelowy model powinien obejmować podmioty prawne, lokale, magazyny, użytkowników, role, artykuły, opakowania, menu, wersje receptur, dostawców, faktury i pozycje, ruchy magazynowe, pomiary stanów, rachunki i pozycje POS, płatności, zamówienia, próby wysyłki oraz zadania synchronizacji.

Każdy importowany rekord przechowuje system źródłowy, zewnętrzny identyfikator, zakres podmiotu i lokalu, datę zdarzenia, datę importu, wersję lub znacznik zmiany i powiązanie z oryginałem. Osobna tabela mapowań łączy kody POS, magazynu i dostawców z wewnętrznymi artykułami. Nazwa jest opisem, nie kluczem.

Proponowany przepływ: konektor źródła → zapis surowych danych → walidacja i mapowanie → zapis znormalizowany → obliczenia → ekran. Nie przeliczać całej historii w przeglądarce przy każdym wejściu do modułu.

Proponowana częstotliwość do uzgodnienia z ograniczeniami dostawców: POS i magazyn co 5–15 minut, KSeF co 30–60 minut, dodatkowo uzgodnienie danych po zamknięciu dnia. To założenia projektowe, nie deklaracja możliwości obecnej instalacji. Konektory powinny obsługiwać ponowienia z opóźnieniem, limity, wznowienie i okresowe pobieranie spóźnionych korekt.

Administrator widzi ostatnią udaną synchronizację każdego źródła i lokalu, liczbę nieprzypisanych pozycji oraz błędy. Przy awarii zachować ostatnie dane z oznaczeniem ich aktualności. Nie zastępować ich zerami.

## 9 Uprawnienia i uruchomienie produkcyjne

Proponowane role: właściciel z dostępem do sieci, manager przypisanych lokali i pracownik z dostępem do listy zamówień. W obecnym kodzie występują role owner i manager; osobną rolę pracownika trzeba wdrożyć. Zakres odczytu i zapisu musi być egzekwowany na serwerze dla każdego dokumentu, surowca, receptury i pliku.

Produkcyjna autoryzacja nie może ufać nagłówkom użytkownika przesłanym bezpośrednio z internetu. Obecny serwer deweloperski symuluje właściciela, a API korzysta z nagłówków tożsamości. Przed wdrożeniem podłączyć zweryfikowaną sesję albo zaufaną bramę, usuwającą nagłówki klienta i wstawiającą własne. Usunąć stałe przypisanie właściciela do adresu w kodzie na rzecz konfiguracji i ról.

Rejestrować kto, kiedy i co zmienił, z poprzednią i nową wartością dla danych rozliczeniowych. Archiwizować użyte kartoteki zamiast je usuwać. Zapewnić kopie zapasowe, sprawdzoną procedurę odtworzenia oraz osobne środowiska testowe i produkcyjne. Dane i kontakty testowe nie mogą trafić do wysyłki ani raportów produkcyjnych.

## 10 Obecny kod i ograniczenia do uwzględnienia

Projekt przekazywany programiście znajduje się w katalogu `alladyn-panel`. Istotne elementy:

| Element | Pliki lub katalogi | Stan |
|---|---|---|
| Ekrany raportowe | `dist/app.js`, `dist/index.html` | Dane rachunkowe są generowane demonstracyjnie |
| Menu, zamówienia, receptury, FV | `dist/modules/loss-ui.js` | Interfejs i lokalne operacje działają |
| Obliczenia i walidacja | `dist/modules/loss-core.js` | Wymagają rozszerzenia o historię i pełne dane integracyjne |
| API i zapis | `server/loss-api.mjs`, `server/loss-store.mjs` | Rewizje, zapis i podstawowy audyt |
| Lokalna baza | `scripts/local-env.mjs`, `.local-data` | SQLite dla środowiska lokalnego |
| Struktura bazy | `drizzle` | Migracje; rekordy modułu przechowywane również jako JSON |
| Propozycje AI | `server/ai-menu.mjs` | Mechanizm przygotowany, usługa wymaga konfiguracji |
| Style | `dist/overview.css`, `dist/modules/loss.css`, `UI_GUIDELINES.md` | Utrzymać wspólny wygląd |
| Testy | `tests` | Testy logiki i części API; nie zastępują testów z prawdziwymi integracjami |

Pliki w `dist` są obecnie także plikami rozwijanymi bezpośrednio. Sprawdzić proces budowania przed zmianami, aby nie nadpisać źródeł. Serwer produkcyjny ma abstrakcje `DB` i `BUCKET`; docelowe środowisko wdrożenia i mechanizm uruchamiania zadań wymagają ustalenia.

Najważniejsze prace przed podłączeniem produkcji:

1. Zastąpić demonstracyjne rachunki w `app.js` jednym rzeczywistym źródłem raportów. Dzisiaj raporty sprzedaży i moduł magazynowy mają odrębne zestawy danych testowych.
2. Rozbudować model sprzedaży: obecny zapis `sale` przechowuje głównie danie, datę, ilość i referencję, bez pełnych pozycji rachunku, płatności i cen historycznych.
3. Zmienić przyjęcie faktury: obecna akcja `invoice` od razu tworzy ruch magazynowy. Przy równoległym imporcie PZ trzeba rozdzielić dokument finansowy od ruchu i powiązać je bez dublowania ilości.
4. Rozszerzyć schemat faktury o KSeF, NIP-y, VAT, walutę, korekty, dostawę i podział na lokale. Obecny prosty formularz nie pokrywa pełnej struktury dokumentu.
5. Dodać wersje receptur, moment pomiaru stanu i rozróżnienie ruchów. Obecna logika w znacznej części operuje datami dziennymi i bieżącą recepturą.
6. Wzmocnić autoryzację, filtrowanie danych między lokalami i audyt szczegółowy. Przetestować także próby użycia identyfikatora produktu lub dania z obcego lokalu.
7. Dodać trwałe zadania synchronizacji, statusy, idempotencję, kolejkę wysyłki i monitoring. Aktualne endpointy `/api/loss/state`, `/api/loss/action` oraz `/api/loss/ai-menu/*` nie są gotowymi konektorami zewnętrznymi.

W lokalnej bazie dodano 32 testowe dania z recepturami, 80 surowców, 48 faktur, 16 dostawców i 16 potwierdzonych zamówień testowych dla ośmiu lokali. Występują też wcześniejsze przykłady i importowane menu. To dane demonstracyjne, nie stan inwentaryzacji ani rzeczywiste receptury restauracji. Migracja produkcyjna wymaga jawnego oddzielenia tych rekordów, a nie kopiowania całej bazy.

## 11 Zasady interfejsu

Zachować istniejący jasny wygląd, granatową typografię, zielone akcje dodawania i zamawiania, czerwone usuwanie oraz czytelne kategorie. Tabele mają być zwarte i szerokie, liczby wyrównane, nagłówki i pola ustawione w jednym rzędzie, jeśli pozwala na to ekran. Kuchnia / Bar ma być duże i po prawej tam, gdzie zostało tak zaprojektowane.

Nie pokazywać technicznych identyfikatorów, zbędnych ustawień ani wyboru netto / brutto w codziennych formularzach. Ustawienia integracji, certyfikatów i mapowań mają osobny dostęp administracyjny. Zachować obsługę klawiatury, podpisy ikon i wyraźny fokus. Automatyczny zapis nie może ukrywać błędu ani nadpisywać zmian innego użytkownika bez komunikatu.

## 12 Kolejność wdrożenia i odbiór

1. Potwierdzić systemy, wersje, dostęp, NIP-y, lokale i mapowania. Przygotować środowisko testowe oraz próbki rzeczywistych dokumentów.
2. Podłączyć odczyt Gastro i magazynu dla jednego lokalu. Uzgodnić jeden pełny dzień sprzedaży oraz stan początkowy.
3. Podłączyć odbiór KSeF i dopasowanie faktur do przyjęć. Zweryfikować fakturę zwykłą, korektę ceny, korektę ilości i dokument wspólny dla lokali.
4. Uruchomić receptury, wersjonowanie, przeliczenia i bilans. Wykonać inwentaryzację kontrolną.
5. Podłączyć potwierdzanie i wysyłkę zamówień po wyborze usługi. Przetestować nieudaną i ponowioną wysyłkę.
6. Przeprowadzić pilotaż, uzgodnić raporty z systemami źródłowymi i rozszerzać integrację na kolejne lokale.

Warunki odbioru:

- Wszystkie osiem lokali ma prawidłowe powiązania i oddzielone dane.
- Raport brutto i płatności za uzgodniony dzień zgadzają się z Gastro, z wyjaśnieniem każdej różnicy.
- Ponowny import nie podwaja rachunków, pozycji, faktur, dostaw ani wysłanych zamówień.
- Ta sama dostawa z PZ i KSeF zwiększa stan tylko raz. Korekta ceny zmienia koszt, a nie ilość.
- Zmiana receptury lub aktualnego cennika nie przepisuje historii sprzedaży.
- Opakowania zbiorcze, beczki, butelki, porcje i wspólne składniki przechodzą uzgodnione przykłady kontrolne.
- Niedobór jest wyliczany z bilansem i pomiarem końcowym; brak danych nie jest zerem ani potwierdzoną stratą.
- Awaria i wznowienie synchronizacji nie gubią rekordów, a użytkownik widzi aktualność danych.
- Pracownik jednego lokalu nie odczytuje ani nie zmienia danych innego lokalu przez API.
- Potwierdzenie zamówienia jest odróżnione od jego wysłania. Powtórne kliknięcie nie tworzy drugiej wysyłki.
- Dane testowe są wyłączone z produkcji, a kopię zapasową można odtworzyć.

## 13 Informacje potrzebne przed rozpoczęciem integracji

Do zebrania przez programistę wspólnie z właścicielem i serwisem:

1. Lista podmiotów, NIP-ów i przypisanych restauracji; reguła dzielenia zakupów wspólnych.
2. Nazwa, wersja i administrator magazynu, Gastro POS, Gastro Szef lub Gastro Centrala; model lokalny albo centralny.
3. Dokumentacja dostępnego API lub eksportu, licencje, uprawnienia i kontakt do serwisu Gastro.
4. Identyfikatory lokali, kas i magazynów oraz przykładowe rachunki, PZ, wydania, przesunięcia i korekty.
5. Zakres historycznego importu i uzgodniony moment rozpoczęcia bilansu.
6. Nadrzędne miejsce utrzymania menu, cen, receptur i stanów; zasady rozstrzygania konfliktów.
7. Potwierdzone opakowania i gramatury oraz lista pozycji oznaczanych jako lunch.
8. Dostęp KSeF nadany bezpiecznym kanałem, osoba odpowiedzialna za jego utrzymanie i środowisko testowe.
9. Docelowy hosting, logowanie użytkowników, role, monitoring, kopie i zasady przechowywania dokumentów.
10. Skrzynka nadawcza, ewentualna bramka SMS i prawdziwe kontakty dostawców. Ten etap został odłożony przez właściciela.

Programista powinien oddać działające konektory, migracje i mapowania, konfigurację środowisk bez sekretów w repozytorium, raport uzgodnienia danych, testy odbiorowe oraz krótką instrukcję ponowienia importu, rozwiązania błędnego mapowania i odtworzenia bazy.