====== Szablon dokumentacji projektowej ======

<!--
===== 1. Ogólny opis systemu (wizja) =====

==== Cel (przeznaczenie) systemu ====

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.

==== Udziałowcy i użytkownicy ====

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



==== Podstawowe cele udziałowców i użytkowników ====

Należy krótko (np.: w tabeli) wyliczyć podstawowe cele stawiane systemowi przez poszczególnych użytkowników. 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

^Udziałowiec^Cel^Priorytet^
|Klient|Możliwość dodania towaru do koszyka|Wysoki|
|Klient|Możliwość usunięcia towaru z koszyka|Wysoki|
|Klient|Wystawienie opinii o sklepie|Średni|
|Klient|Wyszukiwanie podobnych towarów i rekomendacje|Niski|
|Klient|Wybór opcji dostawy|Wysoki|
|Nabywca|Możliwość zmiany szaty graficznej|Średni|
|Nabywca|Wyświetlanie aktualnych promocji|Wysoki|
|Nabywca|Wdrożenie w systemie Linux|Wysoki|
|Zespół|Zastosowanie JEE|Wysoki|
|Zespół|Zastosowanie bazy danych Oracle|Niski|

==== Granice systemu (wejścia, wyjścia) ====

W notacji UML - granicami systemu są **Aktorzy**

Aktorem może być:
  *Użytkownik
  *Inny system
  *Czas (dla procesów lub zadań uruchamianych samoczynnie w wybranych momentach czasu)

Diagram pokazuje system oraz aktorów. Odpowiednik  [[http://home.agh.edu.pl/~pszwed/se/dfd/sample.html|diagramu kontekstowego DFD]]. Np.: [[http://www.google.pl/imgres?imgurl=http://www.agilemodeling.com/images/models/contextDiagramUC.jpg&imgrefurl=http://www.agilemodeling.com/essays/agileRequirementsExample.htm&h=374&w=600&sz=20&tbnid=d_fU7AmOiT8iqM:&tbnh=90&tbnw=144&zoom=1&usg=__1fPnS7Xx9YzpKohfFVUyMQO-b-I=&docid=VSPdKxkK7Wd9ZM&sa=X&ei=QyF_UICfJMTitQbRt4HgDw&ved=0CD0Q9QEwAw&dur=2381|Obrazek z sieci ]]  

==== Lista możliwości (funkcji systemu)====

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

Ten rozdział można zilustrować **diagramem czynności** (activity diagram) pokazującym typowe sekwencje działań wykonywanych w systemie. Poszczególnym 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 (także wykonywane manualnie). Np.:
  -Czytelnik wyszukuje książkę w katalogu i sprawdza jej dostępność i lokalizację na półce
  -Czytelnik bierze książkę z półki i zanosi do stanowiska bibliotekarza
  -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 [[amo:zadanie_4|Analiza i modelowanie oprogramowania - zadanie 4 (diagram czynności)]]

===== 2. Analiza dziedziny (analiza obiektów biznesowych) =====

  *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.

 

//2-5 stron//

  *Patrz [[amo:zadanie_1|Analiza i modelowanie oprogramowania - zadanie 1]]
  *Patrz [[amo:zadanie_3|Analiza i modelowanie oprogramowania - zadanie 3 (diagram stanów)]]

===== 3. SRS - Specyfikacja wymagań =====

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 [[io:use_case_template|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. W przypadku dużej liczby przypadków użycia typu Nowy, Modyfikuj, Usuń należy starać się scalić je w jeden (Definiuj) przedstawiając pozostałe jako przebiegi alternatywne.

//brak ograniczeń objętościowych, wystarczy przedstawić specyfikacje dla 5 przypadków użycia//

Patrz [[amo:zadanie_2|Analiza i modelowanie oprogramowania - zadanie 2]]

===== Analiza i projekt =====

===== 5. Architektura systemu =====

  *Wyliczenie warstw (np.: architektura trójwarstwowa model-widok-kontroler)
  *Lub wyliczenie podstawowych komponentów będących odrębnymi programami (nadawca-odbiorca, klient-serwer). Zamodelowanie ich jako klas z odpowiednim zestawem metod.
  *Specyfikacja interfejsu pomiędzy komponentami (np.: format wymiany danych pomiędzy nadawcą i odbiorcą – opcjonalnie).

W przypadku większości systemów wystarcza określenie, że są wykonywane w trójwarstwowej architekturze. Dla systemów złożonych z samodzielnych programów (np.: komunikator korzystający z pośrednictwa serwera konieczne jest zdefiniowanie interfejsu komunikacyjnego.

:!: W opisie architektury należy określić 
  *platformę implementacji systemu (komponentów systemu) lub/oraz
  *sposób integracji systemu (usługi sieciowe, procesy.

Patrz [[amo:zadanie_6|Analiza i modelowanie oprogramowania - zadanie 6 (diagram komponentów na początku)]]

//1 – 5 stron//


===== 6. Obiektowy model analizy =====

Rozdział opcjonalny :!: Jeżeli występuje,  powinien identyfikować:

  *podstawowe klasy występujące w systemie (atrybuty, metody, związki, diagramy stanów klas).
  *opisywać ich zachowanie za pomocą diagramów sekwencji lub współdziałania
Opis powinien pomijać celowo szczegóły implementacji. Dobrym uzasadnieniem dla tworzenia tego opisu jest aplikacja, która jest projektowana dla wielu platform. W docelowym projekcie dla danej platformy abstrakcyjne elementy zostaną odwzorowane w konkretne elementy projektu (np.: interfejs MFC, interfejs HTML, interfejs XWindows, itp.

Dla serwisów internetowych zrealizowanych w architekturze trójwarstwowej rozdział ten można pominąć. Projekt oprogramowania zapewni w takim przypadku odpowiedni poziom szczegółowości.

//brak ograniczeń na objętość//
 

===== 6. Projekt oprogramowania =====

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. 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 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.

Identyfikując klasy (zwłaszcza dla serwisów internetowych) należy pamiętać, że ta część dokumentacji powinna odpowiadać na pytanie:

  *jakie strony może utworzyć dany skrypt
  *jakie operacje wykonuje na bazie danych

Mimo, że strony są generowane dynamicznie, należy potraktować je jak klasy. \\
Mimo, że kwerendy są również generowane dynamicznie, należy potraktować je jako metody klasy BazaDanych (lub jednej z klas modelu). Takie podejście pozwala oszacować wielkość i złożoność interfejsu użytkownika oraz stopień złożoności operacji na bazie danych.

//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
//

Patrz [[amo:zadanie_6|Analiza i modelowanie oprogramowania - zadanie 6 (diagram klas i sekwencji dla realizacji przypadków użycia)]]

===== 7. Projekt interfejsu użytkownika IRS =====

  *Dla klas interfejsu użytkownika należy dołączyć ich projekt (typu zrzuty ekranu lub schematy interfejsu w Visio).
  *Schemat może być uzupełniony diagramem stanów pokazującym sposób nawigacji po interfejsie użytkownika.
  *Formularze, strony powinny być opisane identyfikatorami klas.
  *Jeżeli formularz lub strona pokazuje listę elementów, oczekuje się, że na diagramie struktury pokazana zostanie agregacja pomiędzy klasą strony i klasą odpowiadającą elementowi.

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

===== 8. Projekt bazy danych DBDD (jeżeli występuje)=====

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

//1 diagram + tabela ze specyfikacjami kwerend//

Patrz [[http://home.agh.edu.pl/~pszwed/wiki/doku.php?id=inzynieria_oprogramowanie_projekt#diagram_erd|diagramy ERD]]
-->