Szablon dokumentacji projektowej

Należy opisać przeznaczenie systemu. Na przykład system obsługi biblioteki może dotyczyć biblioteki w AGH lub biblioteki w domu kultury. Skale tych systemów są nieporównywalne.

Inaczej: interesariusze.

Użytkownicy, właściciele, nabywcy systemu, pracownicy obsługi technicznej, użytkownicy wewnętrzni, zewnętrzni

Należy krótko (np.: w tabeli) wyliczyć podstawowe cele stawiane systemowi przez poszczególnych interesariuszy. Porównać sposób ich realizacji w aktualnym systemie (np.: manualnym) i systemie proponowanym. Należy nadać im priorytet.

Celem:

• Użytkownika - jest zazwyczaj pewna funkcjonalność lub wydajność
• Właściciela - np.: użycie technologii, platform, implementacja funkcji odróżniających od konkurencji, rozbudowane procedury konfiguracji/instalacji, czas realizacji
• Zespołu odpowiedzialnego za rozwój - użycie konkretnych technologii (doświadczenie)

Na przykład

W notacji UML - granicami systemu są Aktorzy

Aktorem może być:

• Użytkownik
• Inny system (np. system płatności, bramka SMS, serwer email)
• Czujnik (np. czujnik wjazdowy, odbiornik GPS, akcelerometr)
• Siłownik (np. szlaban zamykający bramkę)
• Czas (dla procesów lub zadań uruchamianych samoczynnie w wybranych momentach czasu)

Diagram pokazuje system oraz aktorów. Odpowiednik diagramu kontekstowego DFD. Np.: Obrazek z sieci

Wyliczenie bez szczegółowych opisów, można podzielić na funkcje dostępne dla grup użytkowników.

Zamieszczone tu (jeden lub kilka) diagramy czynności pokazują typowe sekwencje działań wykonywanych w systemie. Obejmują czynności realizowane za pomocą systemu komputerowego oraz manualne wykonywane przez aktorów oraz innych aktywnych interesariuszy. Wybranym czynnościom można nadać identyfikatory przypadków użycia.

Ideą jest, aby diagram czynności pokazywał pewien większy proces, obejmujący różne aktywności. Np.:

1. Czytelnik wyszukuje książkę w katalogu i sprawdza jej dostępność i lokalizację na półce
2. Czytelnik bierze książkę z półki i zanosi do stanowiska bibliotekarza
3. Bibliotekarz rejestruje wypożyczenie

Pierwsza czynność jest kandydatem na przypadek użycia Wyszukaj w katalogu; druga: jest manualna i nie jest przypadkiem użycia systemu; trzecia to: Zarejestruj wypożyczenie.

2-5 stron

Patrz Analiza i modelowanie oprogramowania - zadanie 4 (diagram czynności)

• Klasy zidentyfikowane w dziedzinie problemu, opis atrybutów
• Diagramy klas (relacje)
• Diagramy stanów (dla wybranych klas)
• Słownik pojęć

Zazwyczaj w dziedzinie problemu identyfikuje się klasy odpowiadające:

• obiektom fizycznym (paczka, osoba, samochód, samolot)
• zdarzeniom lub stanom (przyjęcie towaru, odlot, wypożyczenie)
• abstrakcyjnym pojęciom charakterystycznym dla dziedziny (PESEL, kolor, świadek)

Słownik pojęć powinien definiować podstawowe pojęcia (termin – znaczenie), którymi będziemy posługiwać się w dokumentacji. Najlepiej w formie tabeli. Słownik może przyrastać w miarę sporządzania dokumentacji.

Ogólna zasada: identyfikowane tu klasy odpowiadają najczęściej typom rekordów przechowywanym w bazie danych. W zależności od frameworku klasy te są nazywane https://www.geeksforgeeks.org/pojo-vs-java-beans/POJO, Entity, klasami modelu. Nie ma potrzeby specyfikowania metod tych klas.

Na tym diagramie nie zamieszczamy klas, które pojawią się później w projekcie, np. klas do obsługi baz danych typu Repository, czy DAO, czy też takich klas, jak kontroler czegoś, np. KontrolerBramkiWjazdowej.

2-5 stron

• Patrz Analiza i modelowanie oprogramowania - zadanie 1
• Patrz Analiza i modelowanie oprogramowania - zadanie 3 (diagram stanów)

Specyfikacja wymagań definiuje wymagania stawiane systemowi w postaci przypadków użycia. Przypadki użycia mogą być zgrupowane w pakiety.

• Ogólny diagram przypadków użycia
• Definicje przypadków użycia (należy przyjąć w miarę wyczerpujący szablon wskazujący aktorów, udziałowców, prewarunki, postwarunki, scenariusze itd.)

Przypadek użycia powinien zostać zdefiniowany zgodnie z przedstawionym dalej szablonem. Ponieważ dążymy do zdefiniowania wszystkich przypadków użycia, należy starać się ograniczyć ich liczbę i złożoność relacji. Dla podanych tematów należy oczekiwać 5-20 przypadków użycia. Zbyt mała liczba (np.: 3) świadczy o ogólnikowym potraktowaniu tematu, zbyt duża o nadmiernym zagłębieniu w szczegóły.

Cztery czy jeden. W zasadzie bardzo dużo operacji to CRUD C(reate) R(ead) U(pdate) D(elete). Mogą być wyrażone jako cztery przypadki użycia:

• Utwórz nowe zamówienie
• Szukaj zamówień
• Modyfikuj zamówienie
• Usuń zamówienie

W przypadku dużej liczby przypadków użycia można starać się scalić je w jeden (głowny to Utwórz nowe zamówienie) przedstawiając pozostałe jako przebiegi alternatywne. Zwyczajowym polskim terminem w przypadku scalania jest Definiuj (np. Definiuj zamówienie)

Zasadą jest, że możemy manipulować każdym obiektem dziedziny. Czyli na ogół oznacza to możliwość wykonania operacji CRUD na każdej klasie z diagramu klas.

Inną formą wyrażenia wymagań są historie użytkownika (ang. user story). Są znacznie krótsze i mniej sformalizowane. Zazwyczaj mają postać opisu mającego formę:

• Jako [opis użytkownika] oczekuję [funkcjonalności] aby [korzyść dla użytkownika].

Przykład pochodzący z tej strony.

• Jako administrator bazy danych, chcę móc automatycznie łączyć zbiory danych pochodzące z różnych źródeł, co ułatwi tworzenie raportów dla wewnętrznych klientów.

Historia użytkownika powinna mieć też zdefiniowane kryteria akceptacji (ang. Acceptance criteria). W tym momencie zaczynają się pojawiać testowalne wymagania

• Chcę mieć możliwość odczytu danych i metadanych ze źródła w postaci pliku CSV i ich wyświetlania
• Chcę mieć możliwość odczytu danych i metadanych ze ze źródła w postaci relacyjnej bazy danych i ich wyświetlania
• Chcę mieć możliwość wyboru atrybutów do łączenia danych z różnych źródeł
• Chcę mieć możliwość wyboru atrybutów do usunięcia

brak ograniczeń objętościowych, należy zamieścić specyfikacje dla 5 przypadków użycia i 3 historii użytkownika. Przypadki użycia nie powinny obejmować rejestracji i logowania - ale historie użytkownika mogą

Patrz Analiza i modelowanie oprogramowania - zadanie 2

W tej sekcji zamieszczamy diagramy tych elementów interfejsu użytkownika, które pojawiły się w opisach przypadków użycia. Można je narysować za pomocą wielu narzędzi online (szukaj wireframe i mockups) ale także w Visio (gdzie występują pod nazwą diagram szkieletowy)

• Schemat może być uzupełniony diagramem stanów pokazującym sposób nawigacji po interfejsie użytkownika.
• Formularze, strony powinny być docelowo opisane identyfikatorami klas.

należy przedstawić najbardziej interesujące diagramy; można pominąć elementy typu menu, lista opcji

Architektura systemu to mówiąc ogólnie zbiór komponentów połączonych interfejsami. Komponenty te mogą być przypisane do jednego lub kilku węzłów obliczeniowych.

• W przypadku aplikacji webowych przez wiele lat dominującą architekturą była realizacja wzorca MVC - z komponentami: model, widok, kontroler. Były one w zasadzie wykonywane na jednym węźle obliczeniowym (serwerze). Widok był postrzegany jako szablon nieaktywnej strony HTML.
  • Model odpowiadał za przechowywanie danych i realizację operacji na danych
  • Kontroler odpowiadał za logikę biznesową i koordynację operacji wykonywanych przez model
  • Widok odpowiadał za wizualizację danych oraz odbieranie poleceń od użytkownika i przekazywanie ich do kontrolera w formie wywołań skryptów
• W wyniku ewolucji strony interfejsu użytkownika stały się aktywne i widok przeniósł się do przeglądarki. Klasy widoku można utożsamiać ze stronami HTML (sekcjami stron), a metody z osadzonym kodem JavaScript
• Obecnie najczęściej spotykanym układem jest podział na backend i frontend połączone interfejsem REST. Przy takim podziale frontend jest odpowiednikiem widoku, ale wykonującym także część zadań kontrolera. Dodatkowo, interfejsu REST może zostać wykorzystany w aplikacji mobilnej.
  • Backend może być realizowany z użyciem różnych języków i frameworków (Java, Python, C#).
  • W przypadku frontendu typowym rozwiązaniem jest wdrożenie na serwerze HTTP dostarczającym pliki HTML, CSS oraz JavaScript. Kod aplikacji wykonywany jest po stronie klienta (w przeglądarce). Dla frameworków (szkieletów aplikacji) React lub Angular implementowanych w języku TypeScript jest konieczna konwersja kodu na JavaScript. Wymagane jest zastosowanie serwera Node.js odpowiedzialnego za translację. W tym przypadku aplikacja webowa (widok) składa się z wielu często zagnieżdżonych komponentów, które mogą być postrzegane jako klasy przechowujące i wyświetlające dane.
• W przypadku niektórych projektów należy w architekturze uwzględnić dodatkowe komponenty, np. kiosk do płatności, wideodetektor, kontroler rogatek.

W opisie architektury należy określić

• platformę implementacji systemu (komponentów systemu) lub/oraz
• sposób integracji komponentów

Patrz Analiza i modelowanie oprogramowania - zadanie 6 (diagram komponentów na początku)

1 – 5 stron

W tym rozdziale należy zamieścić projekt interfejsu pomiędzy komponentami systemu.

W większości przypadków będzie to zestawienie adresów usług REST (ang. endpoints).

Typowe polecenia są opisane tu

Opisy API w formacie REST są często pojawiającym się elementem dokumentacji. Dla trzech zapytań proszę zamieścić dokładną specyfikację, np. wzorując się na

• TMDB API
• API Allegro

Inne typy/implementacje interfejsów (nadające się do komunikacji pomiędzy komponentami, zwłaszcza dla urządzeń oraz aplikacji mobilnych przesyłających masowo dane ):

• GRPC
• Thrift
• https://doc.zeroc.com/
• RabbitMQ

W przypadku trzech pierwszych - specyfikuje się nazwę metody/funkcji oraz jej parametry i zwracane wartości. Metoda jest wywoływana przez klienta i wykonywana przez serwer. W obie strony wędrują komunikaty z danymi i ich strukturę należy wyspecyfikować.

W przypadku RabbitMQ wysyłane są komunikaty pomiędzy stronami uczestniczącymi w komunikacji. Jest to realizacja wzorca producent-bufor-konsument. Middleware obsługuje bufor i zajmuje się dostarczaniem komunikatów i potwierdzeń. Należy wyspecyfikować strukturę komunikatów.

Projekt systemu jest realizowany dla konkretnej platformy (języka programowania zapewniającego podstawowy zestaw klas, biblioteki, architektury systemu, itd.). W zasadzie rozdział ten powinien być największym objętościowo fragmentem. Jeżeli system składa się z niezależnych modułów (klient-serwer, nadawca-odbiorca) należy dla każdego z nich podać osobny projekt.

W projekcie należy określić platformę implementacji komponentu. Java, .NET, PHP, Oracle, MySQL, React, Angular, itp. Może to również zostać określone przy definicji architektury systemu.

Zawartość:

• Definicje klas (atrybuty, metody):
  • klas odpowiedzialnych za prezentację danych: dialogów, stron HTML
  • klas odpowiedzialnych za przetwarzanie, skryptów
  • klas odpowiedzialnych za składowanie i dostęp do danych (baza danych)
• Związki miedzy klasami (także związki z klasami występującymi w analizie dziedziny)
• Opis zachowania dla przypadków użycia (diagramy sekwencji lub współdziałania) odpowiadający scenariuszom.

Klasy mogą należeć do różnych warstw (frontend/backend). Interfejs backendu może być potraktowany jako:

• monolityczna klasa z metodami odpowiadającymi adresom endpoint
• kilka klas z odpowiednio rozdzielonymi metodami (co odpowiada architekturze mikroserwisów – ale zazwyczaj każdy mikroserwis jest realizowany przez osobny komponent).

Mimo, że baza danych wykonuje kwerendy, aspekt interpretowania zapytań i przetwarzania kwerend w postaci danych tekstowych nie interesuje nas. Każda kwerenda ma być potraktowana jako metoda jakiejś klasy o w miarę semantycznej nazwie. Czyli np. oczekiwana jest klasa:

• DataBase z metodami
  • addProduct(Product p)
  • User getUser()
• albo UserRepository (czy też UserDAO) z metodami:
  • getAll()
  • get(int id)
  • add(User u)

Można zajrzeć tu. Specyfikacja kwerend - pojawi się w rozdziale 8. DBDD

Objętość: każdy przypadek użycia powinien zostać zdefiniowany za pomocą odpowiedniego diagramu interakcji. Klasy (z atrybutami i metodami) oraz ich związki powinny zostać również zdefiniowane. W miarę możliwości zestaw powiązanych zależnościami klas należy umieszczać przed diagramem interakcji. opis klas w tabelach, 5 diagramów związków klas, 5 diagramów dla zachowania

Uwaga

• Komunikaty to wywołania funkcji. Powinny być metodami odbiorcy.
• Komunikaty zwrotne (przenoszące zwracane wartości) linie przerywane. Nie zwracamy wartości wywołując metody obiektu
• Współczesne komponenty aplikacji webowych działają asynchronicznie. Pomińmy ten aspekt.
• Aktor - użytkownik - nie wysyłamy do niego komunikatów, ale wołamy funkcję GUI, która uaktualnia lub zmienia widok (tworzymy nowe okno lub wołamy funkcję wyświetlKomunikat()

Patrz Analiza i modelowanie oprogramowania - zadanie 6 (diagram klas i sekwencji dla realizacji przypadków użycia)

• Schemat bazy danych jako diagram ERD
• Specyfikacja kwerend (metody klasy są kwerendami, należy podać ich specyfikację)

Oczekiwana jest spójność diagramu ERD z diagramem klas…

1 diagram + tabela ze specyfikacjami kwerend

Patrz diagramy ERD