Architektura modułu Dozór celny i włączenie go w bazie - dla wdrożeniowców

Strona opisuje, z czego składa się moduł Dozór celny po stronie serwera i bazy oraz jak go włączyć na wskazanej bazie. Moduł jest ewidencją magazynową: nie składa zgłoszeń celnych i nie jest certyfikowanym modułem celnym. Schemat bazy wgrywa się na każdą bazę z wyłączonym modułem, a menu i dane demonstracyjne tylko na bazie demo. Opis funkcjonalny ekranów zaczyna się od sekcji DOZÓR CELNY.

Warstwy modułu

Przeglądarka ładuje jeden z trzech skryptów JavaScript przypisanych do transakcji JQS21. Skrypt rysuje ekran i wysyła zapytania do serwera pod identyfikatorami z rodziny zapytań modułu. Serwer podstawia zmienne zastrzeżone (magazyn, oddział, login zalogowanego użytkownika) i wywołuje procedurę w bazie. Cała logika zmieniająca dane leży w procedurach, a skrypt ekranu tylko wyświetla wynik.

Odczyty idą sterownikiem ssDataSQL: procedura zwraca zbiór wierszy i może mieć własną transakcję. Zapisy idą sterownikiem ssExSQL, w którym serwer owija wywołanie we własną transakcję. Procedury akcji zwracają jeden wiersz z polami OK i KOMUNIKAT, a dwie procedury rzucają wyjątek zamiast zwracać wiersz: zapis PZC i kontrola wydania WZC. Rzucony wyjątek cofa transakcję zatwierdzenia dokumentu magazynowego, w której procedura została wywołana.

Moduł nie ma własnych tabel ruchów magazynowych. Przyjęcie i wydanie zapisują zwykłe wiersze ruchów magazynowych, a tabele modułu przechowują tylko status celny partii z historią zmian oraz dokumenty celne z kolejką komunikatów. Opis tabel znajduje się na stronie model danych i znaczniki.

Trzy transakcje JQS21

Transakcje leżą w skorowidzu (PRX równe JQS21). Każda ma kod otwierający ekran i własny UNIQUEID, a pole KOD1 nadaje jej nazwę techniczną. Adres skryptu jest zapisany w polu IKONA wraz ze znacznikiem wersji.

Pozycje menu z sekcji DOZÓR CELNY otwierają wszystkie tę samą transakcję CE1A-47D2-9B30. O tym, który z ośmiu widoków zobaczy użytkownik, decyduje parametr adresu ekran w polu TARGETPARAMETERS wiersza menu. Skrypt czyta ten parametr przy starcie (funkcja MojaOnLoad) i dla wartości spoza listy otwiera kokpit.

Transakcje PZC i WZC dostają w adresie typ dokumentu: prx=PZ&typdok=PZC oraz prx=WZ&typdok=WZC&refno=0. Parametr refno z wartością 0 otwiera nowy dokument, a refno z numerem referencyjnym wczytuje bufor do edycji.

Wiersze menu

Wiersze menu powstają w skrypcie demonstracyjnym przez sklonowanie działających pozycji roli Magazyn. Klonuje się jeden wzorcowy wiersz sekcji (PRX równe MBR) i jeden wzorcowy wiersz paska (PRX równe BAR), a w nich podmienia się teksty widoczne w menu i kolejność pozycji, a także parametry adresu. Dzięki temu nowe pozycje dziedziczą pozostałe kolumny techniczne z pozycji, które w tej bazie już działają.

Wiersz sekcji ma KOLEJNOSC 12, więc sekcja stoi między MAGAZYN a KARTOTEKI. Wiersze paska mają TARGETURL równy role_sys/jqs21.aspx, a w TARGETPARAMETERS wartości w postaci kod=CE1A-47D2-9B30&uid=...&ekran=kokpit. Każdy wiersz menu ma UNIQUEID z rodziny D4F2B8E6-3C59-4A7B-8D21-9F6E8C4ADExx, gdzie xx przyjmuje wartości od 01 do 11. Po tej rodzinie parametr MODUL_CELNY rozpoznaje wiersze do włączenia i wyłączenia.

SELECT PRX, GRUPA, NAME, KOLEJNOSC, AKTYWNE, TARGETPARAMETERS
FROM dbo._menu
WHERE UNIQUEID LIKE 'D4F2B8E6-3C59-4A7B-8D21-9F6E8C4ADE%'
ORDER BY GRUPA, KOLEJNOSC;

Parametry modułu

Trzy parametry leżą w tabeli parametrów, w grupie WMS, z rolą SuperVisor. Skrypt schematu dodaje je tylko wtedy, gdy parametru o danym kodzie jeszcze nie ma, więc ponowne wgranie nie zmienia wartości ustawionych przez administratora.

Parametry zapisuje procedura wołana z ekranu Ustawienia modułu pod zapytaniem 30 z rodziny C3E1A7D5-2B48-4F6A-9C10-8E5D7B3FCExx. Przy MODUL_CELNY procedura dodatkowo ustawia AKTYWNE na 1 albo 0 we wszystkich wierszach menu z rodziny D4F2B8E6-3C59-4A7B-8D21-9F6E8C4ADExx. Dlatego ręczna zmiana samej wartości parametru w bazie nie ukryje menu: trzeba zmienić też wiersze menu albo użyć ekranu ustawień. Komunikaty zwrotne to Moduł włączony i Moduł wyłączony wraz z informacją, że menu odświeży się po ponownym zalogowaniu. Błędy walidacji mają kody 50061-50064.

SELECT KOD, WARTOSC, AKTYWNE, GRUPA, ROLA
FROM dbo._parametry
WHERE KOD IN ('MODUL_CELNY', 'CEL_TOLERANCJA', 'CEL_PROG_DNI');

Skorowidze

Moduł używa trzech rodzajów wpisów w skorowidzu, rozróżnianych kolumną PRX.

• CPR - słownik kodów procedur celnych (71, 40, 42, 51, 53) w roli WMS; ekran Dodaj dokument i ekran Ustawienia modułu czytają go przez procedurę słownika.
• MAG - lista magazynów roli WMS; moduł tylko czyta ją, aby pokazać nazwy magazynów i przypisać im typ oraz limit dni.
• JQS21 - trzy transakcje z poprzedniej sekcji.
• Zmiana słownika CPR - skrypt dodaje tylko brakujące kody, więc kod dopisany ręcznie przez wdrożeniowca zostaje.

SELECT PRX, KOD, KOD1, OPIS, IKONA, AKTYWNE
FROM dbo.x_skorowidze
WHERE (PRX = 'JQS21' AND KOD IN ('CE1A-47D2-9B30', 'CE2B-58E3-AC41', 'CE3C-69F4-BD52'))
   OR (PRX = 'CPR' AND ROLASYS = 'WMS')
ORDER BY PRX, KOD;

Kolejność skryptów dbup

Skrypty leżą w katalogu skryptów aktualizacji bazy i są idempotentne: tabele powstają tylko wtedy, gdy ich nie ma; procedury używają CREATE OR ALTER; zapytania i transakcje są aktualizowane po UID. Drugie uruchomienie któregokolwiek skryptu nie zmienia danych.

Skrypt 1410 sprawdza dwa warunki wstępne: nazwę bazy i obecność schematu z poprzedniego skryptu. Gdy któryś nie jest spełniony, kończy pracę bez zmian i wypisuje komunikat PRINT. Dane demonstracyjne wstawia tylko wtedy, gdy w dokumentach celnych nie ma jeszcze numeru zawierającego fragment DEMO. Bramkę można zdjąć świadomie przez zmianę zmiennej @tylkoDemo, ale moduł nie jest jeszcze produktem wdrożonym u klientów, więc taką zmianę uzgadnia się osobno.

Dwa forki zapisu skrypt 1400 buduje z bieżącej treści zapytań źródłowych na danej bazie: zatwierdzenia PZB i PW dla PZC oraz zatwierdzenia WZ dla WZC. Jeśli zapytania źródłowego brakuje, fork zostaje pominięty, a skrypt wypisuje komunikat PRINT. Dla wdrożeniowca oznacza to, że zmiany klienta w zapytaniach zatwierdzających zostają zachowane, ale po każdej zmianie zapytania źródłowego fork trzeba odtworzyć ponownym uruchomieniem skryptu.

Adres skryptu w polu IKONA. Serwer rozpoznaje znacznik wersji tylko w postaci .js?v@, na przykład /role_wms/26/jqs_wms_cel.js?v@20261017. Gdy adres nie zawiera rozszerzenia .js, serwer dokleja .js na końcu całego tekstu, przeglądarka pyta o nieistniejący plik i dostaje stronę błędu. Objaw to pusty ekran transakcji i komunikat MojaOnLoad is not defined w konsoli przeglądarki. Poprawkę zawiera skrypt 1000.

Pamięć podręczna po wdrożeniu

Zapytania z tabeli zapytań serwer trzyma w pamięci podręcznej, dlatego po każdym wgraniu skryptów trzeba ją wyczyścić adresem /DefaultAdministrator.aspx?isdeploy=reset. W przeglądarce użytkownika dodatkowo pomaga Ctrl+F5, bo zmienia się skrypt ekranu. Menu użytkownika odświeża się dopiero po ponownym zalogowaniu, także po zmianie parametru MODUL_CELNY.

Wymagania serwera SQL

Schemat korzysta z funkcji JSON (OPENJSON, JSON_VALUE, ISJSON) oraz z instrukcji CREATE OR ALTER i THROW, dlatego wymaga SQL Server 2016 SP1 i poziomu zgodności bazy co najmniej 130. Wersję serwera i poziom zgodności bieżącej bazy sprawdzają dwa zapytania poniżej, wykonywane przed wgraniem skryptów.

SELECT @@VERSION AS wersja;
SELECT name, compatibility_level FROM sys.databases WHERE name = DB_NAME();

Cofnięcie

Najprostsze cofnięcie to MODUL_CELNY równe 0 na ekranie Ustawienia modułu: menu znika po ponownym zalogowaniu i przestają być dostępne dokumenty PZC oraz WZC. Dane zostają w tabelach, więc ponowne włączenie przywraca poprzedni stan. Schematu bazy nie trzeba usuwać, ponieważ bez wierszy menu nikt nie otworzy ekranów modułu. Usuwanie danych demonstracyjnych opisuje strona wdrożenie i testy.

Zmiana wartości parametru bezpośrednio w bazie nie wystarczy, bo wiersze menu zmienia procedura zapisu parametru. Jeżeli parametr ustawiono poleceniem UPDATE, trzeba wykonać także UPDATE wierszy menu z rodziny UNIQUEID, ustawiając AKTYWNE na 0.