Reititys ja siirtymäajat – käyttöönotto (StarCura 1.9)

StarCura laskee kotihoidon hoitajan siirtymäajan käynnistä toiseen. Laskenta toimii aina ilman lisäpalveluja koordinaattien ja alueiden avulla. Versiossa 1.9 tarkkuutta voi parantaa kolmella valinnaisella palvelulla. Mitään ei lähde koneelta tai palvelimelta, ennen kuin pääkäyttäjä ottaa palvelun käyttöön tämän ohjeen mukaan.

1. Mistä siirtymäaika tulee

StarCura käyttää ensimmäistä tietoa, joka asiakasparille on olemassa:

Ruuhka- ja kausikertoimet kertovat ajan kaikissa vaihtoehdoissa. Asetukset ovat työnjohdon näkymässä: Reitit → Siirtymäajan asetukset.

Opittu siirtymä ei vaadi mitään käyttöönottoa. Havainto syntyy, kun hoitaja kuittaa käynnin valmiiksi ja aloittaa seuraavan. Jos seuraava käynti alkoi minuutin tarkkuudella suunniteltuun aikaan, hoitaja todennäköisesti odotti, eikä väliä käytetä. StarCura käyttää 90 päivän ajalta enintään 20 viimeisintä havaintoa ja niiden mediaania. Opittu aika otetaan käyttöön, kun havaintoja on vähintään asetettu määrä (oletus 3). Jos asiakkaan osoite, koordinaatit tai alue muuttuvat, vanhat havainnot jäävät pois.

2. Asetustiedosto ja avaimet

API-avaimia ja palvelimen osoitetta ei tallenneta StarCuran tietokantaan, koska tietokannan tapahtumaloki säilyttää jokaisen tallennuksen. Ne luetaan tiedostosta reititys.json, joka on samassa kansiossa kuin tietokanta:

Tiedoston sisältö (jätä pois ne rivit, joita et käytä):

{
  "osrmUrl": "http://127.0.0.1:5000",
  "mmlApiKey": "Maanmittauslaitoksen API-avain",
  "googleMapsKey": "Google Maps Platform -avain"
}

Palvelimella samat arvot voi antaa ympäristömuuttujina, jotka ohittavat tiedoston: STARCURA_OSRM_URL, STARCURA_MML_API_KEY ja STARCURA_GOOGLE_MAPS_KEY. Anna tiedostolle oikeudet vain StarCuran käyttäjälle (Linux/macOS: chmod 600 reititys.json). StarCura lukee tiedoston jokaisella kerralla, joten uudelleenkäynnistystä ei tarvita.

Turvarajat:

• Reitityspalvelimen osoite hyväksytään vain, jos se on https-osoite tai samalla koneella (127.0.0.1, localhost).
• Uudelleenohjauksia ei seurata, ja vastauksen koko on rajattu.
• Avaimet eivät näy käyttöliittymässä, rajapintojen vastauksissa, virheilmoituksissa eivätkä lokeissa.

3. Oma reitityspalvelin (OSRM)

OSRM laskee ajoajat OpenStreetMapin tieverkosta. Asiakkaiden koordinaatit pysyvät omalla palvelimella. Hakuja voi tehdä rajattomasti, ja tulokset saa tallentaa. Ainoa ehto on maininta "© OpenStreetMapin tekijät", jonka StarCura näyttää reittinäkymässä.

Muisti: koko Suomen aineisto (noin 735 Mt) vaatii laskennan aikana useita gigatavuja ja ajossa noin 1,5 Gt muistia. Yhden asiakkaan alueelle kannattaa rajata vain oma maakunta, jolloin ajo mahtuu StarCuran rinnalle 2 Gt:n palvelimelle.

Asennus kerran (Linux-palvelin, Docker). Komennot ajetaan yksi kerrallaan:

1. Lataa Suomen aineisto: wget https://download.geofabrik.de/europe/finland-latest.osm.pbf
2. Rajaa alue (esimerkki: Vaasan seutu, rajat muodossa länsi,etelä,itä,pohjoinen): osmium extract -b 20.9,62.6,22.4,63.5 finland-latest.osm.pbf -o alue.osm.pbf
3. Esikäsittele: docker run -t -v "$PWD:/data" ghcr.io/project-osrm/osrm-backend osrm-extract -p /opt/car.lua /data/alue.osm.pbf
4. docker run -t -v "$PWD:/data" ghcr.io/project-osrm/osrm-backend osrm-partition /data/alue.osrm
5. docker run -t -v "$PWD:/data" ghcr.io/project-osrm/osrm-backend osrm-customize /data/alue.osrm
6. Käynnistä vain paikallisesti kuunteleva palvelu: docker run -d --restart unless-stopped -p 127.0.0.1:5000:5000 -v "$PWD:/data" ghcr.io/project-osrm/osrm-backend osrm-routed --algorithm mld --max-table-size 100 /data/alue.osrm
7. Lisää "osrmUrl": "http://127.0.0.1:5000" tiedostoon reititys.json.

Esikäsittelyn (kohdat 3–5) voi tehdä myös omalla koneella ja siirtää valmiit alue.osrm*-tiedostot palvelimelle. Reitityspalvelinta ei saa avata internetiin. Portti 5000 kuuntelee vain osoitteessa 127.0.0.1.

Kartan päivitys: toista kohdat 1–5 noin kerran kuukaudessa ja käynnistä palvelu uudelleen. StarCura laskee yli 35 päivää vanhat ajoajat uudelleen itsestään. Työnjohto voi pyytää heti uudelleenlaskentaa painikkeella Laske ajoajat uudelleen.

StarCura hakee puuttuvat asiakasparit taustalla minuutin välein, enintään 50 × 50 parin lohkoissa. Jos palvelin ei vastaa, virhe näkyy asetuksissa ja uusi yritys tehdään 15 minuutin kuluttua.

4. Osoitehaku (Maanmittauslaitos)

Kun osoitehaku on käytössä, asiakkaan profiilissa on painike Hae koordinaatit osoitteesta. StarCura lähettää Maanmittauslaitokselle vain kirjoitetun osoitteen, ei asiakkaan nimeä. Työnjohto valitsee ehdotuksista oikean, ja koordinaatit tallentuvat vasta, kun profiili tallennetaan. Ehdotuksista näytetään vain Suomen alueella olevat.

Käyttöönotto:

1. Hae Maanmittauslaitoksen avoimien rajapintojen API-avain Maanmittauslaitoksen verkkosivuilta.
2. Tarkista geokoodauspalvelun hinnasto ja käyttöehdot. Palvelussa on laskutettavia hakuja.
3. Lisää "mmlApiKey" tiedostoon reititys.json.

5. Google-vertailu (valinnainen)

Google-vertailu tarkistaa valmiin päivän reitit Googlen liikennetietoa vasten: yksi haku hoitajaa kohden. Matriisihakuja ei tehdä. Googlelle lähetetään vain käyntien koordinaatit, ei nimiä, osoitteita eikä asiakastunnuksia. Tuloksia ei tallenneta. Tulokset näytetään merkinnällä "Google Maps", kuten Googlen ehdot edellyttävät.

Ennen käyttöönottoa:

1. Kirjaa Google-vertailu hoivatalon kanssa tehtyyn henkilötietojen käsittelysopimukseen ja tietosuojaselosteeseen. Kotihoidon asiakkaan sijainti on henkilötieto, joka kertoo hoivapalvelun käytöstä.
2. Luo Google Cloudissa laskutustili ja API-avain, salli avaimelle vain Routes API ja rajaa se palvelimen IP-osoitteeseen.
3. Lisää "googleMapsKey" tiedostoon reititys.json.
4. Työnjohto kytkee vertailun päälle yksikön siirtymäasetuksista ja vahvistaa käsittelysopimuksen. StarCura tallentaa, kuka vahvisti ja milloin.

Kustannus: liikennetiedon huomioiva reittihaku kuuluu Googlen Pro-tasoon (5 000 maksutonta hakua kuukaudessa laskutustiliä kohden). 10 hoitajaa × 30 päivää on noin 300 hakua yksikköä kohden kuukaudessa. Tarkista ajantasainen hinnasto Googlelta.

6. Mitä mikin palvelu saa tietää