Skip to content

Suunnitteludokumentaatio

1. JOHDANTO

Toimeksiantajalta Janne.Laitinen@jamk.fi on saatu tehtäväksi kehitellä Meijän Polku -projektin Meijän Metsät-karttapalvelu osana Keski-Suomen hyvinvoinnin osaamiskeskittymä KeHo:a. Ennestään olemassa olevat karttapalvelut on todettu puutteellisiksi toimeksiantajan tämänhetkisiin käyttötarpeisiin. Jyväskylän Ammattikorkeakoulun (JAMK) ICT-instuutilta on toimitettu toimeksianto tuotteen kehittämiseksi. Projektiryhmänä toimii Tiimi-B Himalaja ja tavoitteena osana projekti - ja testauskurssia on kevään aikana tuottaa demo-tuote, jonka pohjalta varsinaista markkinatuotetta lähetään kehittämään.

1.1 Tarkoitus ja kattavuus

Tämä projektidokumentti on tarkoitettu toimeksiantajalle ja muille projektin kehityksen näkökannalta relevanteille taholle. Dokumentin tehtävä on antaa lukijalleen tietoa tuotteen toiminnasta, ominaisuuksista, käyttötarkoituksista, tavoitteista, arkkitehtuurista ja muista ohjelmistokehityksen kannalta tärkeistä suunnittelu-, teknologia- ja toteutusdokumenteista. Sen lisäksi dokumentti antaa lukijalleen tietoa siitä, mitä varten eri ominaisuuksia on luotu tuotteen toteutuksessa, mihin tietoon tai epistomologiseen (tieto-oppi) ajatteluun pohjautuen erilaisia hyväksyttyjä toteutustapoja, toimintatapoja ja käytänteitä on toteutettu projektin aikana. Projektidokumentaation julkaisuvaiheessa V1.0.0.0. dokumentti on keskittynyt pohjamäärittelyyn, eli kyseinen dokumentti ei ole vielä valmis vaan se on pohja, jonka perusteella työtä jatketaan eteenpäin. Se on kuitenkin suunniteltu ja laadittu tarpeeksi kattavaksi, että se toteuttaa kaikki tarvittavat toimenpiteet tuotannon lähdekoodin ja laadunvalvonnan testauksen aloittamiseksi.

1.2 Tuote ja ympäristö

Kyseessä on Meijän Polku - projektin Meijän Metsät-karttapalvelu. Tuotteen tavoite on tuottaa karttapalvelu, jossa kuluttaja saisi mahdollisimman paljon tietoa luonnon retkikohteista, ympäristönstä liikuntamahdollisuuksista luonnossa, alueella olevista palveluista, sekä muusta retkeilyn ja luonnossa liikkumisen kannalta relevantista tiedosta. Tuote on pääsijaisesti suunniteltu toimivaksi mobiililaitteilla, mutta Team-B Himalajan toteutuksessa tavoitellaan arkkitehtuuria, jolla saadaan ohjelmisto luotua samalla sekä mobiililaitteille, että myös PC tietokoneille käytettäväksi.

1.3 Määritelmät, merkintätavat ja lyhenteet

  • Android = Yleisin mobiililaitteiden käyttöliittymä.
  • ANSI = American National Standards Institute, on yleinen ohjelmistostandardien suunnittelua määrittelevä instituutio.
  • API = Application Programming Interface. API:t ovat ohjelmiston rajapintoja. Käytännössä tämä on ohjelmistoprotokolla, jonka avulla eri ohjelmistot kommunikoivat keskenään. Esimerkiksi facebookin kautta sisäänkirjautuminen toiseen ohjelmaan.
  • ASTM = American Society for Testing and Materials on testaukseen määrittelyn standardeja määrittelevä instituutio.
  • camelCasing = Ohjelmiston nimeämisstandardina käytetty camelCasing auttaa koodajia lukemaan ja erottelemaan avainsanoja koodista.
  • CSC = Tieteen tietotekniikan keskus, joka tekee yhteistyötä mm. JAMK kanssa. Tätä pilvipalvelua käytetään projektissa.
  • Docker Container = Kontti on ohjelmistotuotannon palvelu, jonka avulla ohjelmisto voidaan jakaa kevyisiin irrallisiin paloihin ja muokata itsenäisinä paloina.
  • GDPR = General Data Protection Regulation on yleinen EU:n asettama tietosuojastandardi. Tätä dokumenttia noudatetaan esimerkiksi ohjelmistojen tietojenkäsittelyssä.
  • IEC = International Electrotechnical Comission on kansainvälinen tietojenkäsittelyn standardeja määrittelevä komissio.
  • iOS = iOS on AppleInc. mobiililaitteille luoma käyttöliittymä.
  • MySQL = MySQl on relaatiotietokanta-arkkitehtuuri, joka on laajassa käytössä tietokantatoteutuksissa. Ohjelmisto hakee osan ohjelmiston datasta relaatiotietokannoista.
  • NIST = National Institute of Standards and Technology on yleinen teknologian standardeja ja käytänteitä määritteleva organisaatio. Erityisesti kyberturvallisuutta koskevissa asioissa.
  • OS = Operating System. OS on kunkin laitteen laitteen käyttöjärjestelmä, kuten Windows 10, Applen macOS tai Linus Torvaldsin luoma Linux.
  • PascalCasing = Ohjelmiston nimeämisstandardina käytetty PascalCasing nimeämismetodi auttaa koodajia lukemaan ja erottelemaan avainsanoja koodista.
  • SFS = Suomen standardisoimisliitto vastaa Suomen maansisäisistä standardisoinneista, esimerkiksi tietojenkäsittelyn standardisoinnista Suomen lainsäädännön mukaiseksi.
  • UI = User Interface. Ohjelmiston käyttäjäliittymä (Huom! ei ole sama kuin käyttöliittymä). Käyttäjäliittymä on kunkin ohjelmiston oma käyttöliittymä, joka vastaa kyseisen ohjelman visuaalisesta presentaatiosta ja käyttäjän interaktiivisuuden kommunikaatiosta ohjelmiston kanssa.

1.4 Viitteet

1.5 Yleiskatsaus dokumenttiin

Dokumentin rakenne noudattaa JAMK ICT-instituution projekti - ja testaus-kurssin dokumentaatiopohjaa JAMK labranetin Gitlab ympäristössä. Projektin etusivulta löytyy sisällysluettelo.

00 Tilannekatsaus osiossa on kirjattu viikoittaiset sprintit, joihin kirjataan ylös kunkin viikon onnistumiset ja haasteet sekä muuta tietoa sprintistä.

10 Projektihallinta kansion alta löytyy tietoa projektiryhmän jäsenistä, sekä projektinhallinnan dokumentaatioista.

20 Vaatimusten hallinta sisältä löytyy projektin päädokumentaatiot. Vaatimusmäärittelydokumenttiin on kirjatty ylös tärkeimmät piirteet, ominaisuudet, vaatimukset ja muut määrittelyt ja suunnittelut ja se toimii projektin ydindokumenttina. Saman kansioston alta löytyvät myös profiilikuvaukset, asiakastarinat, käyttötapaukset, ominaisuudet ja muut vaatimustenhallintaan liittyvät dokumentit.

30 Arkkitehtuuri ja suunnittelu dokumentaatiokansiossa on projektin arkkitehtuuriin ja teknisiin rakenteisiin liittyvää tietoa mm. tietokantarakenteesta ja teknisen arkkitehtuurin suunnitelmista. Sen lisäksi sieltä löytyy tämä suunnitteludokumentaatio.

40 Julkaisusuunnitelma dokumentaatiosta löytyy tuotteen ominaisuuksien kehityksen ja julkaisun aikataulu. Täältä löytyy myös alustava listaus kaikista ohjelmiston suunnitelmista. V1.0.0.0. kohdassa listattuna on tärkeimmät ominaisuudet ja karkea arviointi.

50 Testaushallinta dokumentaatiosta löytyy projektin laadunvalvonnan testaus ja automatisaatiosuunnitelma, sekä muita laadunvalvontaan ja testaukseen liittyvää dokumentaatiota.

60 Tuotanto dokumentaation sisältä löytyy projektin laskutukseen ja tarjoukseen liittyvää dokumentaatiota.

80 Dokumentit ja raportointi sisällöltään käsittelee projektin dokumentaation dokumentteja, kuten projektin tilannekatsauksen, palvelunkuvauksen ja käyttöohjeet.

99 Projektikirjasto alta löytyy projektin lähteitä, hyödyllisiä linkkejä ja muita projektin kannalta relevantteja lähdekirjastoja.

2. JÄRJESTELMÄN YLEISKUVAUS

Karttapalvelu-tuote on suunniteltu käytettäväksi sekä PC:eillä että mobiililaitteilla. Se hyödyntää CSC:n tarjoamaa pilviarkkitehtuuria palvelimena ja sen lisäksi se hyödyntää muita kolmannnen osapuolen API rajapintoja tiedonhakemiseen ohjelmistossa.

2.1 Sovellusalueen kuvaus

Järjestelmä Meijän Metsät osana Meijän Polku -hanketta on suunniteltu osaksi Keski-Suomen hyvinvoinnin osaamiskeskittymä - KeHo tilaamaa palvelutuotetta. Kyseessä on luonnossaliikkumista edistävä karttapalvelusovellus, joka hakee dataa useista palveluista ja luo kevyesti käytettävän ja kattavan karttapalvelusovelluksen.

2.2 Järjestelmän liittyminen ympäristöönsä

Tässä ympäristössä järjestelmä tekee tiedonhakua muista rajapinnoista, sekä tiedontalletusta omaan palvelimeen tulevaisuuden käyttöä varten.

2.3 Laitteistoympäristö

Laitteistoympäristönä toimii CSC:n pilvipalvelinympäristö ja MySQL-relaatiotietokanta. Toistaiseksi projektiin ei ole implementoitu palvelinmigraatiota. Sovellustuote soveltuu käytettäväksi PC:llä (Windows ja macOS) sekä mobiililaitteilla kuten Android ja iOS. Rajoitteina on palvelun laiterajoitevaatimukset. MySQL-tietokantaa tarvitaan käyttäjätunnuksen, sähköpostin ja muun käyttöön liittyvän datan säilytykseen. Tietokannassa rajauksena jokaisella henkilöllä on oltava uniikki tunnistautuminen tietokantaan, jotta tietokannassa ei tule datan konflikteja ja toiminnallisuus ei rikkoudu.

2.4 Ohjelmistoympäristö

2.5 Toteutuksen keskeiset reunaehdot

Reunaehdoiksi asiakkaalta on saatu vaatimuksia mm. siitä, että haku ja rajauspalvelu voidaan suorittaa riippumatta siitä, onko käyttäjä luonut tilin ja kirjautunut sisään tilille. Toteutuslaitteistoksi suosituksena on pääsääntöisesti tietokonealusta, mutta hyvä jos ratkaisun toteutuksessa myös mobiiliversiototeutus. Vaikka asiakas ei osannut ottaa kantaa tietoteknisiin rajauksiin, niin kyberturvallisuudessa noudatetaan GDPR - standardia, eli Euroopan Unionin sisäistä tietoturvasuoja asetuksia ja suosituksia määrittelemään millaista dataa käyttäjästä kerätään ja tallennetaan palvelimelle ja mitkä osat datasta pysyvät käyttäjän lokaalisessa välimuistissa. Sen lisäksi reunaehtona se asettaa tiettyjä rajauksia ratkaisun toteutukselle ja ominaisuuksille, joten sen huomoiminen on keskeinen ratkaisussa.

Ohjelmistopalvelun kattava käyttö-ohje löytyy käyttö-ohje dokumentaatiosta ja palvelutuotteen sisällä on minimaalinen käyttö-ohje, joka lähinnä antaa käyttäjälleen tietoa kartan tulkinnan helpottamiseksi ja selkeyttämiseksi. Lähdekoodi kommentoidaan, jotta sen luettavuus helpottuu ja jatkokehityksen kannalta ohjelmiston toimintaa on helpompi ymmärtää ja jatkokehittää.

2.6 Sopimukset ja standardit

Yleiskäytössä on ohjelmistokoodaukseen käytettyjä standardeja. Esimerkiksi ohjelmistokoodissa tuttua PascalCase nimeämiskäytäntöä luokkien nimeämiselle, camelCasing nimeämiskäytäntöä metodien ja muuttjien nimeämiselle. Yleisesti hyvänä käytäntönä on myös käytetty ns. koodin kommentointia, joka antaa koodin lähdekoodissa tietoa lukijalle siitä, mitä kyseinen koodinpätkä tekee ohjelmistossa.

Ohjelmiston suunnittelussa on käytetty yleistä ANSI standardia, jonka osa-alueisiin kuuluvat mm. suunnittelu, managerointijärjestelmä, prosessit, tuotteet ja testausmetodit. Lisää standardista ASCE/SEI 7-16. Ohjelmiston spesifikaation standardisoinnissa on höydynnetty ASTM - standardia, joka antaa spesifikaatioon, testi metodeihin, terminologiaan, käytäntöihiin ja ohjeistukseen liittyviä standardisuosituksia. Näistä standardeista voit lukea lisää ASTM F963-17.

Ohjelmiston tuotannossa on käytetty ISO - standardia, jonka standardisointiin kuuluvat tuote, testimetodit, ohjelmakoodin käytäntöjä, ohjenuorat ja managerointijärjestelmä. Lisää aiheesta ISO 13485:2016. Huomattavaa on se, että ISO toimii yhdessä IEC:n organisaation kanssa yhteistyössä, joten voi myös törmätä terminologiaan ISO/IEC JTC1. Ohjelmiston kehityksen standardeja määrittelee IEEE. Ohjelmistotuotannon ja elinkaaren standardisoinnin standardeina on käytetty ESA standardisointia.

Kyberturvallisuuden standardeissa käytetään GDPR - standardia, eli Euroopan Unionin määrittelemään GDPR - tietojenkäsittelyn ja tallennuksen standardeja. GDPR määrittelee mitä tietoa voidaan käsitellä, miten ja millaista tietoa tallennetaan mihinkin ja miten tietoa tulee käsitellä palvelutuotteissa tietoturvallisesti. Aiemmin mainittu ISO/IEC - standardisointi organisaatio asettaa myös standardisointia kyberturvallisuudesta mm. ISO/IEC 27032:2012, sekä erillinen organisaatio NIST. Suomen maankohtaisen lain perusteella standardisoinnista vastaa SFS ja sen perusteella määritellään vielä maan omien lakisäädösten pohjalta standardeja ohjelmistopalvelulle.

3. ARKKITEHTUURIN KUVAUS

Arkkitehtuurin kuvauskappaleessa käsitellään järjestelmän toteutusta tekeville vaadittavat tiedot, jotka täytyy tietää ja ymmärtää. Tällaisia piirteitä ovat esimerkiksi projektin suunnitteluperiaatteet, teknologiavalinnat ja ohjelmiston arkkitehtuuri yleisesti.

3.1 Suunnitteluperiaatteet

Suunnitteluperiaatteet antavat tietoa ohjelmistoarkkitehtuurin järjestelmän filosofiasta eli ohjelmiston suunnitteluun liittyvistä ajattelumalleista.

  • Käyttäjäjärjestelmä on mahdollisimman kevyt käyttää. Tämä tarkoittaa siis graafista toteutusta ja minimaalista tekstin määrää oletusnäytössä.
  • Järjestelmä jakaantuu osiin seuraavasti: laitteisto¬abstraktio-kerros, käyttöjärjestelmäkerros ja sovellusmoduulikerros.
  • Järjestelmä jakautuu komponentteihin: front-end eli mitä käyttäjä näkee, back-end eli mitä toimintoja tehdään, tyylitiedostot omissa moduuleissaan. Tämä selkeyttää luettavuutta.
  • Käyttäjäliittymä on 'notkea', eli käyttäjä voi käytössä laajentaa hakuvalikon esiin, tai pienentää sen pois näkyviltä kartan näkyvyyden maksimoimiseksi. Sen hetkisen käytön kannalta tarpeettomat toiminnot piiloutuvat napin painalluksella.
  • Sovellusmoduulikierroksen moduulit ovat joko passiivisia kirjastoja, tai aktiivisia prosesseja. Molempien tyyppien koodirungoista on esimerkki liitteessä .
  • Ohjelmiston ulkoasun presentaatiossa on huomioitu eri käyttäjäryhmien tarpeita, kuten väriteemassa otettu värisokeutta huomioon mahdollisimman paljon.
  • Demotuotteen toteutuksessa on huomioitu eri retkikohteiden luonne. Eli jokaiselle erityyppiselle retkikohteelle on oma logonsa, jotta se antaa tietoa jo valmiiksi käyttäjälle ja parantaa luettavuutta.

3.2 Ohjelmistoarkkitehtuuri, moduulit ja prosessit

3.3 Tietokanta-arkkitehtuuri

Tietokannan arkkitehtuurin rakenne

Yllä olevasta tietokannan rakenteesta saadaan selkeä kuva siitä, mllaista tietoa on tallennettu eri tietokantojen soluihin. Tietokantana on käytetty MySQL -relaatiotietokantaa. Lähes kaikkia tauluja yhdistää taulun alkiolle yksilöllinen ID, jota käytetään taulun yksikön yksilöimiseen ja tunnistamiseen. Tässä toimintona on tauluille asetettu ns. Auto_Increment komentoa, joka taulun luodessaan luo jokaiselle alkiolle sen yksilöidyn ID-yksilöintitunnisteen ja jokaisella alkiolla on aina oltava sellainen.

Tästä poikkeuksena on planshaslocations - taulu, joka on ns. välitaulu ja joka ei itsessään ole osana tietokannan tietojen säilyttämistä varten olevia soluja, vaan välitauluja käytetään kahden monesta moneen suhteessa olevan taulun tunnistuksen validointiin ja tiedon kuljettamiseen eheydellisesti solujen kommunikaatiossa.

3.3.1 Terminologiaa ja merkintätapoja

MySQL komentokirjasto

  • Salamamerkki = Taulun yksilöivä kenttä, kuten 'id' eli identifier (tunniste).
  • Sininen täysi timantti = NOT NULL, eli kenttä ei voi olla tyhjä vaan siihen on pakko syöttää tietoa.
  • Sininen tyhjä timantti = NULL tai UNDEFINED, tämä kenttä on joko asetettu oletukseksi tyhjäksi tai se on määrittelemätön. Tälläiseen kenttään ei ole pakko syöttää mitään tietoa oletuksena.
  • Punainen täysi timantti = FOREIGN KEY, ns. vierasavain. Tällä tunnistetaan tietokantojen relaatio, eli vuorovaikutussuhde toistensa välillä ja tätä kautta tieto kulkee taulujen välillä.
  • Relaatioviivat taulujen välillä = Relaatioviivat ilmaisevat suhdetta tietokantojen välillä. Merkintätavoista dokumentaatiota.

users taulu:

User (käyttäjä)-taululla on suhde muihin tauluihin niin, että käyttäjiä voi olla vaikka kuinka monta, mutta yhdellä käyttäjällä voi olla vain yksi suhde eri tauluihin. Yksilötunniste-ID:n lisäksi User-taulussa pakollisesti täytettävinä kenttinä on 'username' (käyttäjätunnus), 'email' (sähköposti) ja 'pw_hash' (salasanan hash).

Tämä tarkoittaa siis käytännössä sitä, että henkilön henkilötiedoista ei tietokantaan tallenneta mitään yksityistietoon liittyvää dataa ja salasana on suojattu hash-toiminnolla, eli salasanan ns. dekoodaus-metodilla, jossa yksittäiset merkkijonon kirjaimet ja numerot käännetään satunnaisiksi merkkijonoiksi. Näin olla salasana salauksen purkaminen mahdolliselta haittakäyttäjältä on erittäin hankalaa. Lisätietoa Hash-periaatteesta löytyy PhP:n sivustolta, sekä wikipedia. Muut kohdat on jätetty tyhjiksi, eli niihin ei välttämättä tarvitse laittaa mitään dataa.

plans taulu:

Plans (suunnitelma) taulussa on user-taulusta monen suhde vain yhteen käyttäjään ja vierasavaintunnisteena (foreign key) on users_id, mikä siis tunnistaa käyttäjän ID:n silloin kun hän haluaa luoda suunnitelmia käyttäjäliittymässä ja se tieto tallentuu relaatiotietokantaan. Muut kentät jätetään tyhjiksi, koska olettamuksena ei ole tarvetta täyttää suunnitelmista mitään ellei käyttäjä itse erikseen halua kirjata ylös niitä.

Sen lisäksi sillä on liitos planshaslocations-välitauluun, jota käytetään tietokannan tiedon kommunikoinnissa. Se ei tarvitse kuin vain yhden suhteen käyttäjään eikä mihinkään muuhun, koska suunnitelmia ei voi tehdä ilman käyttäjää ja sen tietokannan yksilötunnistetta (data pitää voida tallettaa ja hakea uudestaan tarvittaessa).

reports taulu:

Reports-tauluun tulee monta suhdetta users-ja locations-taulusta, mutta reports-taulusta ei tarvitse mennä kuin vain yksi suhde user- ja locations-tauluihin. Useita raportteja voi siis tulla käyttäjiltä ja sijainneista. Kentät ovat kuitenkin oletuksena tyhjiä, koska raportteja lisätään vain tarvittaessa tietokantaan, eikä ole tarpeellista täyttää mitään kentistä vaadittavina.

Koska raportit ovat vain dokumentteja tapahtuneesta, eikä sitä näytetä julkisesti palvelussa itsessään, se ei tarvitse minkäänlaista suhdetta suunnitelmiin 'plans' tai latauksiin 'uploads'. Koska 'reports' -tauluun tulee suhde 'users' ja 'locations' -tauluista, on sillä tunnistamiseen tarvittavat vierasavaimet 'locations_id' ja 'users_id'.

locations taulu:

Locations (sijainti) tauluun kirjataan retkikohteista dataa. Siitä lähtee yhden suhde moneen reports-, uploads- ja plans_has_locations -tauluihin. Tämä johtuu siitä, että yhdestä sijainnista voi olla monta raporttia ja ladattuja tiedostoja (kuten kuvia), ja välitauluun plans_has_locations syntyy aina yksi tai moneen suhde eri ID yksilötunnisteille. Tässä taulussa pakollisia sisällön kenttiä ovat 'location_data', 'name', 'description' ja 'created'.

Retkikohteen kannalta on välttämätöntä, että taulusta löytyy sijainnin data (koordinaatisto) näkyäkseen kartalla. Retkikohteella on oltava nimi, jotta käyttäjä tunnistaa mikä retkikohde on kyseessä ja sillä on oltava kuvaus, jotta karttapalveluohjelmassa voidaan laittaa edes jokin tunniste retkikohteen tyypille. Luontipäiväystä tarvitaan tiedon lisäyksen tunnistautumiselle. Päivityssolu 'updated' on valinnainen, sillä päivitystä ei aina ole tai sitä ei ole tarpeellista kirjata, esimerkiksi uuden retkikohteen lisäämisessä palveluun. Koska sijainti ei ole yksilö, se ei tee suunnitelmia 'plans', eivätkä käyttäjät 'users' luo retkikohteita.

uploads taulu:

Uploads (lataukset) -taulussa on vähintään yhden tai monen suhde vain yhteen tauluun, joko 'users' tai 'locations' -tauluun ja siksi sillä on myös vierasavaimet 'locations_id' ja 'users_id'. Tämä siksi, että yhdellä käyttäjällä 'users' voi olla yksi tai monta latausta yhdestä tai useammasta retkikohteesta (kuten kuva tiedostoja) ja yhdestä retkikohteesta 'locations' voi olla yksi tai useampia latauksia tietokantaan.

Tietokannan kentät ovat kuitenkin oletuksella tyhjiä, sillä ne eivät ole käyttäjän tai sijainnin kannalta pakollisia käytön toiminnan kannalta. Ne ovat vain mukava graafinen lisä. Koska 'upload' taulu on puhtaasti käyttäjien tai sijaintien sisältöä, se ei tarvitse suhdetta 'plans' -tauluun tai 'reports' -tauluun, sillä lataukset eivät ole minkäänmuotoisia käyttäjiä, joilla voisi olla tarve raporttien tai suunnitelmien luomiseen.

Teknisiä piirteitä relaatiotietokannasta

  • Tilavaatimus on alussa minimaalinen, sen koko on riippuvainen suoraan relaatiotietokannan sisällön tietomäärästä. Jokainen tieto vie tilaa, joten palvelimen kapasiteetti on ylimitoitettava niin, että tilaa on enemmän kuin käyttöä jolloin ei tule tilaongelmia ja palveluongelmia palvelimen kanssa.
  • Ylläpidon näkökohdille relaatiotietokannassa on relaatiotietokantaa ylläpitävä taho, jolla on valtuudet tietokannan muokkaamiselle tarvittaessa. Ylläpitäjä voi syöttää, editoida ja poistaa tietoa vapaasti. Muussa tapauksessa ainut tallennettu tieto on ei yksilöivää tietoa.
  • Varmistusnäkökohdiksi on asetettu mm. tiedon yheyttä ylläpitävät vierasvain määritelmät.
  • Suojausnäkökohdiksi salasanoihin käytetään Hash-metodologiaa, ja tiedon eheyden suojaus on relaatiotietokannan vierasavaimilla ja tietotyyppien määrityksillä suojattu.

Lisätietoa ylläpitämisestä:

3.4 Virhe- ja poikkeusmenettelyt

Tietokannassa yleisiä virheitä tulee esimerkiksi relaatiotietokannan tiedon syötteessä, eli kun uutta tietoa lisätään. MySQl on siinä mielessä kätevä tietokantavaihtoehto, että se automaattisesti kertoo, missä vika on ja suurinpiirtein, mikä kyseinen vika syntaksissa on. Esimerkiksi väärää tietotyyppiä syöttäessä MySQL palauttaa virheilmoituksen, esimerkiksi mysql ERROR 1366 (HY800): Incorrect integer value: 'null' for column 'columname' at row 1 eli väärä kokonaisluvun määrä kolumniin, joka ei voi olla tyhjä 'null' rivillä 1. MySQL ei anna syöttää tietoa tietokantaan jos käyttäjä ei ole ylläpitäjä tai jos MySQL-syntaksi ei ole oikein. Eli mitään tietoa ei voida syöttää sisälle, ennen kuin MySQL syntaksi on oikein. Tästä syystä MySQl on usein käytetty relaatiotietokantatyyppi IT-teollisuudessa.

  • Virheilmoitustieto saadaan näkyville tämän dokumentaation ohjeistuksen avulla.
  • Virheistä vakavin voi olla haitallisen tiedon tallennus tietokantaan. Tietokannan palauttamiseksi voi käyttää tätä dokumentaatiota.
  • Virheilmoitusten tallennus tapahtuu ensisijaisesti muistiin, ellei erikseen ole määritelty erillisille levylle. Sitä ei tässä projektissa sen enempää käsitellä, kumpi on parempi toteutusvaihtoehto lopullisessa tuotteessa.
  • Koska kyseessä on ohjelmisto, jossa ainoa tietoturvallisesti uhkaava yksityinen tieto on käyttäjä, ovat käyttäjätiedon virheilmoitukset vakavampia kuin muut järjestelmän ilmoitukset.
  • Käyttäjätiedoista kuitenkin on suojattu salasana eikä relaatiotietokantaan pääse käsiksi ulkopuolinen ilman tietokannan kräkkäämistä, ja yksilöivä tieto on salattu hash-metodologialla, eli relaatiotietokanta on suunniteltu kyberturvalliseksi.
  • Relaatiotietokannan ei pitäisi jumittua yleensä. Poikkeuksena voi olla liiallien tietoverkkoliikenne, DDOS hyökkäys tai jokin muu vastaava tilanne. DDOS ei auta muu kuin suojata tietokanta ja purkaa hyökkäyksen solmu mahdollisimman pian, siltä ei voi ennaltaehkäistä kokonaan. Tietoverkkoliikenteen ruuhkautumista ennaltaehkäistään ylimitoittamalla palvelinkapasitettin määrää ja seuraamalla aktiivikäytön ja palvelinkapasiteetin yleistilannetta. Tarvittaessa lisätilaa on hankittava lisää. Projektissa käytetty Docker kontti moduulimetodi mahdollistaa palvelimen migraation.

4. MODUULI /LUOKKA/PROSESSI-KUVAUKSET

Tämä kappale dokumenttia käsittelee projektin moduuleita.

4.1 Moduuli: meijän-metsät-back

Ohjelmiston bisneslogiikasta ja asiakaskäyttäjälle yleisesti näkymättömien back-end taustatoimintojen määrittelevät tiedostot meijän-metsät-back luo toiminnallisuuden kannalta vaadittavia tiedostomääritelmiä, reittiohjeistuksia ja muita bisneslogiikalle tarpeellisia toimintoja, määritelmiä ja muita.

4.1.1 Yleiskuvaus

public/stylesheets - kansio

Moduulin nimi: style.css
Moduulin tyyppi: Kirjasto
Yleiskuvaus: tyylimäärittely virheilmoituksille.
Asiakkaat: Ei suoranaista vaikutusta, ellei kohdata virhettä ohjelmistossa.
Riippuvuudet ja liittymät muihin moduuleihin: Virhekäsittelyt moottorissa.

ruotes - kansio

Moduulin nimi: lipas.js
Moduulin tyyppi: Alijärjestelmä
Yleiskuvaus: Määrittelee ohjelmistossa reitin, jotakautta tieto kulkee ohjelmistotuotteessa.
Asiakkaat: Ei suoranaista vaikutusta.
Riippuvuudet ja liittymät muihin moduuleihin: Vaadittava, jotta datan kuljetus ja rajapinnan ja palvelun välinen kommunikaatio toimii oikein.

test - kansio

Moduulin nimi: test.js
Moduulin tyyppi: Alijärjestelmä
Yleiskuvaus: Reitin tomivuuden testaukseen käytetty tiedosto. Voidaan varmistaa tiedonkulku oikein.
Asiakkaat: Ei vaikutusta.
Riippuvuudet ja liittymät muihin moduuleihin: Ei vakutusta.

views - kansio

Moduulin nimi: error.pug
Moduulin tyyppi: Alijärjestelmä
Yleiskuvaus: Määrittelee virheilmoituksen tyylimuotoilun.
Asiakkaat: Ei suoranaista vaiktusta, ellei virheilmoitusta tule käytön aikana.
Riippuvuudet ja liittymät muihin moduuleihin: Ainoastaan layout.pug ja undex.pug.

Moduulin nimi: index.pug
Moduulin tyyppi: Alijärjestelmä
Yleiskuvaus: Indeksissä näkyvä aloitusviesti, eli käynnistysviesti.
Asiakkaat: Ei suoranaista vaikutusta, ellei virheilmoitusta tule käytön aikana.
Riippuvuudet ja liittymät muihin moduuleihin: Ainoastaan layout.pug.

Moduulin nimi: layout.pug
Moduulin tyyppi: alijärjestelmä
Yleiskuvaus: Muotoilee virheilmoituksen rakenteen muotoilun.
Asiakkaat: Ei suoranaista vaikutusta, ellei virheilmoitusta tule käytön aikana.
Riippuvuudet ja liittymät muihin moduuleihin: Express.js luodessa automaatttisesti generoituva virheilmoitusformaatti moottorille.

Yleiset muut moduulit

Moduulin nimi: .node-version
Moduulin tyyppi: Funktio
Yleiskuvaus: Määrittelee mitä Node.js versiota ohjelmistotuote käyttää.
Asiakkaat: Ei suoranaista vaikutusta.
Riippuvuudet ja liittymät muihin moduuleihin: Vaadittava, jotta ohjelmistossa käytetty Node.js tiedostoja voidaan lukea oikealla tavalla ilman rikkoutumista.

Moduulin nimi: Dockerfile
Moduulin tyyppi: Funkltio
Yleiskuvaus: Suorittaa Javascripti tiedostojen suorittamisessa vaadittavan npm pakettimanageri työkalun asennuksen jos on tarvetta ja ajamiskomennon automaattisesti.
Asiakkaat: Ei suoranaista vaikutusta, ellei käyttäjältä puutu npm jolloin komponentti on kriittinen.
Riippuvuudet ja liittymät muihin moduuleihin: Vaadittava, jotta ohjelmisto pystyy lukemaan Javascript .js tiedostoja. Yleensä tulee automaattisesti jokaisessa käyttöliittymässä asennettuna.

Moduulin nimi: app.js
Moduulin tyyppi: Alijärjestelmä/proxy
Yleiskuvaus: Määrittelee ulkopuoliselle rajapinnalle mitä porttia käytetään ja mitä kutsuja rajapinnasta tehdään.
Asiakkaat: Ei suoranaista vaikutusta.
Riippuvuudet ja liittymät muihin moduuleihin: Vaadittava, jotta karttapalvelussa näkyy muutakin dataa kuin pelkästään kartta ja käyttäjä (jos on sisäänkirjautunut palveluun).

Moduulin nimi: package.json
Moduulin tyyppi: Pakkaus
Yleiskuvaus: Määrittelee ohjelmistossa käytettäviä riippuvuuksia, kuten session keksejä (eng. cookies) versiota.
Asiakkaat: Sessiotietojen tallennus, muistaa mitä tietoja on syötetty ja tallennettu edellisellä sessiolla. Ei tarvitse erikseen kirjoittaa uudestaan jos ei halua.
Riippuvuudet ja liittymät muihin moduuleihin: Riippuvuuksia ohjelmiston versionhallintaan, virhekäsittelyyn ja sessionhallintaan.

4.1.2 Rajapinta yleisesti

Moduuli määrittelee ohjelmistopalvelutuotteelle ns. back-end määritelmiä, joiden avulla asiakaskäyttäjät voivat sitten suorittaa kyselyitä ja erilaisia toimintoja käytön aikana. Tällaisia kyselyitä voivat olla mm. API-rajapinnan lipas.fi kautta haettavien retkikohteiden tiedot karttapalveluun. Huomoitavaa on se, että palvelusta saa kerrallaan hakukyselyyn vain 50 hakukyselyn tulosta, mikä on toiminnallisesti aika vähän.

Tapahtumaketjua kuvaava sekvenssikaavio:

Yllä olevassa sekvenssikaaviossa kuvataan siis sitä ketjua, jonka järjestelmä suorittaa kun asiakas käyttää Meijän Metsät palvelua. Meijän Metsät palvelu saa palvelupyynnön käyttäjältä. Tämän tässä tapauksessa hakupyynnön se ohjaa edelleen ulos portista 3001 lipas.fi palvelun rajapintaan, josta haetaan kartalle piirrettävien retkikohteiden dataa Meijän Metsät palveluun.

Mikäli hakupyynnössä on kaikki OK, lipas.fi suorittaa omalta palvelimeltaan haettavan datan ja palauttaa saadun datan eteenpäin. Jos hakupyyntö oli sopiva, lipas.fi palauttaa haetun datan Meijän Metsätu palvelun kyselyyn takaisin ja Meijän polku -palvelu näyttää käyttäjälle tämän hakemansa hakutuloksen. Mikäli kysely ei ole sopiva, palauttaa tämä virhetiedon Meijän Metsät -palveluun ja tämä näyttää kyseisen tuloksen käyttäjälle. Esimerkiksi jos käyttäjä olisi syöttänyt hakukenttään retkikohdepaikan, jollaista ei löydy lipas.fi -rajapinnan tietokannasta.

4.1.3 Rajapintafunktiot

Tässä kuvataan erikseen omassa alakohdassaan jokainen rajapintafunk-tio:

/Routes/lipas.js

Funktion parametrit ja paluuarvo:

  • router.get & res.send lähettää resurssipyynnön eteenpäin ja saa takaisin express.js vaaditut tiedostot.

Toiminta:

  • var express = require('express'), vaatii, että express.js resurssit on mukana.
  • var router = express.Router(), reitittää tiedonvälityksen kulkuväylän.
  • router.get = lähettää tämän resurssipyynnön eteenpäin.
  • res.send = pyytää resurssia.
  • module.exports = router; kertoo mistä muuttujasta funktio voi viedä resurssinhakupyynnön.
  • Esiehdot: Ohjelmistolla on oltava yhteys tietoverkkoon, josta express.js resurssit voidaan hakea ohjelmiston asennuksessa.
  • Jälkiehdot: Ohjelma toimii kuten pitääkin ja pystyy suorittamaan sille vaadittavia rajapintakutsuja.
  • Virhetilanteet: 404 virhekoodi jos käyttäjällä ei ole yhteyttä tietoverkkoon. 504 virhekoodi jos palvelinrajapinta ei vastaa.

app.js

Funktion parametrit ja paluuarvo:

  • const express = tutkii löytyykö ohjelmiston asennuksen yhteydessä vaadittu express.js ja paluuarvona totuusarvon: kyllä tai ei.
  • cont request = tutkii löytyykö ohjelmistosta parametria 'request' ja palauttaa totuusarvon: kyllä tai ei.
  • app.use((req, res, next) = lähettää rajapintojen kommunikaatiolinkkinä toimivan Access-Control-Allow-Origin headerin ja paluuarvona saa varmistuksen onnistuneesta linkistä.
  • app.get("/lipas-api/", (req, res) = Hakee lipas.fi rajapinnasta yleistä dataa ja paluuarvonaan saa rajapinnan yleistä tietoa.
  • app.get("/lipas-api/places/", (req, res) = Hakee lipas.fi rajapinnasta retkikohteiden dataa ja palauttaa retkikohdedatan Meijän Metsät -palveluun.

Toiminta:

  • const express = require('express'); vakio vaatii express.js -komponentin olemassaoloa ohjelmistossa palvelun kommunikaatiolinkin mahdollistamiseksi.
  • const request = require('request'); vakio vaatii pyyntötoiminnon vastausta hakutoiminnon resurssien hakemisen mahdollistamiseksi.
  • app.get => res.send, app.listen => console.log = Tiedonvälityskommunikaation testaukseksi käytetty "Hello World", varmistetaan, että kommunikaatio toimii.
  • app.use => res.headerres.header("Access-Control-Allow-Origin", "*"), next; ohjelmisto käyttää CORS -headeria
    pyytämään reittitietoja haetun datan sijainneista rajapinnasta.
  • app.get("/lipas-api/", (req, res) lukee yleisen datan hakukyselyn parametrit req ja res.
  • const url = http://lipas.cc.jyu.fi/api/sports-places?${req.query["type"]}, kertoo mistä sijainnista data haetaan ja millainen hakukysely
    lipas.fi rajapinnasta haetaan.
  • request(url).pipe(res), ohjaa hakukyseln lipas.fi IEX API -rajapintaan ja välittää tiedon eteenpäin.
  • app.get("/lipas-api/places/", (req, res), hakee retkikohteiden dataa lipas.fi rajapinnan API:sta.
  • const url = http://lipas.cc.jyu.fi/api/sports-places/${req.query["type"]}, suorittaa hakukyselyn retkikohteiden datalle.
  • request(url).pipe(res), ohjaa hakukyselyn lipas.fi IEX API -rajapintaan ja välittää tiedon eteenpäin.

4.1.4 Moduulin toteutus

  • Kokonaisrakenteeltaan meijän-metsät-back -moduuli on minimaalinen ja loogisesti rakennettu ja kommunikaatiolinkki on nopea, tehokas ja suora.
  • Algoritmit tekevät peruskyselyita ja niissä ei ole huomioitu mitään vaativampia resurssipyyntöjä.
  • Komponentteja voi käyttää uudelleen, mutta yleinen hyvä standardikäytäntö on se, että kyselyiden tulosten muokkaus ja muu back-end toiminnallisuuden manipulointi tehdään muualla kuin resurssien tiedonvälityksessä ja rajapintojen kommunikaatioissa tiedon koheesion, eli eheyden ja autenttisuuden säilyttämiseksi.

4.1.5 Virhekäsittely

Virheet tilanteista tulevat syötteenä sekä virheilmoitusviesti, että konsoliin logitiedostot mikä virheilmoitustyyppi on ollut kyseessä. Poikkeuskäsittelyt tapahtuvat varmenteiden avulla, jossa tsekataan tapahtuuko poikkeuksia tai virheitä ja mitään komentoa ei ajeta lopullisesti ennenkuin varmenteen tarkistus näyttää tiedon koheesion, eli eheyden, olevan OK ja komento voidaan turvallisesti ajaa. Muussa tapauksessa syötteeseen tulee virheilmoitus ja luodaan logitiedot tapahtumasta.

4.2 Moduuli: meijän-metsät-web

Ohjelmiston käyttäjäliittymästä vastaava kokonaisuus. Täällä näkyy ohjelmistorakenteessa standardina käytetyn Model-View-ViewModel, eli MVVM, näkymäosiota, eli sitä osuutta mitä käyttäjä tulee näkemään ja minkä kanssa käyttäjä kommunikoi interaktiivisesti käyttäessään tuotetta ja saadessaan käytön syötteistä palautusarvoina näkymän muutoksia.

4.2.1 Yleiskuvaus

public - kansio

Moduulin nimi: index.html
Moduulin tyyppi: Prosessi
Yleiskuvaus: Meijän Metsät -palvelun aloitusnäkymä.
Asiakkaat: Suurin osa ohjelmiston komponenteista on riippuvaisia tästä komponentista.
Riippuvuudet ja liittymät muihin moduuleihin: Riippuvainen meijän-metsät-back moduuleista ja src-kansion tiedostoista.

Moduulin nimi: manifest.json
Moduulin tyyppi: Kirjasto
Yleiskuvaus: Määrittelee eri näkymien logoja.
Asiakkaat: Aloitusnäkymät, yleisnäkymät.
Riippuvuudet ja liittymät muihin moduuleihin: Ainoastaan tyylitiedostoista, eli hakee sijaintinsa .css -tiedostoista.

Moduulin nimi: robots.txt
Moduulin tyyppi: Funktio
Yleiskuvaus: Kieltää robottien pääsemisen ohjelmistoon. Tällä torjutaan haitallisten bottien pääsyä ohjelmistotuotteeseen, eli se on yksi kyberturvallisuuden laadunvarmistuksen tiedosto.
Asiakkaat: Tiedon kommunikaatiosta ja tallennettavan tiedon säilytyksestä vastaavat tiedostot.
Riippuvuudet ja liittymät muihin moduuleihin: Ei mitenkään. Robot.txt on itsenäinen, se ei riipu muista, mutta muutama tiedosto riippuu myös siitäkin.

src-kansio

src/Components - alikansio

Moduulin nimi: AdvSearch.js
Moduulin tyyppi: Luokka
Yleiskuvaus: Määrittelee hakutoiminnon muotoilun ja toiminnallisuuden näkymän.
Asiakkaat: Hakutoimintoa suoddatavat komponentit.
Riippuvuudet ja liittymät muihin moduuleihin: Hyödyntää tyylitiedostoja, hakukyselyistä vastaavista komponenteista ja näyttämisen views vastaavista komponenteista.

Moduulin nimi: AppContainer.js
Moduulin tyyppi: Alijärjestelmä
Yleiskuvaus: Koostaa koko näkymän rakenteen käyttäjälle, eli missä kohti näkyy kartta, missä kohti näkyy hakutoiminto ja niin edespäin.
Asiakkaat: Hakykyselyä suorittavat komponentit tarvitsevat haun tarkennuksen kyselyvaihtoehtojen tietoja hakukyselyn filtteröintiin.
Riippuvuudet ja liittymät muihin moduuleihin: Hyödyntää meijän-metsät-backia ja eri rajapintoja kuten lipas.fi tiedon hakemiseen.

Moduulin nimi: InfoCard.js
Moduulin tyyppi: Luokka
Yleiskuvaus: Määrittelee hakubaarissa näkyvien retkikohteiden yksittäisiä kortteja, tämän avulla retkikohteiden lisääminen yhteiseen selkeään formaattiin on vaivatonta.
Asiakkaat: Ei suoranaista vaikutusta. Tämä komponentti riippuu ainoastaan sille saamista resursseista.
Riippuvuudet ja liittymät muihin moduuleihin: Riippuu ainoastaan sille saadusta syötteestä kun uusi retkikohde syötetään tietokantaan ja sille annetuista resursseista.

Moduulin nimi: InfoPanel.js
Moduulin tyyppi: Luokka
Yleiskuvaus: Näyttää yksittäisen retkikohteen tarkempaa tietoa.
Asiakkaat: Ei mitkään. Komponentti itse on riippuvainen muista rajapinnoista.
Riippuvuudet ja liittymät muihin moduuleihin: Yksityiskohtaisemman tiedon kuljetuksesta rajapinnoista vastaavat tiedostot ja kyseiset rajapinnat.

Moduulin nimi: Login.js
Moduulin tyyppi: Luokka
Yleiskuvaus: Sisäänkirjautumisesta vastaava moduuli.
Asiakkaat: Relaatiotietokannan moduulit silloin kun uusi käyttäjätieto syötetään tai käyttäjätietoa muokataan. Kuvien lisäämistä vastaava moduuli vaatii sisäänkirjautumisen.
Riippuvuudet ja liittymät muihin moduuleihin: Riippuvainen relaatiotietkonannasta vastaavasta moduulista.

Moduulin nimi: MeijänMetsätMap.js
Moduulin tyyppi: Luokka
Yleiskuvaus: Kartan piirtämisen moduuli. Piirtää siis ohjelmistotuotteessa kartan näkymän ja kartalle näkyvät retkikohteet.
Asiakkaat: Yksi keskeisimmistä näkymistä. Esimerkiksi hakukysely-toiminnon syötteen tuloksen näyttö on riippuvainen tästä kartan piirtämisen näkymästä.
Riippuvuudet ja liittymät muihin moduuleihin: Riippuvainen karttapalvelun pohjana käytettävästä rajapinnasta, kuten myös muista kartan piirtoon vaadittavan datan syöttävistä rajapinnoista.

Moduulin nimi: SideBar.js
Moduulin tyyppi: Luokka
Yleiskuvaus: Määrittelee hakubaarin rakenteen.
Asiakkaat: Ei suoranaisesti mitkään muut kuin tyylitiedostot, eli .css tiedostot ja InfoCard.js ja InfoPanel.js luokat, sekä assosioivat resurssit kuten kuvakkeet.
Riippuvuudet ja liittymät muihin moduuleihin: Ainoastaan riippuvainen .css tyylitiedostoista.

Moduulin nimi: components.module.css
Moduulin tyyppi: Kirjasto
Yleiskuvaus: Ohjelmiston pääikkunan näkymän tyylimäärittelyt. Määrittelee siis ohjelmiston päänäkymän ulkoasun.
Asiakkaat: Päänäkymän tiedostot, eli Component kansion tiedost ovat riippuvaisia tämän tiedoston tyylimuotoilusta. Toiminnallisuuten ei suoranaisesti vaikuta, mutta käytön mukavuuteen vaikuttaa.
Riippuvuudet ja liittymät muihin moduuleihin: Ei ole riippuvainen muista. Edes käyttämättömät tyylitiedostot eivät tee mitään, koska niitä ei kutsuta missään.

src/img - alikansio

Moduulin nimi: /img/ - kansio
Moduulin tyyppi: Kirjasto
Yleiskuvaus: Sisältää useampia kansioita ja yleisiä tiedostoja, mutta kaikki tiedostot ovat ohjelmistossa käytettyjä kuvakkeita.
Asiakkaat: Components alikansio on riippuvainen tästä, sillä siellä ilmenevät kuvakkeet haetaan tästä alikansiosta.
Riippuvuudet ja liittymät muihin moduuleihin: Ei riippuvuutta muihin tiedostoihin. Käyttämättä jääneitä kuvakkeita ei käytetä ilman kutsua niihin, ne vievät vain turhaa tilaa.

src/yleisesti - alitiedostot

Moduulin nimi: App.css
Moduulin tyyppi: Kirjasto
Yleiskuvaus: Määrittelee index.html aloitusikkuna-näkymän tyylin.
Asiakkaat: Aloitusikkuna-näkymä index.html ulkoasu on riippuvainen tästä tiedostosta.
Riippuvuudet ja liittymät muihin moduuleihin: Ei riippuvuuksia muihin. Tyylitiedostot näkyvät vain jos niitä kutsutaan muualla.

Moduulin nimi: App.js
Moduulin tyyppi: Luokka
Yleiskuvaus: Hakee ja luo ohjelmistosta Docker kottiin moduulin.
Asiakkaat: Ei suoranaista vaikutusta. Tämä kehystää ohjelmiston ja sen sisälle rakentuu koko ohjelma.
Riippuvuudet ja liittymät muihin moduuleihin: Riippuvainen Docker container resursseista.

Moduulin nimi: App.test.js
Moduulin tyyppi: Prosessi
Yleiskuvaus: Docker-kontin testaukseen käytetty tiedosto.
Asiakkaat: Ei vaikutusta.
Riippuvuudet ja liittymät muihin moduuleihin: Ei riippuvuuksia.

Moduulin nimi: Lipas.js
Moduulin tyyppi: Prosessi
Yleiskuvaus: Hakee ja suorittaa resurssikyselyitä lipas.fi API rajapinnasta ja ohjaa tuloksen syötteen eteenpäin Meijän Metsät palvelun komponentteihin.
Asiakkaat: Bisneslogiikan meijän-metsät-back moduulissa oleva app.js tarvitsee tätä tiedostoa ohjatakseen tietoa kommunikaatiolinkissä ja saadakseen kyselyitä ohjattavaksi.
Riippuvuudet ja liittymät muihin moduuleihin: Riippuvainen bisneslogiikan meijän-metsät-back app.js tiedostosta, rajapinnoista, sekä MeijänMetsätApp.js näkymään tehdyistä hakukyselyn rajauksen valinnoista.

Moduulin nimi: index.css
Moduulin tyyppi: Kirjasto
Yleiskuvaus: Tyylitiedosto, joka määrittelee koko ohjelmistossa käytetyn tekstin muotoilusta.
Asiakkaat: Kaikki näkymät, eli meijän-metsät-web moduulin näkymistä vastaavat tiedostot.
Riippuvuudet ja liittymät muihin moduuleihin: Tyylitiedostona ei ole riippuvainen muista tiedostoista.

Moduulin nimi: index.js
Moduulin tyyppi: Funktio
Yleiskuvaus: Mahdollistaa index.html:n interaktiivisen toiminnallisuuden, eli syöte myös palauttaa jonkin arvon käyttäjän näkymään.
Asiakkaat: Aloitusikkunan index.html vaatii tämän tehdäkseen mitään interaktiivisuutta vaativaa toiminnallisuutta.
Riippuvuudet ja liittymät muihin moduuleihin: Ei suoranaista riippuvuutta.

4.2.2 Rajapinta yleisesti

Moduuli meijän-metsät-web kokonaisuudessaan tarjoaa näkymät ja näkymien kommunikaation käsittelyä asiakkaille. Se sisältää mm. hakutoiminnon kyselyn rajaamisen ja kohdentamisen sille syötetyn hakurajauksen perusteella, ja piirtää tämän syötteen tuloksen kartalle näkyville. Moduuli hyödyntää samaa tapahtumaketjua kuin aiemmassakin moduulissa käytetty tapahtumaketjukuvaus. Ainoastaan erona on se, että tämä moduuli vastaa käyttäjän syötteestä, sekä palautteen näyttämisestä käyttäjälle takaisin kun ohjelmisto on saanut vastauksena haetut resurssit. Kapasiteettirajoituksena lipas.fi on ainoastaan se, että sieltä voi saada maksimissaan 50 retkihakukohdetta kerrallaan.

4.2.3 Rajapintafunktiot

AppContainer.js

Toiminta:

  • shouldComponentUpdate(nextState) = Tarkistaa ja vertailee tarvitseeko komponentin päivittää tietoa karttanäkymässä. Jos tarvitsee, päivittää komponentin.
  • componentDidMount() = Avaa tietyn sille määritellyn yhteyden kommunikaatiolle sen yhteyden ajaksi.
  • dataReady(data) = Kertoo mihin data asetetaan, tässä tapauksessa kyseiseen muuttujaan.
  • componentWillUpdate() = Päivittää karttanäkymää.

4.2.4 Moduulin toteutus

  • Rakenteeltaan pääsäntöisesti moduuli tekee sen mitä sen pitää tehdä ja se on moduloitu eri komponentteihin, jotka kommunikoivat keskenään, mutta ovat kestävämpi kokonaisuus silloin kun jokin komponentti hajoaa. Tämä on yksi modulaarisen ohjelmoinnin eduista.
  • Näkymien komponentteja kuten InfoCard.js ja SideBar.js voidaan käyttää uudestaan ja erityisesti InfoCard.js komponenttia käytetään uudestaan joka kerta kun uusi retkikohde lisätään.

4.2.5 Virhekäsittely

Virheilmoituksia käsitellään poikkeuskäsittelijöiden avulla ja serviceWorker.js tiedoston avulla. Mikäli vastaan tulee jokin virhe tai poikkeuskäsittelyn tarve, siitä lähetetään käyttäjälle näkymään suoraan syötteenä virheilmoitus. Samat virheilmoitukset vielä kirjoitetaan logiin, jotta ylläpitäjät voivat tarkistaa missä kyseinen vika on ilmentynyt ja millainen virhe on kyseessä.

5. VALMISOSAT JA ERITYISET TEKNISET RATKAISUT

Mikäli on valmisosia eli ulkopuolisia komponentteja, niin sellaisista selostetaan:

npm.js, express.js & node.js

express.js

  • Sijoitus tapahtuu portin 3001 kautta, jossa rajapinnan ja Meijän Metsät ohjelmiston välinen kommunikaatio tapahtuu.

lipas.fi API rajapinta

  • meijän-metsät-web/Lipas.js, hakee lipas.fi rajapinnan kautta dataa Meijän Metsät karttapalveluun.
  • Data sijoitetaan karttanäkymän palautesyötteeseen, eli saatu data piirretään kartalle tai näytetään infolaatikkoon saatu tieto.
  • Käytetään datan näyttämisen eri toimintoihin.

6. HYLÄTYT RATKAISUVAIHTOEHDOT

Mietityt, mutta hylätyt ratkaisuvaihtoehdot:

  • Sään näyttäminen: Sään näyttäminen osana Meijän Metsät ohjelmistoa olisi hyvä idea lisäyksenä palveluun. Käyttäjä hyötyisi säätiedon näkemisestä suoraan silloin kun hän olisi juuri lähdössä haluamaansa haettuun retkikohteeseen.

  • Julkisen liikenteen tietojen näyttäminen: Julkisen liikenteen tietojen näyttäminen olisi hyvä lisä palveluun. Sen avulla henkilö voisi tarkistaa julkisen liikenteen aikatauluja suoraan ilman erillistä tarvetta kolmannen osapuolen palveluihin.

  • Kulkuväylien ja reittien piirtäminen ohjelmistossa: Tämä toiminto näyttäisi suoraan GPS-mallin mukaisesti mitä kautta helpoiten voisi päästä retkikohteelle. Bonuksena vielä jos siinä voisi rajata erikseen millaista kulkuvälinettä käytetään, esimerkiksi kävellen tai autolla. Piirtäisi tiet tai jalkakäytäväreitit hakusijainnista retkikohteeseen.

  • Omien kuvien lisääminen: Omien kuvien lisääminen oli alunperin suunniteltu toteutettavaksi ominaisuudeksi. Asiakkaan kuvien lisääminen retkikohteista on kuitenkin hyvä ominaisuus, sillä se luo yhteisöllisyyttä ja täten lisää ohjelmistotuotteen käyttöä.

  • Käyttäjän sijainnin keskittäminen: Joskus karttaa selaillessa tulee kuljettua aika pitkälle ja oman tämänhetkisen sijainnin voi helposti kadottaa reittien tutkimisen varrella. Kätevää käyttäjälle olisi yksinkertainen nappi karttasovelluksessa, joka palauttaisi näkymän takaisin omaan tämänhetkiseen sijaintiin tarvittaessa.

  • Käyttäjän suunnan näyttäminen: Ominaisuutena se toimisi vain mobiililaitteissa, mutta niissä se hyödyntäisi jokaiseen kännykkään nykyään sisäänrakennettua GPS-tunnistinta, jonka avulla ohjelmistopalvelu voisi näyttää mihin suuntaan henkilö seisoo kännykkä kädessään. Tämnä siksi, että se helpottaa suunnistamista ja paikantamista kartaa lukiessa.

  • Retkikohteiden luonnonhistoriallisten tietojen näyttäminen: Joskus retkellä ollessaan käyttäjät haluavat saada yksityiskohtaista tietoa retkikohteestaan.

7. JATKOKEHITYSAJATUKSIA

  1. Säätietojen haku ja säätietojen syötteen näyttö suoraan ohjelmistopalvelussa. Ratkaisuvaihtoehto hylättiin ajan ja resurssien puutteen takia.
  2. Julkisen liikenteen aikataulujen ja reittihakujen hakeminen suoraan ohjelmistopalvelussa. Ratkaisuvaihtoehto hylättiin ajan ja resurssien puutteen takia.
  3. Kulkuväylien ja reittien piirtäminen ohjelmistossa. Ratkaisuvaihtoehto hylättiin ajan ja resurssien puutteen takia.
  4. Omien kuvien lisääminen ohjelmistopalveluun. Ratkaisyvaihtoehto hylättiin ajan ja resurssien puutteen takia.
  5. Oman sijainnin keskittäminen. Ratkaisuvaihtoehto hylättiin ajan ja resurssien puutteen takia.
  6. Käyttäjän suunnan näyttäminen. Ratkaisuvaihtoehto hylättiin ajan ja resurssien puutteen takia.
  7. Retkikohteiden luonnollishistoriallisen datan näyttäminen. Ratkaisuvaihtoehto hylättiin ajan ja resurssien puutteen takia.

Lähde

Tämä dokumentin runko pohjautuu http://www.cs.tut.fi/ohj/dokumenttipohjat/pohjat/suunnittelu/hytt_drsuunnittelu.doc

Kiitokset alkuperäisen tekijöille!