Skip to content

Latest commit

 

History

History
361 lines (282 loc) · 18.5 KB

README.md

File metadata and controls

361 lines (282 loc) · 18.5 KB
Raw

ÚPadmin logo

ÚPadmin

Webová aplikace pro projekt Úspěšný prvňáček.

Travis (.com) Codecov GitHub license GitHub release GitHub commits since latest release
LGTM Alerts LGTM Grade LGTM Grade
Code style (js): prettier Code style (python): black
GitHub deployments GitHub deployments GitHub deployments

Sentry · Heroku · Slack · Google Analytics · Logentries – produkce / staging / testing

Obsah

Základní informace o aplikaci

Aplikaci jsem vytvořil v roce 2018 v rámci bakalářské práce na FIT ČVUT – vizte repozitář s textem bakalářské práce. Od té doby je v projektu Úspěšný prvňáček denně úspěšně používána a její rozšiřování a práce na ní stále pokračují ❤️.

Klíčové funkce aplikace

  • evidence klientů a skupin klientů docházejících na lekce kurzů
  • evidence lekcí klientů a skupin včetně předplacených – stav účasti, platba, datum, čas, zrušení, poznámky
  • evidence zájemců o kurzy
  • zobrazení lekcí ve 3 formách: v kartě klienta/skupiny, v diáři a na hlavní stránce v přehledu pro dnešní den
  • kontrola časových konfliktů lekcí
  • automatické rušení lekcí když nikdo nemá přijít
  • automatické vytváření předplacených náhrad lekcí při omluvě předem
  • upozornění, že má klient příště platit
  • konfigurace kurzů a stavů účasti včetně např. intuitivního nastavení zvolené barvy pro kurz
  • propojení s API Fio banky – na hlavní stránce se přehledně zobrazují nedávné transakce z účtu
  • automatický odhad kurzu pro nově přidávané lekce
  • respektování a kontrola všech omezení daných danou doménou (např. duplicity apod.)
  • automatické přidání předplacené lekce při omluvě/zrušení lekce ze strany lektorky
  • funkce pro vedení aktivních a neaktivních klientů a skupin
  • ... (výčet není konečný)

Použité technologie

Aplikace je rozdělena na frontend a backend, ty spolu komunikují přes REST API zabezpečené JWT autentizací. Jako databáze se používá PostgreSQL 12.

Poznámka: součástí repozitáře je také diagram nasazení a logický datový model – viz docs/README.md.

Backend

Obsahuje veškerou logiku a pro klienta vystavuje REST API, postaven na těchto technologiích:

V Djangu jsou pro mnohonásobné zrychlení pokročile optimalizované komplexní SQL dotazy (viz články [1], [2]). Aplikace umožňuje pokročilé debugování na lokálním i vzdáleném prostředí díky Django Debug Toolbar a jeho doplňku Django Debug Toolbar Request History. Pro eliminaci mrtvého kódu se také používá vulture.

Frontend

Responzivní JS (Typescript) webová aplikace typu SPA (Single-Page-App) postavená na těchto technologiích:

Vývoj frontendu je postaven především na:

Aplikace je odolná proti pádům JS díky React Error Boundaries. Pro zrychlení načítání celé aplikace se používá lazy loading React.lazy + React Suspense. Webpack DevServer je při vývoji propojený s Django dev serverem a umožňuje tak jednoduchý vývoj bez kompromisů včetně HMR.

Informace o nasazených aplikacích

Aplikace aktuálně běží na 4 prostředích (3x PaaS Heroku), které se liší příslušnou nasazenou verzí aplikace, konkrétní instancí databáze, umožňují různé úrovně debugování a kosmeticky se liší také barvou menu.

Seznam prostředí:

  • vývojové (lokální) – pro lokální vývoj (žluté menu),
  • testing – umožňuje zapnout debugování, deploy každého commitu (modré menu),
  • staging – stejná verze aplikace jako na produkci, deploy při release (zelené menu),
  • produkce – produkční verze používaná zákazníkem, deploy při release (jako staging) (bílé menu).
  • Nasazené aplikace jsou HTTPS-only (+ pokročilé zabezpečení, viz [1], [2]).
  • Na produkci se každý den ve 3:00 provádí automatická záloha databáze.
  • Pro automatické formátování kódů se používá Black (Python) a Prettier (TS, TSX, JS, CSS, HTML, JSON, YAML, TOML, MD), oba nástroje jsou napojené na IDE a provádějí automatické úpravy.
  • Aplikace jsou napojené na další služby:
    • CI a CD má na starost Travis – automatizovaný build, testování i nasazení na různá prostředí, automaticky prováděné pokročilejší skripty např. pro automatické zapsání verze do aplikace, práci s tokeny, nahrání sestaveného frontendu do assetů k releasu na GitHubu, napojení na služby pro výpočet pokrytí kódu a další.
    • Automatickou průběžnou analýzu a kontrolu kódu včetně hodnocení kvality kódu, hledání potenciálních chyb a zranitelností má na starost LGTM.
    • Logování z Heroku se zasílá do Logentries (logy se uchovávají po 7 dnů, tříděné podle typu prostředí).
    • Odchytávání chyb na backendu i frontendu včetně následné evidence, notifikací a propojení s repozitářem zařizuje Sentry (tříděné podle typu prostředí, aktivní na produkci, testing i staging prostředí). Při chybě na frontendu je možné poslat zpětnou vazbu vázanou ke konkrétní chybě díky propojení Sentry a React Error Boundaries.
    • Sledování chování a návštěv umožňuje napojení na Google Analytics (díky modulu react-ga).
    • Slack
  • Aplikace respektuje standardy PEP 8, 12-Factor App, ROCA.
  • Kompletní vývoj aplikace probíhá v IDE Pycharm (Professional Edition) (řeší například automatickou optimalizaci importů, automatické formátování kódů apod.).
  • Základ aplikace tvoří rozsáhlé testy API i frontendu, které se automaticky spouští na CI a lze je spustit i na lokálním prostředí.
    • Testování je postaveno na BDD frameworku behave – testové scénáře jsou psány přirozeným jazykem, podle nich se spouští konkrétní testy.
    • Pro testování UI se používá Selenium.
    • Podrobné informace o testech jsou v tests/README.md.

Struktura repozitáře

├── .idea ........ nastavení pro IDE (Pycharm od Jetbrains)
├── admin ........ Django aplikace pro samotnou webovou aplikaci
├── api .......... Django aplikace pro API
├── docs ......... další dokumenty a soubory k aplikaci včetně diagramů
├── frontend ..... klientská část webové aplikace
├── scripts ...... skripty pro CI/CD/instalaci
├── staticfiles .. složka pro statické soubory (prázdná, přesun až na CI)
├── tests ........ kompletní testy API i UI (frontendu)
└── up ........... celý Django projekt

Jak spustit aplikaci

Aplikaci lze spustit na lokálním prostředí ve dvou režimech, výchozí je klasický vývojový – ten obsahuje pokročilé debugovací nástroje, spouští se Django vývojový server a také webpack-dev-server pro frontend. Vzhledem k práci s privátními npm registry (viz níže) nelze samozřejmě bez příslušných tokenů sestavovat frontend, proto zde budu popisovat postup spuštění ve druhém režimu – produkční verze aplikace, tedy ta, která je nejblíže verzi u zákazníka.

Požadavky

Pro spuštění je potřeba mít v OS nainstalováno:

Poznámka: Node.js ani NPM/Yarn nejsou požadovány, protože ve vlastním prostředí nelze frontend sestavit (je potřeba přístup přes token k privátnímu npm registru pro FontAwesome PRO). Místo toho zde použijeme automaticky sestavenou poslední produkční verzi frontendu z integračního serveru (která se automaticky nahrává do assetů ke každému release).

Instalace

Pokud už požadavky výše splňujete, můžeme se vrhnout na instalaci.

  1. Nejdříve naklonujeme repozitář, otevřeme jeho složku a nahrajeme si poslední produkční verzi repozitáře:

    $ git clone "https://github.com/rodlukas/UP-admin.git" && cd UP-admin

$ git fetch --tags
$ latestRelease=$(git describe --tags `git rev-list --tags --max-count=1`)
$ git checkout $latestRelease

  2. Stáhneme již sestavené zdrojové kódy frontendu z poslední produkční verze a rozbalíme je přímo do repozitáře (a frontend.zip smažeme):

    $ wget https://github.com/rodlukas/UP-admin/releases/latest/download/frontend.zip
$ unzip frontend.zip && rm frontend.zip

  3. Přejmenujeme vzorový konfigurační soubor .env.template v kořenovém adresáři na .env:

    $ mv .env.template .env

  4. Spustíme psql CLI, kde pomocí dvou příkazů vytvoříme databázi a uživatele pro přístup do databáze, na závěr ukončíme CLI:

    $ sudo -u postgres psql

postgres=# CREATE USER up WITH ENCRYPTED PASSWORD 'up';
postgres=# CREATE DATABASE up WITH OWNER up;
postgres=# exit

  5. Nahrajeme český balíček pro databázi (kvůli českému řazení podle abecedy):

    $ source scripts/shell/postgresql_cs.sh

  6. Nainstalujeme všechny závislosti pro backend a aktivujeme virtuální prostředí Pythonu:

    $ pipenv install --dev
$ pipenv shell

  7. Připravíme celou Django aplikaci na spuštění (skript nastaví výchozí soubor s nastavením Djanga, připraví statické soubory frontendu pro nasazení a vytvoří databázové schéma):

    $ source scripts/shell/release_tasks.sh

  8. A vytvoříme uživatelský účet pro přístup do aplikace (zadáme libovolné údaje, kterými se poté budeme přihlašovat):

    $ python manage.py createsuperuser

  9. 💡 (NEPOVINNÉ) Na závěr můžeme ještě naplnit naší databázi předpřipravenými vzorovými daty, která ukážou fungování aplikace a usnadní první použití (obsahují několik klientů, skupin, lekcí, zájemců, kurzů a stavů účasti) – po zadání příkazu je vyžadováno heslo databázového uživatele up, které jsme nastavili taktéž up:

    $ psql --dbname up -h localhost -U up -f scripts/sql/sample_data.pgsql

Spuštění

Spustíme vývojový server 🚀:

$ python manage.py runserver 0.0.0.0:8000

✅ Aplikace je nyní dostupná na adrese http://localhost:8000/.

Poznámka: otevření aplikace na jiném zařízení v síti

Aplikace je připravena také na zobrazení z dalších zařízeních v síti (např. z mobilního telefonu). Obvykle je potřeba provést tyto 2 kroky:

  1. povolit Python a Node.js ve firewallu (např. na chvíli aktivovat interaktivní režim ESETu),
  2. na mobilním zařízení zadat hostname nebo privátní IP adresu počítače, na kterém běží server.

Testování

Můžeme také snadno spustit různé testy aplikace, například otestovat, jestli správně funguje API pro klienty:

$ python manage.py behave --stage=api --tags=clients

Aplikace obsahuje rozsáhlé API a UI testy – vizte podrobné informace o testech a možnostech spouštění.

Screenshoty z aplikace

Poznámka: modré/černé obdelníky skrývají citlivé údaje.

Diář

screenshot z diáře

Karta klienta

screenshot z karty klienta

Zájemci o kurzy

screenshot ze zájemců o kurzy

Licence

Licencováno pod MIT.

Copyright (c) 2020 Lukáš Rod