ImportDokMag/README.md

ImportDokMag

Aplikacja Windows (WinForms, VB.NET) firmy myCONSULT dla Gotec. Przenosi zapisy księgowe dokumentów magazynowych z bazy Comarch ERP XL w Jastrzębiu (baza źródłowa) do bazy ERP XL Gotec (baza docelowa) jako noty memoriałowe uproszczone.

• Odczyt z bazy źródłowej: bezpośrednio przez SQL (procedury CDN.my_ImpDM_*).
• Zapis do bazy docelowej: przez XL-API 2025.1 (cdn_api20251.net.dll).

Wymagania

Składnik	Wersja / uwagi
.NET Framework	4.8
Comarch ERP XL (stanowisko z importem)	2025.1 lub nowszy, z zainstalowanym cdn_api20251.net.dll
Platforma	x86, bo biblioteka XL-API jest 32-bitowa
Visual Studio	2026 (projekt .vbproj w starym formacie, pakiet NuGet Microsoft.Data.SqlClient 7.1.1)
Instalator	rozszerzenie Microsoft Visual Studio Installer Projects (Instalator.vdproj)

Projekt odwołuje się do biblioteki API ze ścieżki C:\xl\comarch xl\cdn_api20251.net.dll. Jeśli XL jest zainstalowany gdzie indziej, popraw HintPath w ImportDokMag/ImportDokMag.vbproj.

Struktura repozytorium

ImportDokMag.sln
ImportDokMag/
  MainFrm.vb          okno główne: lista dokumentów, filtry, import, oznaczanie flagą
  ImportDM.vb         budowa not i dekretów (część klasy MainFrm)
  FunkcjeXL.vb        wrapper na XL-API: logowanie, licencja, noty, dekrety, opisy błędów
  dlgKonfig.vb        okno konfiguracji (serwery, bazy, seria, katalog logów)
  DsMain.xsd          DataSet z TableAdapterami na procedury CDN.my_ImpDM_*
Instalator/           projekt instalatora MSI
*.sql                 skrypty procedur w bazie źródłowej (patrz niżej)
GenerowanieOpisuNoty.docx   opis zasad budowania treści noty

Poza repozytorium (w .gitignore): Publikuj/ (wyniki publikacji ClickOnce), bin/, obj/, .svn/.

Obiekty SQL w bazie źródłowej

Procedury trzeba założyć w bazie źródłowej (Jastrzębie), w schemacie CDN:

Procedura	Skrypt	Do czego służy
CDN.my_ImpDM_Src	CDN.my_ImpDM_Src_20210729.sql (aktualny)	lista dokumentów i dekretów do importu: filtry sprzedaż / zakup / wewnętrzne, rok, miesiąc, konto, status importu
CDN.my_ImpDM_Dekr	DokumentyZrodlowe-DekretySkladowe.sql	pozycje (dekrety składowe) wybranego zapisu, z których powstają pozycje noty
CDN.my_ImpDM_Konta	Konta.sql	lista kont z danego okresu do filtra „Konto”

DokumentyZrodlowe.sql i DokumentyZrodlowe_old.sql to starsze wersje my_ImpDM_Src.

Jak działa import

1. Program łączy się z bazą źródłową i pokazuje zapisy z wybranego roku i miesiąca. Zaimportowane wiersze są czerwone.
2. Po kliknięciu Importuj loguje się do bazy docelowej przez XL-API: XLLogin w trybie wsadowym, potem XLSprawdzLicencje i XLPolaczenie.
3. Dla każdego zaznaczonego dokumentu:
   • XLDodajNote zakłada notę uproszczoną (GIDTyp 4145) w serii z konfiguracji;
   • XLDodajPozycjeNoty dodaje pozycje z my_ImpDM_Dekr, a numery kont (KKS_GIDNumer) ustala SQL-em z CDN.Konta bazy docelowej;
   • XLZamknijNote zamyka notę. Jeśli pozycja się nie dodała, nota jest kasowana (XLKasujNote).
4. Po udanym imporcie:
   • w bazie źródłowej ustawia CDN.Dekrety.DT_DataCentrali, czyli flagę „zaimportowano”;
   • w bazie docelowej zapisuje magazyn do CDN.MemNag.MEN_CechaOpis.
5. Skasuj flagę importu zeruje DT_DataCentrali, żeby dokument dało się zaimportować ponownie. Utworzonej noty w bazie docelowej nie usuwa.

Przebieg pracy widać na zakładce „Przebieg pracy”. Jest też zapisywany do pliku ImportDM-<data_godzina>.LOG w katalogu roboczym.

Konfiguracja

Ustawienia wprowadza się w oknie Konfiguracja. Zapisują się w user.config użytkownika Windows i po zmianie trzeba uruchomić program ponownie.

Pole	Ustawienie	Znaczenie
Serwer SQL, baza danych, użytkownik, hasło	SerwerSrc, BazaSrc, MCsrc, Comsrc	połączenie z bazą źródłową. Użytkownik i hasło są przechowywane w zaciemnionej postaci (to nie jest szyfrowanie).
Baza docelowa	BazaDst	baza ERP XL do logowania przez XL-API. Prefiks CDNXL_ lub ERPXL_ jest obcinany, bo XLLogin oczekuje nazwy z Managera baz.
Serwer klucza	SerwerKlucza	serwer licencji ERP XL
Seria noty	Seria	seria not memoriałowych
Katalog roboczy	FolderR_Roboczy	katalog plików .LOG

Konfiguracja jest przypisana do komputera i użytkownika. Po uruchomieniu na innym koncie program zgłasza „Niezgodna konfiguracja” i czyści ustawienia.

Z bazą źródłową program łączy się zawsze przez uwierzytelnianie SQL (User ID / Password, MainFrm.zrob_polaczenie) z danymi z okna konfiguracji. Tego wymaga środowisko klienta. Connection string CS_Src w App.config (uwierzytelnianie Windows) służy tylko projektantowi DataSetu w Visual Studio. Program go nie używa i nie trzeba go zmieniać u klienta.

Kompilacja i publikacja

• Kompilacja: konfiguracja x86 (Debug|x86 lub Release|x86).
• Publikacja ClickOnce: do katalogu Publikuj\. Przed publikacją podnieś ApplicationVersion we właściwościach projektu.
• Instalator MSI: projekt Instalator. Dołącza cdn_api20251.net.dll jako zależność.

Zmiana wersji XL-API

Wersja API jest zapisana w czterech miejscach i trzeba zmienić wszystkie naraz:

1. FunkcjeXL.vb: stała API_VERSION;
2. FunkcjeXL.vb, ImportDM.vb: sufiksy struktur cdn_api.XL…Info_<wersja>;
3. ImportDokMag.vbproj: referencja i HintPath do cdn_api<wersja>.net.dll;
4. Instalator.vdproj: zależność cdn_api<wersja>.net.

Dokumentacja XL-API (2025.1, Markdown) jest w osobnym folderze XLAPI, dołączonym w ImportDokMag.code-workspace. Kwoty przekazywane do XL-API zawsze mają kropkę jako separator dziesiętny.