TreeMap

Aktualni verze aplikace: 0.22.0 (bezici verzi ukazuje menu O aplikaci a /health).

Mobilni PWA pro mapovani lesa a stromu v terenu. V lesnickem rezimu eviduje jednotlive stromy, skladky dreva a porostni skupiny s vekovymi vrstvami, v arboristickem rezimu hodnoti stav stromu podle standardu SPPK A01 001 s opakovanymi prohlidkami a navrzenymi opatrenimi. Aplikace je navrzena tak, aby byla plne pouzitelna bez signalu - vsechno se uklada lokalne a na server se odesila, az kdyz je pripojeni.

Repozitar pro nasazeni:

https://tomlabscloud.visualstudio.com/TreeMap/_git/TreeMap

Vetve a nasazeni

Ostra verze bezi z vetve main: API, PostgreSQL a Docker Compose na VPS, nasazovane pipeline azure-pipelines.yml na treemap.cz (driv treemap.tomlabs.xyz, viz "Prechod na treemap.cz" nize).

Uvodni stranka a prihlaseni

Od verze 0.22 je aplikace jen pro prihlasene. Neprihlaseny navstevnik vidi uvodni stranku (#landing v app/index.html, app/styles/landing.css, app/src/features/landing.js). Co se ukaze, rozhodne skript v <head> podle ulozeneho session hintu jeste pred prvnim vykreslenim, takze nic neproblikne. Prihlaseni vydrzi i bez signalu, v terenu se tedy aplikace otevre rovnou. Bez prihlaseni zustava pristupny jen sdileny pohled (#share=); reset hesla a odkaz #new otevrou sve okno nad uvodni strankou a aplikace se ukaze po prihlaseni.

Prechod na treemap.cz

Od verze 0.21 je aktualni adresa https://treemap.cz (www.treemap.cz presmerovava na ni). Stara treemap.tomlabs.xyz zatim dal obsluhuje aplikaci, protoze prohlizec drzi data v telefonu zvlast pro kazdou domenu: tvrde presmerovani by neodeslane zaznamy a fotky zamklo na stare adrese.

• Deploy zalozi nginx a certifikat pro novou domenu. Dokud DNS neukazuje na VPS, certifikat nevznikne, aplikace zustane na stare adrese a deploy nespadne.
• Jakmile nova domena bezi, deploy nastavi PUBLIC_URL=https://treemap.cz a PUBLIC_URL_ALIASES=https://treemap.tomlabs.xyz.
• Appka na stare adrese se zepta GET /api/auth/domain. Kdyz v telefonu nic neceka na odeslani, rovnou prejde na novou adresu i s puvodnim odkazem (#share, #new, ...); prihlaseni prenese jednorazovym tokenem (POST /api/auth/handoff a /api/auth/handoff/redeem, plati 2 minuty). Jinak ukaze banner a pocka, az se vsechno odesle (app/src/features/domainmove.js).
• Odkazy v e-mailech a sdileci odkazy uz vedou na novou adresu. OAuth se vraci na tu adresu, odkud prihlaseni zacalo, proto musi u Googlu i Seznamu zustat registrovane obe callback adresy.
• Stazene offline mapy se prenest nedaji; appka po prechodu pripomene, at si je uzivatel stahne znovu.

Az stara adresa nebude mit navstevy (par tydnu), muze se jeji nginx konfigurace nahradit trvalym presmerovanim 301 na https://treemap.cz.

Do verze 0.7 mel projekt dve vetve: main se statickou verzi pro Azure Static Web Apps a vps-postgres s plnou verzi pro VPS. Staticke nasazeni bylo zruseno vcetne domeny treemapx.tomlabs.xyz, VPS verze se presunula na main a vetev vps-postgres zanikla. Puvodni statickou verzi najdes pod tagem archiv/staticka-verze-0.1.0.

Co aplikace umi

V terenu

• vyfotit strom mobilni kamerou nebo vybrat fotky z galerie (vic fotek na strom i na prohlidku) a ulozit jeho GPS polohu; fotky se prohlizi v galerii s listovanim a priblizenim
• zalozit stromy hromadne z fotek - aplikace precte GPS a cas primo z EXIF hlavicky fotek z galerie a zalozi strom na miste, kde vznikly
• vybrat polohu klepnutim do mapy
• zapsat druh, prumer nebo obvod kmene, vysku, stav a poznamku
• zalozit skladku dreva a prirazovat k ni pokacene stromy
• nakreslit porostni skupinu klepanim do mapy nebo obchazenim hranice s GPS, zadat rok zalozeni a videt porosty obarvene podle vekovych trid
• spocitat orientacni objem dreva v m3 podle tvaroveho koeficientu druhu
• filtrovat podle druhu a stavu, oznacit strom jako pokaceny
• otevrit polohu stromu nebo skladky v aplikaci Mapy.com v telefonu

Ci je to pozemek

Samostatna stranka /parcel (v menu pod "Katastr") najde podle GPS parcelu, na ktere clovek stoji, zvyrazni ji v mape a ukaze cislo parcely, katastralni uzemi a vymeru. Klepnutim do mapy jde vybrat jinou parcelu. Parcely vraci API GET /api/parcel?lat=&lng= z bezplatne INSPIRE WFS CUZK. Vlastniky zadne bezplatne API CUZK neposkytuje (API KN osobni udaje vynechava), proto tlacitko "Zobrazit vlastniky" otevre parcelu v Nahlizeni do katastru.

Arboristicky rezim

Kazdy projekt je bud lesnicky (vychozi), nebo arboristicky. Rezim se voli pri zalozeni projektu a jde zmenit v menu; nic se pri tom nemaze, jen druhy rezim neukazuje skladky nebo prohlidky. Ciselniky odpovidaji standardu SPPK A01 001 Hodnoceni stavu stromu (2018), cisla clanku jsou u poli ve formularich i v kodu (app/src/arbor.js).

• strom ma volny taxon vedeckym jmenem s naseptavacem ceskych i latinskych nazvu, cislo stromu (napr. ze stitku), vysku nasazeni a sirku koruny a pocet kmenu; u druhu je odkaz na Stromopedii
• prohlidka je samostatny zaznam s historii: datum, typ kontroly, kdo ji provedl, fyziologicke stari, vitalita, zdravotni stav, stabilita, perspektiva (predvyplni se z horsiho hodnoceni), provozni bezpecnost, povinny seznam staticky vyznamnych defektu, podezreni na zvlaste chranene druhy, fotka (povinna od stability 3) a termin dalsi kontroly
• ke kazde prohlidce libovolne mnoho opatreni s kodem technologie z Prilohy c. 9, nalehavosti 0 az 3, intervalem opakovani a specifikaci, ktera je u vyznacenych technologii povinna; provedena opatreni se odskrtavaji
• mapa barvi stromy podle nejnalehavejsiho otevreneho opatreni a stromy po terminu kontroly maji cerveny odznak; seznam filtruje „k zasahu“, „po terminu“ a „bez hodnoceni“
• porostni skupiny slouzi jako zakladni plochy s intenzitni tridou udrzby, celkovou stabilitou, cilem padu a sklonitosti; plocha upozorni, kdyz na ni chybi individualni hodnoceni stromu
• sestavy Protokol o kontrole (7.3.3) a Stromy k zasahu po etapach a karta stromu (udaje, fotky, mapa, QR kody, hodnoceni a historie) se skladaji v telefonu jako PDF i bez signalu (knihovna pdfmake je v app/vendor/pdfmake) a jdou stahnout nebo rovnou poslat
• export CSV a GeoJSON obsahuje posledni hodnoceni, nalehavost a termin kontroly

Prohlidky a opatreni se ukladaji do IndexedDB a odesilaji stejnou frontou jako ostatni zaznamy. Stav stromu (nalehavost, termin kontroly) se pocita v telefonu z prohlidek, takze prohlidka zapsana bez signalu se v mape projevi hned.

Mapove vrstvy

Vedle OpenStreetMap jsou k dispozici oficialni lesnicke vrstvy pres WMS:

• NLI / UHUL (OPRL): lesnicka typologie, lesni vegetacni stupne, cilove hospodarske soubory, ochrana lesa, ochrana prirody, zpristupneni lesu, provozni soubory, potencialni ohrozeni smrku klimatickou zmenou
• NLI / UHUL: kategorizace lesu
• CUZK: hranice parcel a parcelni cisla

Vek porostu ve verejnych sluzbach neni - je soucasti LHP a LHO, coz jsou data vlastnika lesa. Proto vekove vrstvy stoji na vlastnich kreslenych porostnich skupinach a WMS slouzi jako podklad.

Vsechny WMS sluzby jdou pres proxy v nasem API, ne primo z prohlizece. Duvody jsou dva: cross-origin dlazdice nejdou rozumne ulozit pro offline, a upstream URL se stehuji (UHUL se presunul z geoportal.uhul.cz na gp1.nli.gov.cz).

Offline

• kostra aplikace, mapove dlazdice i fotky jsou v cache prohlizece

• zaznamy porizene bez signalu se ukladaji do IndexedDB a cekaji ve fronte

• fronta se odesle sama, jakmile je server dostupny; aplikace to zkousi i sama od sebe, protoze udalost online v terenu casto neprijde

• v menu je Stahnout tuto oblast, ktera ulozi dlazdice zobrazeneho vyrezu pro pozdejsi praci bez signalu

  OpenStreetMap hromadne stahovani dlazdic zakazuje, takze podklad OSM se uklada jen postupne tim, jak mapu prochazis. Lesnicke vrstvy stahnout lze.

Ucet a sdileni

• prihlaseni e-mailem a heslem, volitelne pres Google nebo Seznam
• overeni e-mailu, reset zapomenuteho hesla, zmena hesla
• prehled prihlasenych zarizeni a moznost je odhlasit
• presun stromu do jineho projektu nebo podprojektu i s prohlidkami, opatrenimi a fotkami (potrebuje signal)
• rozdeleni zaznamu do vice projektu; vlastnik muze projekt smazat (nazev je treba opsat, serverovy projekt jde smazat jen se spojenim)
• sdileni projektu odkazem jen pro cteni
• sdileni jednoho nebo nekolika stromu vlastnim odkazem (napr. pro zadost o povoleni kaceni): odkaz ukaze jen vybrane stromy s prohlidkami, opatrenimi a fotkami a jde kdykoli zrusit. Ma stejny tvar #share=<token> a stejnou odpoved GET /api/shares/<token> jako sdileni projektu (scope je "trees"), takze ho boudakaci.cz cte beze zmeny

Podprojekty: projekt jde zaradit pod jiny projekt (jedna uroven), typicky jedna zakazka pod "Zakazky". V menu je podprojekt zanoreny pod nadrazenym projektem (rozbaleni se pamatuje v telefonu), na projektu nejvyssi urovne je "Novy podprojekt" a u projektu "Presunout pod…". Podprojekt pri zalozeni prevezme rezim a cleny nadrazeneho projektu, jinak je to bezny projekt s vlastnimi zaznamy, synchronizaci i sdilenim; mapa nadrazeneho projektu zaznamy podprojektu neukazuje. Podprojekty existuji jen na serveru (vyzaduji prihlaseni), smazani nadrazeneho projektu je nemaze, jen z nich udela samostatne projekty.

Prihlaseni neni podminkou pouzivani. Bez uctu vsechno funguje lokalne a data zustanou v prohlizeci; po prvnim prihlaseni se prevedou na server.

Integrace s boudakaci.cz

Administrace boudakaci.cz otevira pro kazdou zakazku projekt v TreeMapu a cte z nej stromy pres sdileci odkaz. Spojuji to dva mechanismy:

Hluboky odkaz na zalozeni projektu

https://treemap.cz/#new?name=<nazev>&parent=<id nadrazeneho projektu>&return=<https URL administrace>

Vsechny hodnoty jsou URL-encoded. parent je volitelne UUID projektu, pod ktery se ma podprojekt zaradit (prijme i presny nazev projektu nejvyssi urovne); kdyz neni dostupny, projekt se zalozi samostatne. return je volitelna navratova adresa. Po otevreni odkazu prihlaseny uzivatel dostane novy projekt (nebo se otevre existujici projekt stejneho nazvu pod stejnym rodicem, aby opakovane kliknuti nezakladalo duplicity), projekt dostane sdileci token a navratova adresa se zapamatuje pro tuto relaci prohlizece (sessionStorage). Neprihlaseny uzivatel je vyzvan k prihlaseni a odkaz pokracuje po nem, vcetne prihlaseni pres Google nebo Seznam.

Navrat do administrace

Dokud je navratova adresa zapamatovana, projekt ukazuje v mape tlacitko "Zpet do administrace". To presmeruje na

<return>?share=<token>

(k existujicimu query stringu se share pripoji pres &). Administrace si token ulozi jako sdileci odkaz: cely odkaz ma tvar https://treemap.cz/#share=<token> a data vraci GET https://treemap.cz/api/shares/<token> beze zmeny tvaru odpovedi. Odkazy na treemap.tomlabs.xyz funguji dal, appka je presmeruje. Jako navratova adresa se prijima jen https na hostech ze seznamu RETURN_HOSTS v app/src/config.js (boudakaci.cz, lokalne localhost); jina adresa se ignoruje a tlacitko se neukaze.

Lokalni spusteni

Samotny frontend bez API:

node dev-server.js

Aplikace pobezi na http://127.0.0.1:8091. Kamera a GPS funguji jen na localhost nebo pres HTTPS.

Frontend proti bezicimu API (dev server preposila /api):

API_TARGET=http://127.0.0.1:3000 node dev-server.js

API lokalne:

cd api
npm install
export DATABASE_URL=postgres://treemap:heslo@127.0.0.1:5432/treemap
export JWT_SECRET=$(openssl rand -base64 48)
export COOKIE_SECURE=false
npm run migrate
npm start

COOKIE_SECURE=false je pro lokalni HTTP nutne, jinak prohlizec prihlasovaci cookie neulozi.

VPS nasazeni

Bezne se nasazuje pipeline, rucni postup nize je zaloha pro pripad, ze je Azure DevOps nedostupny.

Release pipeline

Pipeline azure-pipelines.yml se spousti pri pushi do vetve main a ma dve faze:

1. Build - kontrola syntaxe vsech modulu, shoda verzi mezi app/src/config.js, app/sw.js a api/package.json, overeni, ze vsechny soubory ze seznamu service workeru existuji, kontrola, ze migrace neobsahuji destruktivni prikazy, a sestaveni obrazu API.
2. DeployVps - nahraje release na VPS a spusti deploy/deploy-vps.sh, ktery zalohuje databazi, spusti migrace, nahodi stack, obnovi nginx a pocka na zdravou odpoved API. Nakonec probehne kourova zkouska proti verejne domene.

Variable group se jmenuje treemap-vps-deployment. Povinna je jen jedna polozka:

Volitelne polozky. Kdyz je nevyplnis, hodnota v .env na serveru zustane, jak byla, takze pipeline nikdy neprepise rucne nastavenou konfiguraci prazdnou hodnotou:

PUBLIC_URL, PUBLIC_URL_ALIASES, TREEMAP_DOMAIN a COOKIE_SECURE se neptaji - deploy skript je odvodi z domeny, protoze jsou vzdy znama a nejsou to tajemstvi.

Skript jde spustit i rucne primo na serveru:

bash /opt/treemap/deploy/deploy-vps.sh

Rucni prvni nastaveni

Repo obsahuje Docker Compose stack:

• api: Node.js TreeMap API
• postgres: PostgreSQL databaze
• hostitelsky Nginx: HTTPS reverse proxy a staticky frontend

Na serveru naklonuj repozitar a priprav .env podle .env.example:

sudo mkdir -p /opt/treemap
sudo chown $USER:$USER /opt/treemap
git clone -b main https://tomlabscloud.visualstudio.com/TreeMap/_git/TreeMap /opt/treemap
cd /opt/treemap
cp .env.example .env
nano .env

Povinne polozky:

TREEMAP_DOMAIN=treemap.tvoje-domena.cz
PUBLIC_URL=https://treemap.tvoje-domena.cz
POSTGRES_PASSWORD=dlouhe-nahodne-heslo
DATABASE_URL=postgres://treemap:dlouhe-nahodne-heslo@postgres:5432/treemap
JWT_SECRET=opravdu-dlouhy-nahodny-secret

JWT_SECRET musi mit aspon 32 znaku. API zamerne nenastartuje, pokud chybi nebo je to jedna ze znamych vychozich hodnot - drive se v takovem pripade tise pouzil verejne znamy default, cimz sel podepsat cizi token. Vygenerujes ho treba takto:

openssl rand -base64 48

Nginx konfigurace je v deploy/nginx-treemap.conf:

sudo cp deploy/nginx-treemap.conf /etc/nginx/conf.d/treemap.cz.conf
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d treemap.cz -d www.treemap.cz

Po vydani certifikatu uz tento soubor rucne neprepisuj, Certbot do nej doplni HTTPS cast.

Prvni spusteni:

sudo docker compose build api
sudo docker compose up -d postgres
sudo docker compose run --rm api npm run migrate
sudo docker compose up -d

Overeni:

sudo docker compose ps
curl http://127.0.0.1:3009/api/health
curl -H "Host: treemap.tvoje-domena.cz" http://127.0.0.1/api/health

Aktualizace po dalsim pushi:

git pull
sudo docker compose build api
sudo docker compose run --rm api npm run migrate
sudo docker compose up -d

Prechod z verze 0.6 na 0.7

Fotky se drive ukladaly jako base64 primo v radku stromu. Ve verzi 0.7 jsou to soubory na disku a v databazi zustava jen odkaz. Prevod stavajicich fotek udela jednorazovy skript, ktery je mozne spustit vickrat:

sudo docker compose run --rm api npm run migrate:photos

Fotky a cache dlazdic zijou ve svazku treemap_data (/var/lib/treemap v kontejneru), takze prezijou prestaveni kontejneru.

Prihlaseni pres Google a Seznam

Volitelne. Bez vyplnenych udaju se prislusna tlacitka v aplikaci vubec nezobrazi a prihlaseni e-mailem funguje dal.

U poskytovatele zaregistruj aplikaci a nastav redirect URI:

https://treemap.tvoje-domena.cz/api/auth/oauth/google/callback
https://treemap.tvoje-domena.cz/api/auth/oauth/seznam/callback

Ziskane hodnoty dej do .env (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, SEZNAM_CLIENT_ID, SEZNAM_CLIENT_SECRET).

Odchozi posta

Take volitelne. Posta jde primarne pres Resend (RESEND_API_KEY), odesilatel je v EMAIL_FROM a jeho domena musi byt v Resendu overena. SMTP (SMTP_HOST, SMTP_USER, SMTP_PASSWORD, ...) zustava jako zalozni cesta, kdyz Resend neni nastaveny nebo selze.

Bez Resendu i SMTP se overovaci a resetovaci odkazy vypisuji do logu kontejneru, takze registraci i reset hesla lze projit i bez posty:

sudo docker compose logs -f api

Zaloha

Databaze:

mkdir -p backups
sudo docker compose exec -T postgres pg_dump -U treemap treemap > backups/treemap-$(date +%F).sql

Fotky:

sudo docker run --rm -v treemap_treemap_data:/data -v "$PWD/backups:/backup" \
  alpine tar czf /backup/treemap-fotky-$(date +%F).tar.gz -C /data photos

Vypocty

Objem kmene je orientacni:

objem = vyska * pi * (prumer / 2)^2 * tvarovy koeficient

Prumer se zadava v cm, vyska v m, tvarovy koeficient se lisi podle druhu.

Vymera porostni skupiny se pocita ze skutecne geometrie polygonu pres sferickou excesi, a to na serveru - hodnote poslane klientem se neveri.

Vek porostu je rozdil aktualniho roku a roku zalozeni. Vekove tridy jsou po dvaceti letech, vekovy stupen podle lesnicke praxe po deseti.