developer.e-ehitus.ee

Tehniline arhitektuur

Alates 2018. aasta neljandast kvartalist on planeerimisel olemasoleva Ehitisregistri (EHR) arhitektuuri muudatused ning uue e-ehituse keskkonna arendused, mis lähtuvad käesolevas dokumendis toodud nõuetest.

Käesolev dokument kajastab MKM IT-osakonna ja EHR arendajate poolt tehtud e-ehituse keskkonna arhitektuuri kokkuleppeid. Uutes arendustes tuleb järgida käesolevat dokumenti.

Juhul kui tekib vajadus käesolevas dokumendis toodud nõudeid laiendada või muuta, tuleb selleks eelnevalt saavutada kokkulepe MKM IT-spetsialistidega ning tehtud kokkulepped käesolevasse dokumenti sisse viia.

Arhitektuuri muutmise eesmärk

  1. Lammutada olemasolev monoliitne Javal baseeruv EHR rakendus (edaspidi vana e. olemasolev EHR) osadeks, et
    1. Tagada lõppkasutajatele kiirem töökeskkond (praegune rakendus on tänu keerukusele kohati muutunud väga aeglaseks).
    2. Muuta rakenduse edasiarendamine kiiremaks ja odavamaks (tänase monoliitse rakenduse arendamine nõuab pikka õpiaega, testimine on ajamahukas ja seetõttu on arendused kauakestvad ning kallid).
  2. Tagada uus (edaspidi viidatakse uuel arhitektuuril baseeruvale EHR rakendusele kui uuele EHR-le) ja tehniliselt kaasaegne platvorm e-ehituse kontseptsiooni realiseerimiseks. E-ehituse üks oluline osa on EHR ja seetõttu on vajalik, et EHR tehniline lahendus võimaldaks realiseerida kõiki e-ehituse vajadusi.
  3. Tagada EHR jätkusuutlikkus, võttes arendustes järk järgult kasutusele uusi tehnoloogiaid ja rakenduse käitluskeskkondi nii, et olemasolevaid rakendusi saaks töös hoida, kuni uued need välja vahetavad.
  4. Tagada EHR vastavus kõikidele ISKE klassiga määratud nõuetele.

Uue e-ehituse platvormi tarkvaralise arhitektuuri põhimõtted

  1. Arhitektuur lähtub mikroteenuste kontseptsioonist, ehk plaanis on EHR monoliitrakendus jagada osadeks nii, et iga osa oleks käsitletav eraldi käitatava teenusena. (Mikroteenuse asemel on edaspidi kasutusel sõna teenus).
  2. Olemasolev rakendus on töös senikaua kui uued teenused selle järk järgult välja vahetavad. Uute teenuste arendusel lähtume „brownfield“ arendusmetoodikast, ehk teenuste loomine lähtub olemasolevast tarkvarast ja seetõttu on vajalik, et teenuste arendajad omaksid põhjalikke teadmisi EHR olemasoleva rakenduse kohta.
  3. E-ehituse platvormi tarkvaraline arhitektuur koosneb järgnevatest tasemetest (vt joonis 1):
    1. Kasutajaliides
    2. Veebiserver
    3. Rakendusserver
    4. Andmebaas
Joonis 1. e-ehituse platvormi tarkvaraline arhitektuur

Tasemetest detailsemalt

  1. Kasutajaliides:
    1. Kasutajaliides (User Interface) – lähtub microfrontend põhimõttest ehk kasutajaliides on jaotatud teenuste vahel komponentideks (custom elements). Komponentide laadimiseks kasutame SSI (server side include). Kõikides jagatud komponentides kasutame ühte ja sama jagatud ruuterit (router), et ära hoida komponentide vahel lülitamisel page reload vajadust.
    2. Kõik uued komponendid kasutavad ühtesid ja samasid aluskomponente: JS Polyfills, veateated, monitooring, püsifailide hoidmine.
    3. Kasutajaliidese loomisel kasutame React, HTML, CSS ja JavaScripti viimaseid versioone.
    4. Kasutajaliides luuakse EHR aluskomponentidest.
    5. Kasutajaliidese aluskomponente kasutatakse npm paketist ehr-components. Aluskomponendi arendamisel luuakse uus ehr-components paketi versioon npm paketihoidlassse ning suurendatakse versiooninumbrit vastavalt semver2 standardile.
    6. E-ehituse aluskomponendi loomisel ei tohi muuta esialgseid komponente. Esialgse komponendi alusel tuleb luua uus komponent ning lisada see e-ehituse komponentide projektis “src/ehr_components” folderisse.
    7. E-ehituse kasutajaliides käivitub juurkomponendist, mis asub siin projektis ning kõik uued loodavad komponendid peavad olema integreeritud juurkomponenti.
    8. Juurkomponendis on komponentide infovahetuseks kasutusel Redux pakett.
    9. Komponendid integreeritakse juurkomponenti npm paketina. Komponendi sisenditeks on “React props” ja väljunditeks “render props event”-d. Komponentide sisendid ja väljundid dokumenteeritakse React Styleguidist paketiga.
    10. Kasutajaliidese juurkomponent integreeritakse olemasoleva Java rakendusega linkide kaudu, nii et EHR lingi avamisel käivitatakse juurkomponent ning sellest omakorda uue või vana Java rakenduse lehed (vt allpool joonis 2).
    11. Kasutajaliidese navigeerimiseks kasutame juurkomponendis react-router paketti
    12. Kasutajaliidese stiilid võetakse juurkomponenti integreeritud e-ehituse CSS stiilifailist.
    13. Kasutaliidese stiilide muutmiseks või lisamiseks on e-ehituse stiiliraamat. E-ehituse stiilifail koos stiiliraamatuga asub siin projektis. E-ehituse stiilifaili täiendamisel peab arendaja tagama, et muudatused ei kahjustaks olemasolevate komponentide töötamist. Peale muudatuste sisseviimist tuleb genereerida uus CSS ja integreeridasee e-ehituse juurkomponenti.
    14. Kasutaja õigused kasutajaliidese elementidele leitakse juurkomponendis või vajadusel alamkomponentides, kasutades e-ehituse JWT tokenit (vt. Kasutajaõiguste süsteemi detailanalüüs.
    15. Kasutajaliidese andmevahetuseks andmebaasiga kasutame REST teenustel põhinevat API-t.
    16. Vormi väljade kohustuslikkuse kontrolli ja väljade kuvamise/ täitmise ärireeglid realiseerime võimalusel lehitsejas ja andmebaasi kirjutamisel vastavas API-s.
    17. Kasutajaliidese põhivaated realiseeritakse prototüüpimisel kasutades e-ehituse aluskomponente.
    18. E-ehituse kasutajaliides peab olema testitud enamlevinud lehitsejatega (Chrome, Edge, Firefox, Safari) ja mobiilivaates.
    19. Kasutajaliides peab olema koostatud nii, et autoriseeritud kasutaja saaks muuta html elementide pealkirju, veateated ning abitekste.
    20. Kasutajaliidese tekstid peavad asuma juurkomponendis keelefailides (eesti, inglise).
    21. Lõppkasutajale kuvatavatel html elementidel peavad olema unikaalsed ID-d, et saaks rakendada kasutajaliidese automaattestimist.
    22. Komponentidele luuakse staatiline html, et kuvada komponente ka juhul, kui javascript pole kättesaadav/lubatud.
    23. Uute komponentide loomisel kasutame antd ja reacstrap pakette.
    24. Kasutajaliidese loomisel kasutame creat-react-app tööriistu (webpack, babel, eslint airbnb reeglitega).
Joonis 2.
  1. Veebiserver:
    1. EHR olemasolevas Java rakenduse infrastruktuuris kasutatakse Apache veebiserverit.
    2. Microteenuste loomisel kasutatakse eelkõige Nginx veebiserverit, mis on kasutusel uue rakenduse juurkomponendi serveerimiseks.
  1. Rakendusserver:
    1. Uute API-de loomisel kasutatakse kas Java( ver.11 Zulu), NodeJS (ver. 12)  või Python programmeerimiskeeli.
    2. Uue API rakendusserverid käitatakse Docker konteinerites riigipilves Kubernetes klastris.
    3. Kubernetes klastrite haldusvahendina kasutatakse Rancher tarkvara.
    4. Uue API rakendused peavad sisaldama automaattarne: MKM Git -> Riigipilves Helm Chart vajalikke Helm konfiguratsiooni faile (vt. näiteks Helm konfiguratsioonifaile ja Helm kasutusjuhendit).
    5. Automaattarne riigipilve lisatakse MKM Git-s projektidele, mis asuvad selles grupis.
    6. Helm Charti abil peab saama paigaldada rakendused Rancher App kaudu e-ehituse test- ja toodangu klastris olevatesse: development, test, prelive, live projektides asuvatesse namespace-desse.
    7. Olemasoleva Java rakenduse server (paikneb Tieto majutuses) jääb tööle, kuni olemasolev Java rakendus on kasutuselt maha võetud.
    8. Olemasolev kaardiserver jääb eraldiseisva teenusena tööle, kuni luuakse uued kaarditeenused. Olemasolev kaardiserver kasutab Maa-ameti kaarditeenuseid:
      1. Gazetteer
      2. ADS hoone SVG:
      3. ADS hoone WFS
      4. ADS hoone info: ?
      5. Kitsenduste ja KÜ info?
    9. Luuakse mikroteenuste kontseptsioonil baseeruv e-ehituse REST API. API kavandamiseks ja dokumenteerimiseks kasutatakse OpenAPI standardit ja Swagger tööriistu Swagger UI ja Swagger Editor. EHR API kavandamisel tuleb järgida EHR API kirjeldamise reegleid.
    10. E-ehituse REST API kirjeldus asub siin. Uue API loomisel tuleb API kirjeldus lisada siia projekti ning uus versioon tarnida riigipilve.
    11. E-ehituse API loomisel tuleb tagada, et teenused ei korduks ja soovitav on olemasolevat teenust edasi arendada, mitte luua uusi teenuseid. Teenused peavad olema vähemalt 2 põhiversiooni (semver2 ) tagasiulatuvalt ühilduvad.
    12. Andmete ülekandmiseks API-st kasutajaliidesesse kasutatakse võimalusel JSON formaati või eelneval kokkuleppel mõnda muud XML formaati (näiteks CityGML).
    13. E-ehituse kaardikomponendist ja geo-otsingu teenustest andmete vahetuseks kasutatakse GeoJSON formaati.
    14. Juhul, kui API teostab andmebaasis CRUD operatsioone (Create, Read, Update, Delete) , siis andmete verifitseerimine toimub kahel tasemel ehk esmalt UI vormi kasutajaliideses ja seejärel enne andmebaasi viimist API rakenduses.
    15. Teenuste autoriseerimine toimub vastavalt kasutajaõiguste süsteemi detailanalüüsile.
    16. Teenused, mis teostavad andmebaasidega CRUD operatsioone, tuleb luua nii, et transaktsioonid ning vajalikud Join operatsioonid toimuvad andmebaasis, kasutades andmebaasi protseduure, mitte API rakenduses.
    17. Andmete terviklikkuse tagamiseks andmebaaside üleselt kasutatakse võimalusel (juhul, kui saga pattern realiseerimine pole otstarbekas) kahetasemelist “commit” lahendust (2PC) lisades transaktsiooni koordineerimist vajavate teenuste üleselt uue “commit” teenuse või vajadusel mikroteenustes nn. “Choreography-based saga pattern” metoodikat. Message Brokerina on kasutusel RabbitMQ.
  1. Andmebaas:
    1. Olemasolev EHR Oracle andmebaas jääb kasutusele, kuni uute mikroteenuste andmebaasid on kasutusele võetud.
    2. Olemasolev andmeaida PostgreSQL andmebaas jääb kasutusele.
    3. Mikroteenuste vajadusteks luuakse uued PostgreSQL andmebaasid.
    4. Igal andmeobjektil on üks baas, kuhu andmed kirjutatakse ja vajadusel kasutada neid mõnes teises baasis JOIN-de teostamiseks luuakse teise baasi r prefiksiga view, mille abil andmeid saab lugeda. Andmete sünkroniseerimiseks andmebaaside vahel kasutatakse pglogical tarkvara.
    5. Olemasolev Oracle ja uued baasid hoitakse sünkroonis RabbitMQ sõnumiedastusega, kuni olemasolev Java rakendus on kasutusel.
    6. EHR unikaalvõtmete (EHR-kood, dokumendi number jm.) loomiseks kasutatakse koodide omistamise teenuseid.
    7. Andmebaasi operatsioonide teostamiseks luuakse SQL protseduurid, mida API-t realiseerivad komponendid välja kutsuvad.
  1. Failisüsteem:
    1. Konteinerakendustele on klastris kasutusel NFS block storage ja Longhorn block storage.
    2. Klastrites on kasutusel S3 Object storage teenus, mis on eelistatud failide hoidmise lahendus.
  1. Muud komponendid:
    1. Cache jaoks on kasutusel Redis. Redist saab rakendada vajadusel konteinerite vahel info jagamiseks või rakenduse andmete ajutiseks säilitamises kiires püsimälus.
    2. Pilve arhitektuuris kasutame nimelahendust (DNS). Vt. Eehitus DNS kirjeldus
  1. Mikroteenuste rakendustele tuleb lisada Kubernetes liveness probe.
  2. Uue teenuse loomisel kasutatakse võimalikult palju valmis arendatud komponente ja olemasolevaid raamistikke või teeke.
  3. E-ehituse teenused peavad arenduse käigus olema kaetud unit testidega, mille abil kontrollitakse teenuse komponentide (alamosade) vigadeta tööd. 
  4. Javascripti kasutamisel (React, NodeJs) peab tarnitav kood olema kontrollitud Eslint Airbnb reelitega ning ei tohi sisaldada linteri veateateid.
  5. Koodi kvaliteeti kontrollitakse CI/CD tarnetel Sonarqube tarkvaraga. Koodi Sonarqube raport peab olema:  
    1. Reliability Bug = 0
    2. Security Vulnerability = 0
  6. Rakenduse arendusel tuleb arvestada, et rakendus peab olema testitav Katalon automaattestidega ehk kasutajaliideses kasutatavad html elemendid peavad sisaldama unikaalset atribuuti näiteks id. Kasutajaliides peab olema testitud automaattestidega mobiilivaates ning toetatavate veebilehitsejate vaadetega. API peab olema testitud Katalon API testimiseks mõeldud testidega.
  7. Rakenduste logid kogutakse kesksesse logihalduse teenusesse ja seetõttu peavad rakenduste logid olema Json formaadis. Logiteenuse kirjeldus

Üleminekuprotsessi etapid

Etapid on toodud ajalises järgnevuses, aga samas on võimalik etappe ka paralleelselt käivitada juhul, kui selleks on olemas piisavalt ressursse. 

  1. Tarkvaralise arhitektuuri dokumenteerimine
  2. Olemasoleva EHR komponentideks jaotamine ja teenuste kavandamine (vt. järgmine ptk.)
  3. Automaattarnete ja testide käivitamine
  4. Teenuste kasutajaliidese arendamine (MTA UI + React)
  5. Turvateenuste arendamine: JWT – ehk teenustele juurdepääsu pass, autoriseerimise süsteem ehk kasutajad/grupid/rollid/juurdepääsuõigused, andmete turvalisuse ja juurdepääsu muudatused.
  6. Teenuste arendusprojektid, mille käigus arendatakse uus teenus ja muudetakse olemasolevat rakendust nii, et uue teenuse saab kasutusele võtta.

EHR olemasoleva rakenduse komponentideks jaotamine

Olemasoleva rakenduse teenusteks jaotamisel on aluseks EHR tänase rakenduse komponendid. Samuti tuleb komponentidena arvestada tänases EHR infrastruktuuris paiknevad eraldi rakendused:

  • andmeait,
  • EHR infoportaal,
  • VRM,
  • kaardirakendus.

Uue teenuse arendamisel tuleb järgida mikroteenuste põhimõtteid ehk teenuses peavad olema andmed, rakenduse server ja kasutajaliides nii, et EHR muude teenuste (va. elutähtsad teenused, mis on aluseks kõigi teiste teenuste toimimisele) katkestused ei mõjutaks ülejäänud teenuste tööd.

Teada olev EHR komponentide loetelu on kirjeldatud dokumendis Nõuded ehitisregistri arhitektuurile.

Kuna uute teenuste loomisel tuleb need integreerida olemasoleva rakendusega, siis tuleb olemasolevad EHR komponendid jaotada teenusteks arvestades olemasoleva rakenduse ülesehitust ja võimalusi nii, et uusi teenuseid saaks kasutusele võtta võimalikult vähe olemasolevat rakendust muutes. See võimaldab hoida kokku ressursse ning tagada lõppkasutajatele võimalikult sujuva ja probleemideta ülemineku protsessi.

E-ehituse tarneprotsess (tehnoloogia vaade)

E-ehituse teenuste tarkvaraline protsess on lahti kirjeldatud allpool olevas joonisel (vt. Joonis 3).

Uue tarkvara tarnimisel võetakse kasutusele konteineri põhine lähenemine. Selle protsessi realiseerimiseks kasutatakse järgmisi tarkvarasid:

  • GIT/GIT CI – kooditarnete tegemine (rakenduse kood, SQL-kood, docker paigaldusfailid, automaattestid). Tarne protsessi automaatne käivitamine. Kasutatakse tellija keskkonda
  • Docker – vastavalt GIT-is oleva infole konteinerite loomine ja levitus ( rakendus + andmebaas + rakenduse toimimiseks vajalik infrastruktuur). Docker-iga integreeritud tarkvarad :
    • Unit testid – arendaja poolt kirjutatud testid kontrollimaks EHR-i ja selle komponentide toimimist vastavalt nõuetele; 
    • Apache Maven   – Java koodi kompileerimine, 
    • SonarQube   – koodi kvaliteedi kontrolli teostamine,
    • Liquibase – andmebaasi loomine ja muutmine,
    • ArtifactoryJava artifaktide loomine ja konteinerite registreerimine,
    • Helm kaartide hoidla.
  • Kubernetes – konteinerite haldamine, skaleerimine ja koormuse jaotamine.
  • Katalon – EHR UI ja API testmine.
Joonis 3. E-ehituse platvormi tarneprotsess

Changelog

Versioon KuupäevAutorKommentaar
v905.03.2020Ülo Puskar, Kristjan KaiklemAlgversioon