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.