Schemat architektury systemu Teneum¶

Poniższy schemat ilustruje ideę wyodrębnienia w ramach projektu fasady oraz Api dla systemów zewnętrznych.

Fasada projektu (API)¶

Po co robimy fasadę?

aby funkcje biznesowe wykonywać zawsze w taki sam sposób
aby ukryć szczegóły implementacyjne przed osobami, które nie muszą ich znać, a jedynie chcą skorzystać z naszego modułu (enkapsulacja)
aby złożone funkcje biznesowe wykonywać w prosty i zrozumiały sposób
aby móc w przyszłości refaktoryzować wnętrze modułu, a po refaktoryzacji inni mogli z niego korzystać w taki sam sposób jak do tej pory
aby testował moduł i generować w nim dane demo

Fasada projektu jest obligatoryjna dla nowo tworzonych projektów, to znaczy że każdy projekt powinien mieć fasadę. Inny projekt (Y), który ma na liście referencji projekt (X), powinien się komunikować z projektem X tylko i wyłącznie przez jego fasadę.

Fasadę projektu stanowią obiekty biznesowe projektu tego projektu umieszczone w folderze "api". Każdy obiekt powinien odpowiadać jednemu zagadnieniu (np aktywności workflow, foldery dokumentów, zlecenia WMS, itp). Nazwa obiektu, to rzeczownik w liczbie pojedynczej.

Obiekt fasady może być bez źródła danych jeśli źródło danych nie jest wystawiane na zewnątrz. Taki obiekt może wystawiać:

statyczne metody logiki - służą do wykonywania operacji bezinterfejsowych, np załóż dany obiekt w bazie, usuń, akceptuj fakturę, itp. Nazwa: czasownik w jęz. angielskim w trybie rozkazującym (Create, Update, Delete). Jeśli metoda działa asynchronicznie, np zleca tylko komendę przez EDA i się kończy, na końcu nazwy metody dodaj "Async", np "CreateAsync".
statyczne metody interfejsu - służą do wykonywania operacji interfejsowych, np pokaż okno nowej faktury, pokaż okno zadanej faktury, itp. Nazwa: czasownik w jęz. angielskim w trybie rozkazującym (Show, ShowNew)
zdarzenia - są tu zdefiniowane zdarzenia, na które inny projekt może mieć handlery, np: dodano fakturę, zaakceptowano fakturę, itp. Nazwa: czasownik w jęz. angielskim w formie biernej + słowo "Event" (AddedEvent)

Metoda fasady może przyjmować parametry. Jeśli jest ich nie więcej niż 3, mogą to być podane bezpośrednio. Jeśli ma ich być więcej, to lepiej w parametrze przekazywać strukturę danych.

Obiekt fasady może także mieć źródło danych, dzięki czemu zewnętrzny moduł może go powołać jako programowe źródło danych, iterować po nim oraz wykonywać operacje CRUD (Create, Update, Delete).

Fasada jest pasywna, to znaczy nie woła aktywnie innych modułów, a jedynie udostępnia swoje własne funkcjonalności dla kogoś z zewnątrz.

Wszystkie metody, parametry i struktury danych fasady powinny mieć komentarze, które będą dostępne w intellisense. Struktury danych wykorzystywane w fasadzie powinny w nazwie mieć nazwę obiektu + przeznaczenie, np "ActivityInfo", "ActivityUpdateInfo".

Fasada SQL w bazie danych¶

Dopóki projekty nie mają fasad w obiektach biznesowych neosa, to robimy co najmniej fasadowe procedury SQL w bazie danych. W przyszłości metody fasadowe neosa będą mogły wywoływać te procedury, lub mieć przepisany ich kod. Fasady w bazie danych robimy przy okazji wszystkich projektów rozwojowych, w ramach których chcemy zapisać jakieś dane do struktur danych innych projektów. Zaleca się także czytać dane z innych projektów przez procedury fasadowe, chyba że wymagania wydajnościowe powodują, że musimy robić selecty/joiny bezpośrednio do tabel źródłowych.

Procedury fasadowe SQL nazywamy w pełni po angielsku, wg następującego schematu:

<MODUŁ>\API_<OBIEKT><CZYNNOŚĆ>

np:

Przykład

TDAPI_ORDER_ADD - procedura fasadowa do założenia nagłówka zamówienia

TDAPI_ORDER_POS_DEL - procedura fasadowa do usunięcia pozycji zamówienia

TDAPI_ORDER_OPERATION - wywołanie operacji na zadanym zamówieniu

TDAPI_ORDER_CHECKACCEPT

Ze względu na brak drzewiastych struktur danych, procedury SQL API działają atomowo, czyli np jedna procedura zakłada nagłówek zamówienia, a inna pozycję. Fasada C# połączy to w jedną metodę i strukturę danych do zakładania zamówienia wraz z pozycjami.

Parametry w/w procedur powinny być jak najbardziej przejrzyste i minimalne, czyli np do założenia pozycji zamówienia powinno wystarczyć podanie: REF zamówienia, WERSJAREF, ILOSC, a opcjonalnie także cena cennikowa i rabat. Przez procedurę fasadową nie przepychamy niezrozumiałych parametrów, takich jak jakieś REFy łącznikowe do innych struktur danych, itp.

Aktualnie posiadamy fasady SQL do następujących modułów:

https://docs.google.com/document/d/1nEuxvrtXQYDjHZyzAGJU7XgfyvjU9HYZsc3hp-SfK5Y/edit?usp=sharing (TD)

Fasada a WebApi¶

WebApi stanowi rozszerzenie fasady na potrzeby zewnętrznych systemów. WebApi Jest opcjonalne. Jeśli obiekt fasady ma źródło danych, to zawiera metody webapi do CRUDa (GetAll, Get, Post, Put, Delete). Jeśli obiekt fasady posiada statyczne metody logiki, to każda taka metoda może być udostępniona na zewnątrz odpowiednią metodą webapi.

Przykład fasady¶

Przykład

Fasada projektu WORKFLOW

Obiekt api/ACTIVITY (obiekt bez źródła danych):

statyczne metody logiki:

Create(ActivityInfo)
Update(ActivityUpdateInfo)
Delete(int)
ExecuteTransition(ActivityTransitionInfo)
ActivityInfo Get(int)
ActivityInfo Get(string, int)

statyczne metody interfejsu:

Create(ActivityInfo)
Show(int)
ShowNew(int)
StartTransition(ActivityTransitionInfo)

zdarzenia:

AddedEvent { ActivityInfo }
ChangedEvent { ActivityChangeInfo }
DeletedEvent { ActivityInfo }

Obiekt api/GQS:

statyczne metody logiki:

IndexAsync(IndexCommand)
DeleteIndexAsync(DeleteIndexCommand)

zdarzenia:

ReindexAllEvent { otable }

Projekty integracyjne¶

Projekty funkcjonalne (np. TD, WMS, FA) nie powinny być od siebie nawzajem zależne, gdyż powodowałoby to cykle zależności, a to jest niemożliwe. Dlatego projekty te powinny być od siebie niezależne i ze sobą nie rozmawiać. W celu łączenia projektów, należy tworzyć dodatkowe projekty - tzw. projekty integracyjne. Powinny one zależeć od tych projektów, które są integrowane i wykorzystywać ich fasady.

Przykład:

Przykład

Do księgowania dokumentów handlowych powinniśmy przestać używać triggerów i generalnie wyciąć z bazy zależności między TD a FA. Zamiast tego TD w swojej fasadzie powinien zgłaszać m.in. zdarzenie zmiany stanu akceptacji faktury, a projekt FA w swojej fasadzie mieć metody logiki służące do wystawiania dokumentów księgowych. Dodatkowy projekt integracyjny między TD a FA, powinien subskrybować zdarzenia wystawiania dokumentów w TD i generować dokumenty w FA.

Dzięki projektom integracyjnym podłączenie do Teneum innego systemu księgowego wymaga jedynie napisania innego projektu integrującego TD z zewnętrznym systemem FK, który będzie działał analogicznie do naszego wewnętrznego modułu integrującego TD i FA.