Skip to content
ÚPadmin – webová aplikace pro projekt Úspěšný prvňáček
JavaScript Python Gherkin PLpgSQL CSS HTML Shell
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.idea [js] funkce pro skryti soukromych udaju klientu Aug 15, 2019
admin [api] automaticka uprava formatu barvy kurzu Aug 11, 2019
api [api] automaticka uprava formatu barvy kurzu Aug 11, 2019
docs [js+api+docs] stavy vychozi a omluven musi byt viditelne Aug 3, 2019
frontend [js] vystiznejsi noscript text Aug 15, 2019
scripts aktualizace vzorovych dat (dodani barvy kurzu) Aug 8, 2019
staticfiles nwb May 3, 2019
tests [testy][ui] dvojnasobne zrychleni testu upravy klientu Aug 12, 2019
up [python] zavedeni code formatteru pro python Black Aug 10, 2019
.behaverc [testy] zarovnani konfiguracniho souboru testu Aug 11, 2019
.codecov.yml [testy] vlastni konfigurace codecov Aug 11, 2019
.coveragerc oprava omit frontend slozky pro coverage Jan 26, 2019
.env.template prejmenovani .env.default na .env.template Aug 8, 2019
.gitignore odstraneni textu nacitani z html (aby fungovala animace), smazani aut… May 3, 2019
.travis.yml [ci] lepsi osetreni skriptu Aug 8, 2019
LICENSE [docs] pridani licence Jul 12, 2019
Pipfile [python] zavedeni code formatteru pro python Black Aug 10, 2019
Pipfile.lock [python] zavedeni code formatteru pro python Black Aug 10, 2019
Procfile [ci] na heroku se neprovadi collectstatic, travis smaze frontend slozku Aug 8, 2019
README.md [docs] code formatting badges Aug 13, 2019
lgtm.yml [lgtm] ignorace unused npm deps Aug 11, 2019
manage.py Initial commit Feb 26, 2018
package.json [ci] heroku oprava deploy Aug 6, 2019
pyproject.toml [python] zavedeni code formatteru pro python Black Aug 10, 2019
yarn.lock pri buildu uz se nevypise adresa webpackdevserveru May 4, 2019

README.md

Ú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

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 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 11.

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.

Frontend

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

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. Statickou typovou kontrolu má na starost Flow.

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 (JS, JSX, CSS, HTML), 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

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

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

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

$ mv .env.template .env

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

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

$ source scripts/shell/postgresql_cs.sh

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

$ pipenv install --dev
$ pipenv shell

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

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

💡 (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ými obdelníky jsou skryta jména klientů.

Diář

screenshot z diáře

Licence

Licencováno pod MIT.

Copyright (c) 2019 Lukáš Rod

You can’t perform that action at this time.