KCClose Remote

1. Cel i zakres

KCClose Remote umożliwia operatorowi odczyt bieżącej daty zamknięcia okresu oraz zapis nowej daty z telefonu lub tabletu z Androidem. Aplikacja komunikuje się z usługą REST udostępnianą przez program KCClose.

2. Wymagania

3. Instalacja i pierwsze uruchomienie

1. Zainstaluj podpisany plik APK z zaufanego źródła.
2. Jeśli system blokuje instalację, zezwól wskazanej aplikacji na instalowanie nieznanych aplikacji.
3. Uruchom KCClose Remote.
4. Przy braku konfiguracji aplikacja wyświetli informację o braku serwerów.
5. Dodaj pierwszy serwer zgodnie z rozdziałem 4.

4. Konfiguracja serwera

4.1 Dodanie serwera

1. Otwórz kartę zarządzania serwerami.
2. Wprowadź nazwę rozpoznawalną dla operatora.
3. Podaj adres IP, nazwę hosta albo pełny adres z prefiksem http:// lub https://.
4. Wprowadź port od 1 do 65535.
5. Wpisz hasło API identyczne jak w konfiguracji REST KCClose. Minimalna długość w aplikacji wynosi 12 znaków.
6. Wybierz „Dodaj serwer” lub zapisz edytowany wpis.

4.2 Edycja i usuwanie

Wybierz wpis z listy, aby przełączyć aktywny serwer. Funkcja edycji aktualizuje istniejący wpis. Usunięcie wymaga potwierdzenia i nie zmienia konfiguracji programu KCClose.

5. Codzienna obsługa

5.1 Odczyt statusu

1. Wybierz właściwy serwer.
2. Użyj funkcji odświeżenia statusu.
3. Sprawdź nazwę serwera, datę zamknięcia i liczbę dni wstecz.

Aplikacja wykonuje GET /getstatus. Odpowiedź poprawna aktualizuje kartę statusu i pole daty.

5.2 Zmiana daty

1. Dotknij pola daty i wybierz dzień w kalendarzu.
2. Sprawdź format RRRR-MM-DD.
3. Wybierz „Zapisz datę na serwerze”.
4. Po sukcesie aplikacja ponownie pobierze status.

6. Komunikaty błędów i diagnostyka

6.1 Zalecana kolejność diagnostyki

1. Potwierdź, że KCClose jest uruchomiony.
2. Sprawdź połączenie KCClose z bazą.
3. Porównaj adres, port i hasło w obu programach.
4. Zweryfikuj dostępność portu z tej samej sieci lub VPN.
5. Sprawdź kod HTTP w aplikacji i log KCClose.

7. Bezpieczeństwo i przechowywanie danych

Każde wywołanie REST zawiera hasło w nagłówku X-Auth-Token. Hasło jest przypisane do konkretnego wpisu serwera. Po stronie KCClose konfigurację chroni Windows DPAPI. Po stronie Androida lista serwerów jest serializowana do pliku servers.dat w prywatnym katalogu aplikacji File.DirInternal.

7.1 Zalecenia

• Używaj unikalnego, losowego hasła dłuższego niż wymagane minimum.
• Nie instaluj aplikacji na urządzeniach współdzielonych, zrootowanych lub bez blokady ekranu.
• Udostępniaj port REST wyłącznie w zaufanej sieci LAN albo przez VPN.
• Nie wystawiaj serwera REST bezpośrednio do Internetu.
• Przy HTTP token nie jest szyfrowany transportowo; preferuj sieć izolowaną lub VPN.
• Po utracie telefonu natychmiast zmień hasło REST w KCClose.

8. Architektura i przepływ danych

8.1 Przepływ odczytu

8.2 Przepływ zapisu

8.3 Model lokalnej konfiguracji

9. Kontrakt REST API

9.1 Odczyt statusu

GET /getstatus   Nagłówek: X-Auth-Token: <hasło>

{
  "ok": true,
  "dataZamkniecia": "2026-08-16",
  "dniWstecz": 3
}

9.2 Ustawienie daty

PUT /setdate   Nagłówki: X-Auth-Token oraz Content-Type: application/json; charset=utf-8. Limit treści: 4096 bajtów.

{
  "data": "2026-08-16"
}

{
  "ok": true,
  "message": "Data końca zamkniętego okresu została ustawiona na 2026-08-16."
}

9.3 Format błędu

{
  "ok": false,
  "error": "unauthorized",
  "message": "Brak lub nieprawidłowe hasło w nagłówku X-Auth-Token."
}

Klient interpretuje kod HTTP i pole error. Pole message służy jako szczegół techniczny; operator otrzymuje uproszczony komunikat po polsku.

10. Budowa i wydanie aplikacji

10.1 Wymagane środowisko

10.2 Biblioteki B4A

B4XCollections, Core, OkHttpUtils2, RandomAccessFile, XUI Views, AppCompat oraz JSON.

10.3 Konfiguracja ścieżki SDK

W B4A wybierz Tools > Configure Paths i wskaż C:\Android\platforms\android-35\android.jar. Użycie android-34 powoduje błąd linkera dotyczący android:attr/windowOptOutEdgeToEdgeEnforcement, ponieważ atrybut jest dostępny od API 35.

10.4 Procedura wydania

1. Zaktualizuj VersionCode i VersionName.
2. Wykonaj Clean Project i kompilację Release.
3. Podpisz APK właściwym kluczem i zabezpiecz jego kopię.
4. Zainstaluj wydanie na czystym urządzeniu testowym.
5. Wykonaj checklistę z rozdziału 11.
6. Archiwizuj APK, kod źródłowy, numer wersji i datę wydania.

11. Testy odbiorcze i utrzymanie

11.1 Minimalna checklista wydania

• Pierwsze uruchomienie bez servers.dat pokazuje informację o braku serwerów.
• Walidacja odrzuca puste pola, port poza zakresem i hasło krótsze niż 12 znaków.
• Dodany serwer pozostaje po ponownym uruchomieniu.
• Edycja zmienia wpis, a usunięcie wymaga potwierdzenia.
• GET /getstatus pokazuje datę i dni wstecz.
• PUT /setdate wysyła JSON, zapisuje datę i odświeża status.
• Błędne hasło wyświetla 401 bez ujawnienia tokenu.
• Brak sieci, wyłączony KCClose i blokada portu dają czytelną diagnostykę.
• Brak połączenia KCClose z bazą poprawnie obsługuje 503.
• Nieprawidłowa data poprawnie obsługuje 400 invalid_date.
• Interfejs jest czytelny w pionie na urządzeniu docelowym.

11.2 Mapa najważniejszych procedur

12. Historia zmian i słownik

12.1 Wersja 2.0

• Usunięto hasło zaszyte na stałe w kodzie.
• Dodano hasło API w konfiguracji każdego serwera.
• Zmieniono zapis daty z GET na PUT z treścią JSON.
• Dodano obsługę odpowiedzi JSON i kodów błędów API.
• Dodano edycję serwerów oraz walidację portu i hasła.
• Przebudowano interfejs na ciemny układ kartowy.
• Zastąpiono starszy DateDialog kalendarzem B4XDateTemplate.
• Podniesiono targetSdkVersion do 35.

12.2 Słownik

12.3 Źródła dokumentacji

Dokument opracowano na podstawie kodu źródłowego KCClose_Remote.b4a (wersja aplikacji 2.0), modułu Starter.bas oraz implementacji REST w module UMain.pas programu KCClose. Stan na 16 sierpnia 2026.