Lokalny Magazyn Surowców (LMS) — Dokumentacja Projektu v2.5.0

Aplikacja Lokalny Magazyn Surowców (LMS) to zaawansowany system desktopowy przeznaczony do zarządzania surowcami, śledzenia wagi opakowań, rejestracji operacji poboru/zużycia, pełnego audytu zdarzeń (Audit Log) oraz drukowania etykiet na drukarkach przemysłowych w języku ZPL II (Zebra Programming Language).

---

📐 1. Architektura Systemu

Aplikacja została zaprojektowana w oparciu o architekturę modułową (pakiet lms/), co zapewnia separację odpowiedzialności, ułatwia utrzymanie oraz pozwala na rozbudowę systemu.

Nowa Aplikacja/
├── magazyn_app.py          # Wrapper wejściowy (zgodny z PyInstaller .spec oraz run.sh)
├── lms/                    # Główny pakiet aplikacji
│   ├── __init__.py
│   ├── __main__.py         # Punkt startowy aplikacji (Init DB -> Auto-Backup -> Login -> Dashboard)
│   ├── config.py           # Ścieżki, stałe, RotatingFileHandler, Enums (PackageStatus, AuditAction)
│   ├── database.py         # Warstwa danych: SQLite z auto-commit/rollback, migracjami i log_audit
│   ├── helpers.py          # Funkcje pomocnicze: SHA-256, SQL IN helper, walidacja IP, EAN-13
│   ├── export.py           # Moduł eksportu do Excel (.xlsx) oraz CSV
│   ├── zpl_generator.py    # Generowanie kodu ZPL z podglądem historii ważeń i kodem EAN-13/Code128
│   └── ui/
│       ├── __init__.py
│       ├── styles.py       # Konfiguracja stylu i motywu ciemnego dla tabel Treeview
│       ├── dialogs.py      # Okna modalne: dodawanie surowca SAP, historia ważeń, Dziennik Audytu
│       ├── login.py        # Okno logowania i autoryzacji roli (Operator / Admin)
│       └── main_app.py     # Główny interfejs (Dashboard) z 4 zakładkami
├── szablon.zpl             # Domyślny szablon etykiety ZPL
├── ARCHITECTURE.md         # Dokumentacja techniczna architektury i plan refaktoryzacji
├── file_version_info.txt   # Metadane wersji pliku wykonywalnego Windows (.exe)
├── magazyn_app.spec        # Konfiguracja kompilacji PyInstaller
├── requirements.txt        # Zależności Python
├── run.bat                 # Skrypt uruchamiający dla systemu Windows
├── run.sh                  # Skrypt uruchamiający dla systemów Linux/macOS
└── .gitignore              # Reguły wykluczeń gita

---

🗄️ 2. Baza Danych i Schemat (SQLite)

Plik bazy danych lokalny_magazyn.db zarządza pięcioma tabelami:

erDiagram
    surowce ||--o{ operacje : "zawiera"
    operacje ||--o{ historia_wazenia : "rejestruje"
    
    surowce {
        int id PK
        string indeks_sap UK
        string nazwa
    }
    
    operacje {
        int id PK
        int surowiec_id FK
        real ilosc
        real waga_poczatkowa
        string data_otwarcia
        string operator
        string kod_opakowania UK
        string status
    }

    historia_wazenia {
        int id PK
        int operacja_id FK
        string data_wpisu
        real ilosc
        string operator
    }

    ustawienia {
        string klucz PK
        string wartosc
    }

    audit_log {
        int id PK
        string timestamp
        string operator
        string action
        string entity_type
        string entity_id
        string details
    }

Bezpieczeństwo i Transakcyjność Bazy Danych

• Automatyczny Commit/Rollback: Menedżer kontekstu get_db_connection() w database.py automatycznie wykonuje commit() po sukcesie oraz rollback() w przypadku wystąpienia błędu.
• Klucze Obce i Indeksy: Włączona obsługa PRAGMA foreign_keys = ON; z kaskadowym usuwaniem (ON DELETE CASCADE). Indeksy na polach indeks_sap, nazwa, status, data_otwarcia oraz audit_log(timestamp, action, operator).
• Automatyczne Kopie Zapasowe: Funkcja create_auto_backup() tworzy znacznikiem czasu kopie bazy danych w katalogu backups/ przy każdym starcie aplikacji oraz przed operacjami destrukcyjnymi, rotując najstarsze pliki (utrzymując max. 30 kopii).

---

🔒 3. Bezpieczeństwo, Audyt i Standaryzacja

1. Dziennik Audytu (Audit Log):
   • Każda operacja (tworzenie, ważenie, usuwanie z sesji/historii, logowanie, zmiana ustawień, importy, backupy) jest automatycznie rejestrowana w tabeli audit_log.
   • Dedykowany podgląd w Ustawieniach (AuditLogModal) umożliwia filtrowanie i eksport audytu do pliku Excel.
2. Uwierzytelnianie PIN Administratora:
   • PIN administratora jest bezpiecznie hashowany przy użyciu algorytmu SHA-256 (helpers.hash_pin()).
3. Ochrona przed SQL Injection:
   • Wszystkie zapytania wykorzystują parametryzowane instrukcje ?.
   • Zastosowano bezpieczny helper sql_in_clause() do budowania klauzul IN (?, ?, ...).
4. Logowanie z Rotacją Plików:
   • Użycie RotatingFileHandler ogranicza rozmiar pliku lms.log do max 5 MB z zachowaniem 3 ostatnich kopii.

---

💻 4. Kluczowe Funkcjonalności Aplikacji

Tab 1: Panel Operacyjny

• Nowe Opakowanie: Tworzenie wpisu nowego opakowania z automatycznym kodem ID EAN-13 lub zeskanowanym kodem dostawcy.
• Aktualizacja Wagi / Pobranie: Błyskawiczne odnajdywanie opakowania skanerem kodów kreskowych lub z listy rozwijanej oraz rejestracja pobranej wagi.
• Wymuszenie Statusu ZUŻYTE: Wprowadzenie 0 kg automatycznie przełącza status opakowania na ZUŻYTE.
• Bieżąca Sesja:
  • Zbiorczy wydruk etykiet zaznaczonych opakowań.
  • Eksport raportu sesji do Excela.
  • Usuwanie Rekordów w Sesji: Możliwość trwałego usunięcia wpisów z bazy danych (przycisk USUŃ ZAZNACZONE) lub kosmetycznego ukrycia z widoku sesji (menu pod prawym przyciskiem myszy).
• Druk ZPL: Szybki wydruk pojedynczego lub zbiorczego zestawu etykiet przez gniazdo TCP/IP (port 9100).

Tab 2: Słownik SAP

• Wyszukiwanie surowców wg indeksu SAP oraz nazwy.
• Pełny CRUD (Dodawanie, Edycja, Usuwanie) z kontrolą uprawnień dla Administratora.
• Import i Eksport bazy surowców do formatów .xlsx oraz .csv.

Tab 3: Historia i Otwarte Opakowania

• Filtrowanie opakowań według stanu (WSZYSTKIE, OTWARTE, ZUŻYTE) i zakresu dat oraz wyszukiwarka kodów/nazw.
• Podgląd Karty Ważeń: Pełna chronologiczna historia zmian wagi danego opakowania z podpisami operatorów (WeightHistoryModal).
• Oznaczanie ZUŻYTE oraz Usuwanie z Bazy (z potwierdzeniem i auto-backupem).
• Generowanie raportów szczegółowych i zbiorczych z podsumowaniem zapasów w Excelu.

Tab 4: Ustawienia

• Konfiguracja adresu IP drukarki etykiet ZPL.
• Zmiana PIN-u Administratora.
• Dziennik Zdarzeń (Audit Log): Przeglądarka zdarzeń z filtrami i eksportem Excel.
• Zarządzanie kopiami zapasowymi bazy danych (Ręczny Backup / Przywracanie z pliku).
• Edytor wizualny szablonu ZPL (szablon.zpl) z możliwością przywrócenia szablonu fabrycznego.

---

🏷️ 5. Szablon Etykiety ZPL (Szablon Nowy)

Etykieta jest generowana dynamicznie na podstawie szablonu ZPL (szablon.zpl). Szablon obsługuje następujące zmienne dynamiczne:

Zmienna	Opis
{data}	Data otwarcia opakowania (format: RRRR-MM-DD)
{3}	Aktualna pozostała waga w kg
{waga_poczatkowa}	Pierwotna waga opakowania
{nazwa}	Nazwa surowca SAP
{indeks}	Indeks SAP surowca
{kod}	Kod unikalny opakowania
{podpis}	Podpis/inicjały operatora
{tabela_zpl}	Wygenerowane wiersze ZPL reprezentujące ostatnie 3 wpisy wagi

Kod kreskowy generowany jest automatycznie jako EAN-13 (dla kodów 12/13 cyfrowych) lub Code 128 (dla kodów alfanumerycznych).

---

🛠️ 6. Instrukcja Uruchomienia i Kompilacji

Wymagania Środowiskowe

• Python 3.10+
• Wymagane pakiety: customtkinter, openpyxl, pyinstaller

1. Instalacja zależności

pip install -r requirements.txt

2. Uruchomienie lokalne

• Windows / Linux / macOS (Python):

  python magazyn_app.py
  # LUB bezpośrednio z pakietu:
  python -m lms
  

• Windows (skrypt wsadowy):

  run.bat
  

• Linux (skrypt bash):

  chmod +x run.sh
  ./run.sh
  

3. Kompilacja do pliku wykonywalnego (.exe)

Aplikacja wykorzystuje dedykowany plik specyfikacji magazyn_app.spec:

pyinstaller magazyn_app.spec --noconfirm

Wytworzony plik wykonywalny znajduje się w katalogu dist/magazyn_app.exe.

---

📜 7. Metadane Wersji

• Wersja oprogramowania: 2.5.0
• Licencja / Właściciel: Copyright (c) 2026 Kamil. All rights reserved.