OptimaConverterApp/README.md

🚀 Konwerter CSV do Optima XML

Cześć! 👋

To jest małe narzędzie backendowe (napisane w Javie), które konwertuje pliki CSV do formatu XML zgodnego z Comarch ERP Optima.

Twoim zadaniem będzie dorobienie do tego fajnego UI/UX, a to jest na razie sam "silnik", który możesz sobie uruchomić i testować.

🤓 Co jest potrzebne?

1. Java (JDK): Wersja 11 lub nowsza.
2. Maven (Zalecane): Projekt jest skonfigurowany przy użyciu Mavena. To najprostszy sposób, bo sam pobierze wszystkie potrzebne biblioteki (w tym opencsv do czytania CSV).
   • Aby sprawdzić, czy masz Mavena, wpisz w terminalu: mvn -version.

---

📂 Struktura Projektu

Struktura katalogów jest bardzo prosta:

.
├── input/                <-- TU WRZUCASZ PLIKI WEJŚCIOWE
│   ├── kontrahenci.csv
│   └── rejestr_sprzedazy.csv
├── output/               <-- TUTAJ POJAWI SIĘ WYNIKOWY XML
│   └── (na razie pusty)
├── src/main/java/        <-- CAŁY KOD ŹRÓDŁOWY JAVY
│   ├── CsvToOptimaXmlConverter.java  (główny plik z logiką)
│   └── ValidationException.java    (nasz specjalny plik do błędów)
└── pom.xml               <-- "Mózg" projektu (plik konfiguracyjny Mavena)

---

▶️ Jak to uruchomić (Sposób 1 - Zalecany: Maven)

To najłatwiejszy sposób. Będąc w głównym katalogu projektu (tam, gdzie jest plik pom.xml):

1. Kompilacja i pobranie bibliotek

mvn compile

Za pierwszym razem Maven połączy się z internetem i pobierze bibliotekę opencsv. Następnie skompiluje cały kod.

2. Uruchomienie programu

mvn exec:java

To polecenie uruchomi główną klasę. Jeśli wszystko pójdzie dobrze, w terminalu zobaczysz komunikat o sukcesie, a w katalogu output/ pojawi się plik optima_import.xml.

(Opcjonalnie) Czyszczenie projektu

mvn clean

Usuwa skompilowane pliki (katalog target), jeśli chcesz zacząć "na czysto".

---

▶️ Jak to uruchomić (Sposób 2 - Ręcznie, bez Mavena)

Jeśli nie masz lub nie chcesz instalować Mavena, możesz to zrobić "klasycznie".

1. Ręczne pobranie biblioteki

Musisz ręcznie pobrać plik .jar biblioteki opencsv.

• Wersja: 5.12.0 (lub nowsza)
• Pobierz z: Maven Central (kliknij jar obok "Downloads")
• Co zrobić: Pobrany plik opencsv-5.12.0.jar umieść w głównym katalogu projektu (obok pom.xml i input).

2. Ręczna kompilacja

Będąc w głównym katalogu, utwórz katalog na skompilowane klasy:

mkdir bin

Następnie skompiluj kod, wskazując bibliotekę i katalog docelowy:

javac -d bin -cp .:opencsv-5.12.0.jar src/main/java/*.java

3. Ręczne uruchomienie

Teraz uruchom program, wskazując w "classpath" zarówno bibliotekę, jak i katalog bin:

java -cp .:opencsv-5.12.0.jar:bin CsvToOptimaXmlConverter

(Uwaga: na Windowsie zamiast : użyj ; jako separatora w classpath)

---

🚦 Ważne informacje

Separator CSV

Program jest obecnie ustawiony na domyślny separator CSV, czyli przecinek (,). Wszystkie pliki .csv w katalogu input/ muszą używać przecinków, aby zostały poprawnie wczytane.

Walidacja ("Test Pani Marisi")

Program nie jest "głupi". Zanim zacznie konwersję, sprawdza pliki CSV:

• Weryfikuje, czy wszystkie obowiązkowe kolumny (np. AKRONIM u kontrahenta, POZ_NETTO na fakturze) są wypełnione.
• Jeśli czegoś brakuje, program zatrzyma się i wyświetli w terminalu bardzo czytelny, "ludzki" komunikat o błędzie (np. Błąd w danych (w fakturze o numerze 'FV/2/2024')! Brakuje wartości w kolumnie: 'POZ_NETTO'.).

Dzięki temu od razu wiesz, co i gdzie poprawić w pliku CSV.

---

🗒️ TODO (Co dalej?)

Lista zadań do zrobienia, aby ten projekt był jeszcze lepszy:

• Zbudować graficzny interfejs (UI), który będzie zawierał:

  • Przycisk do wyboru pliku kontrahenci.csv.
  • Przycisk do wyboru pliku rejestr_sprzedazy.csv.
  • Przycisk "Start", który uruchamia konwersję.
  • Czytelny komunikat (labelka, okienko pop-up) informujący o sukcesie lub wyświetlający błąd walidacji.

• Rozbudować walidację danych wejściowych (zgodnie z dokumentacją Comarch):

  • Walidacja typów danych (np. czy POZ_NETTO jest liczbą, a DATA_WYSTAWIENIA poprawną datą).
  • Walidacja długości pól (np. czy AKRONIM nie przekracza 20 znaków).
  • Walidacja logiki biznesowej (np. sprawdzenie, czy w rejestrze sprzedaży POZ_NETTO * (POZ_STAWKA_VAT / 100) faktycznie równa się POZ_VAT, z uwzględnieniem zaokrągleń).

Powodzenia! Daj znać, jakbyś miała jakieś problemy.