Dokumentacja Systemu Numerowania Dokumentów

1. Przegląd Systemu

1.1 Cel

System numerowania dokumentów zapewnia unikalną, chronologiczną i kontekstową identyfikację wszystkich dokumentów generowanych w aplikacji, z pełną obsługą pracy offline.

1.2 Główne Założenia

• Unikalne numery dokumentów w skali całego systemu
• Możliwość pracy offline bez utraty funkcjonalności
• Czytelny format zawierający kontekst biznesowy
• Automatyczna synchronizacja po powrocie online
• Zachowanie historii wersji dokumentów

2. Format Numeru Dokumentu

2.1 Struktura Podstawowa

[TYP_NIERUCHOMOŚCI]/[ROK]/[MIESIĄC]/[NUMER]/[WERSJA]

2.2 Komponenty

Typ Nieruchomości (3 znaki)

• BIU - Biuro
• MAG - Magazyn
• HAN - Handel/Usługi
• MIE - Mieszkanie

Rok (4 cyfry)

• Format: YYYY (np. 2025)

Miesiąc (2 cyfry)

• Format: MM (01-12)
• Zawsze z wiodącym zerem

Numer Sekwencyjny (4-10 znaków)

• Online: 4 cyfry (0001-9999)
• Offline: ID urządzenia + licznik lokalny (np. A3F2-00001)

Wersja

• Format: v[numer] (v1, v2, v3...)
• Opcjonalnie: -draft dla wersji roboczych

2.3 Przykłady

• Dokument online: BIU/2025/01/0142/v1
• Dokument offline: BIU/2025/01/A3F2-00001/v1
• Wersja robocza: MAG/2025/01/0143/v1-draft

3. Architektura Rozwiązania

3.1 Komponenty Systemu

Frontend (Przeglądarka)

• Generowanie numerów lokalnych
• Zarządzanie pulą numerów
• Przechowywanie w localStorage
• Kolejkowanie dokumentów do synchronizacji

Backend (Serwer)

• Centralny rejestr numerów
• Rezerwacja pul numerów
• Walidacja i deduplikacja
• Mapowanie numerów tymczasowych na docelowe

Synchronizacja

• Automatyczna przy powrocie online
• Ręczna na żądanie użytkownika
• Rozwiązywanie konfliktów

3.2 Przepływ Danych

Scenariusz Online

1. Użytkownik tworzy nowy dokument
2. System pobiera numer z zarezerwowanej puli
3. Dokument otrzymuje numer docelowy od razu
4. Potwierdzenie użycia numeru do backendu

Scenariusz Offline

1. Użytkownik tworzy dokument bez internetu
2. System generuje numer tymczasowy z ID urządzenia
3. Dokument zapisany lokalnie z numerem tymczasowym
4. Po powrocie online - synchronizacja i przypisanie numeru docelowego

4. Zarządzanie Pulą Numerów

4.1 Rezerwacja Puli

• Automatyczna rezerwacja 20 numerów przy starcie
• Dodatkowa rezerwacja gdy pozostało mniej niż 5 numerów
• Osobne pule dla każdego typu nieruchomości

4.2 Struktura Puli

• Lista zarezerwowanych numerów
• Data rezerwacji
• Data wygaśnięcia (24h)
• Status wykorzystania

4.3 Optymalizacja

• Przewidywanie zapotrzebowania na podstawie historii
• Dynamiczne dostosowanie wielkości puli
• Recykling niewykorzystanych numerów

5. Praca Offline

5.1 Identyfikator Urządzenia

• Generowany przy pierwszym użyciu
• 4 znaki alfanumeryczne
• Przechowywany w localStorage
• Unikalny per przeglądarka/urządzenie

5.2 Licznik Lokalny

• Osobny dla każdego typu dokumentu
• Resetowany po synchronizacji
• Maksymalnie 99999 dokumentów offline (5 cyfr)

5.3 Kolejka Synchronizacji

• Lista dokumentów oczekujących
• Priorytetyzacja wg daty utworzenia
• Retry w przypadku błędów

5.4 Obsługa Błędów Offline

• Komunikaty o błędach zapisywane w localStorage
• Automatyczne retry przy błędach sieciowych
• Powiadomienie użytkownika o problemach z zapisem
• Możliwość ręcznego ponowienia synchronizacji

6. Synchronizacja

6.1 Proces Synchronizacji

1. Wykrycie połączenia internetowego
2. Pobranie listy dokumentów do synchronizacji
3. Wysłanie dokumentów do backendu
4. Otrzymanie numerów docelowych
5. Aktualizacja numerów lokalnie
6. Potwierdzenie synchronizacji

6.2 Rozwiązywanie Konfliktów

• Priorytet: pierwszy zsynchronizowany
• Zachowanie historii numerów
• Powiadomienie użytkownika o zmianach

6.3 Mapowanie Numerów

• Tablica przekładająca numery tymczasowe na docelowe
• Aktualizacja wszystkich referencji
• Zachowanie spójności w systemie

7. Wersjonowanie Dokumentów

7.1 Tworzenie Wersji

• Każda edycja = nowa wersja
• Zachowanie oryginalnego numeru
• Tylko inkrementacja wersji

7.2 Historia Wersji

• Lista wszystkich wersji dokumentu
• Data i autor każdej zmiany
• Możliwość porównania wersji

8. Bezpieczeństwo i Integralność

8.1 Zabezpieczenia

• Walidacja formatu numerów
• Zapobieganie duplikatom
• Limity per użytkownik/urządzenie
• Audit log wszystkich operacji

8.2 Backup i Odzyskiwanie

• Regularne kopie rejestru numerów na serwerze
• Możliwość odtworzenia stanu w przypadku awarii
• Procedury awaryjne dla krytycznych błędów

9. Interfejs Użytkownika

9.1 Wyświetlanie Numeru

• Widoczny w prawym górnym rogu dokumentu
• Format skrócony w listach
• Pełny numer w szczegółach

9.2 Komunikaty

• Status synchronizacji
• Informacja o pracy offline
• Powiadomienia o zmianach numerów

10. Monitorowanie i Raportowanie

10.1 Metryki

• Liczba dokumentów per typ/miesiąc
• Wykorzystanie pul numerów
• Czas synchronizacji
• Błędy i konflikty

10.2 Raporty

• Miesięczne podsumowania
• Analiza trendów
• Wydajność systemu

11. Przyszłe Rozszerzenia

11.1 Możliwe Ulepszenia

• QR kody z numerami dokumentów
• Integracja z systemami zewnętrznymi
• Personalizacja formatów per klient
• Wsparcie dla wielu lokalizacji

11.2 Skalowalność

• Obsługa ponad 10,000 dokumentów/miesiąc
• Wielopoziomowa hierarchia numerów
• Rozproszone generowanie numerów